# Analysis document review (`/multi-agent:review-analysis`) > Reviews a written analysis the way `/multi-agent:review` reviews a diff. Loaded on demand. Read-only: no branch, no worktree, no commit, and the source document is never edited in place. `/multi-agent:review` answers "is this code right". This answers "could an implementer build the thing from this document, and does the document keep the promises its own contract makes". The two are different questions with the same failure mode: a reviewer who has opinions instead of rules produces findings nobody can act on. So this flow cites `Locked ` the way a code review cites a rule ID. ## Phase 0 - Resolve the document `$ARGUMENTS` is one of: | Input | Resolution | |---|---| | A local path | Read it. | | A Confluence page URL or `pageId` | Fetch read-only through `$HOME/.claude/multi-agent-refs/channels/confluence.md`. Record `pageId` and page version - the review is about a specific version, and Confluence pages move under you. | | A Jira key | Fetch the issue, then follow its analysis link. If the issue carries the analysis in its description or a comment, review that text and say which it was. | | Nothing | Offer the most recent documents from `~/Desktop/multiAgentAnalysis/` and from `analysis/` in each selected repo, newest first, and single-select one. | Fetch failures are reported and stop the run. Reviewing a document you could not read is the one outcome worse than not reviewing it. ## Phase 1 - Deterministic gates first Run the machine checks before the model reads anything, and report their output verbatim. A finding a script already proves does not need a model's opinion, and a model that reads the document first tends to argue with the script afterwards. ```bash node "$HOME/.claude/scripts/validate-analysis-doc.mjs" "" # when the run's state JSON is available (a fresh analysis, or --state ): node "$HOME/.claude/scripts/build-references.mjs" "" --check "" ``` `validate-analysis-doc.mjs` reads `profile` from the front-matter and applies the matching contract, so the corporate backbone and the global omission rule are each judged by their own rule. Its ERRORs are Blockers in this review, its WARNs are Important unless the document states why the warned-about thing is deliberate. **No state JSON, no references gate.** Say so in the report rather than passing silently: the coverage claim ("every source the run read is listed") is exactly the claim nobody can verify from the document alone, and marking it unchecked is the honest output. ## Phase 2 - Rubric Parallel model review, same shape as `/multi-agent:review`: 2 models on Claude Code, 3 on Copilot CLI, then triage. Each reviewer answers the rubric below against the resolved profile and returns findings with `Locked ` or a rubric id, a quote from the document, and what a reader cannot do because of it. **A. Buildability** - could an implementer start from this alone? - Every screen, state and error path the feature needs is described somewhere, not assumed. - Each business requirement or rule is testable: two readers cannot disagree about whether it passed. - Nothing important is deferred to a conversation the reader was not in. **B. Evidence** (Locked 3, 4, 34) - Every quoted string, endpoint, status code and event name carries a citation. - Nothing in a forward-looking section is actually a description of the current code. - References carry their precision anchors, and a source that could not be fetched is listed as unreachable rather than dropped. **C. Spine** (Locked 31 global, Locked 33 corporate) - Global: every `BR-` id reaches an acceptance criterion and a test row. - Corporate: every `IG` is realised by a `UC`, every `FG` names a source that exists, and the traceability matrix agrees with the sections. The matrix half is already machine-checked in Phase 1; the reviewer judges whether the chain is *meaningful*, not merely present. **D. Altitude** - Part A carries no technology name, Part C carries no business rationale. A row that is unclear in two layers at once is two rows. **E. Gaps that were admitted** - every `EKLENECEK` and every unverified assumption has an open question naming who can answer it. A gap with an owner is a plan; a gap without one is a defect. **F. Contradiction** - the document does not say two different things in two places. This is the finding class a human reviewer misses most, because it needs the whole document held at once. ## Phase 3 - Triage and verdict Fable triages the pooled findings exactly as in `/multi-agent:review`: drop duplicates, drop what the document already answers elsewhere, and keep the rest at one of three severities. | Severity | Meaning | |---|---| | Blocker | An implementer would build the wrong thing, or could not start. Deterministic-gate ERRORs land here. | | Important | The document is right but a reader will need a conversation to use it. | | Suggestion | Clarity and consistency. Never a style preference dressed as a defect. | The verdict names the profile it judged against, the counts per severity, and what was NOT checked (the references gate without a state file, anything the fetch could not reach). Follow the pipeline rule on claiming: state which findings are mechanically proven and which are judgement. ## Phase 4 - Output Default is the chat report. Nothing is written anywhere without an explicit choice. | Target | Behaviour | |---|---| | Chat only | Default. | | Confluence comment | A comment on the reviewed page, never an edit of the page body. The document belongs to its author; a reviewer who rewrites it has removed the choice to disagree. | | Jira comment | Comment only, per `channels/issue-comment.md`. The description is never touched. | | Local file | `/-review.md` beside the document, so the review travels with what it reviewed. | `/multi-agent:analysis-resolve` is the companion that acts on the findings: this command says what is wrong, that one walks the open questions and folds the answers back into the document. Say so in the report when the verdict has open questions, so the reader knows the next command rather than editing by hand. Non-negotiables: report body follows `prefs.global.outputLanguage`; humanizer punctuation policy (Locked 7) applies to anything posted to a channel; no AI attribution anywhere; no status change, no assignment, no page edit, no commit.