# 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 <n>` 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" "<doc>"
# when the run's state JSON is available (a fresh analysis, or --state <path>):
node "$HOME/.claude/scripts/build-references.mjs" "<state>" --check "<doc>"
```

`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 1.5 - What did the run skip?

Ask this before rubric quality. A document can be well-formed and still be wrong
because the run never looked. Every row here is a finding class observed in a real run.

| Skip class | Evidence it happened |
|---|---|
| A declared-missing input nothing searched for | `evidence.fetchErrors[]` has no entry for it and the document cites no scan |
| An open question about evidence never read | a Section 20 row names a node, page or file with no extracted content behind it |
| A gap with no owner | `EKLENECEK` with no `AS-NN`, or an `AS-NN` naming nobody |
| A scope call made without asking | the document narrows what the request asked for and no picker answer records it |

A skip is blocking, not advisory: the fix is a search or a question, and both are
cheaper before publication than a correction after it. Report each with what should
have been searched, so Phase 3.3 can put it in the right bucket.

## Phase 2 - Rubric

Parallel model review, same shape as `/multi-agent:review`: 3 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 <n>` 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.

**Every rubric class is printed, including the empty ones.** A verdict that lists only the classes that fired says nothing about the rest: the reader cannot tell "checked, clean" from "never looked". Print A through F in order with a count each, and write `none` where the count is zero. Same rule for the deterministic gates: name each one and its verdict, including the ones that skipped and why.

**Colophon.** Close the verdict with the reviewed document's `evidence_digest` and `base_commit`, taken from its front-matter, plus the reviewer models used. Two reviews of the same feature on the same day are otherwise indistinguishable, and the first question anyone asks of an older verdict is which version of the document it judged. `validate-analysis-doc.mjs --report` prints the per-check verdicts to paste under it.

```
Verdict: 2 Blocker, 3 Important, 1 Suggestion   (profile: global, mode: full)

  A evidence          2      D altitude          none
  B backbone          none   E admitted gaps     1
  C ...                      F contradiction     3

Not checked: references coverage (no state file passed)
Provenance:  evidence_digest sha256:1f3a9c2   base_commit 4c1b2de
```

## 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 | `<doc-dir>/<doc-name>-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.