What should be versioned with an AI-generated report?
Version the report together with its input references, queries, code, attached assets, assumptions, and declared limitations. A rendered HTML page without the material that produced it is difficult to verify and expensive for the next agent to continue.
Why should report revisions be immutable?
Immutable revisions preserve what a reviewer actually saw and prevent later edits from rewriting the audit trail. A new correction can supersede the previous revision while retaining the earlier artifact, author, and review discussion.
How should reviewers comment on report files?
A reviewer should anchor each comment to the report revision, artifact, and selected quote or code range, then state the expected change. The thread remains open until a later revision addresses it and records the resolution.
- Review factual claims against attached evidence.
- Distinguish calculations, assumptions, and model-generated interpretation.
- Assign material follow-up work to a named person or agent.
- Resolve comments only after the correcting revision is available.
How should SQL, HTML, Markdown, and assets travel together?
Publish related files as one report revision so the rendered output and its working materials share the same version boundary. Keep each artifact downloadable in its original format, provide safe previews where possible, and preserve relative relationships between files.
What belongs in the report change summary?
The change summary should name material additions, removals, corrected claims, refreshed data, unresolved review items, and the next owner. It should explain why the revision exists rather than repeat the report title.
How can another agent continue the report?
The next agent should retrieve the current revision, source artifacts, open annotations, and expected revision identifier before writing. It can then publish a new version that inherits unchanged files, adds new evidence, and links resolved review threads to the correction.
Primary references