# analysis check / refresh - is the document still true to its sources

`/multi-agent:analysis check <doc.md>` and `/multi-agent:analysis refresh <doc.md>`
answer one question after a document was written: did the design, the pages or
the API it was built from move, and does that matter. Both stay inside the
analysis family, so they are the only places besides the analysis run itself
that read Figma (Locked 29).

## The fingerprint is written at emit

`scripts/analysis-sources.mjs fingerprint --state <state.json> --write --sidecar <doc>.sources.json`
runs once per emitted document, before Section 21 is built. For each source in
`analysisSpec.evidence` it records the source's own version and a hash of the
part the document uses:

| Source | Version | Hash of |
|---|---|---|
| Figma | file `version`, `lastModified` | the cited node's document tree |
| Confluence | page version number | the page body |
| API spec | none | the whole spec, plus the operations of the endpoints the document cites |

`--write` stores them in `analysisSpec.sourceVersions` and copies the Figma and
Confluence versions onto their evidence rows, so Section 21 shows
`node-id=<id> v<version> (<date>)`. `--sidecar` writes the locators and the
fingerprints beside the document, and nothing else: no fetched content, no
token. The sidecar is what makes `check` work on another day and another
machine, without the run's state.

## check: read only

```bash
node "$HOME/.claude/scripts/analysis-sources.mjs" check --state "<doc>.sources.json" \
  --doc "<doc.md>" --repo "<repo>"
```

| Verdict | Meaning | What follows |
|---|---|---|
| `unchanged` | same version, same content | nothing |
| `no-effect` | the version moved, the used part did not | nothing; say so |
| `update-doc` | a page body or a used endpoint changed, or a citation no longer resolves at HEAD | `refresh` |
| `retest` | the design node changed | `refresh`, then re-check what was built from it (`/multi-agent:design-check`, the component's tests) |
| `unchecked` | the source could not be read, or has no fingerprint | report it; never read it as unchanged |

Print one row per source with its verdict and the version it moved from and to.
Exit 1 means at least one source is stale or unchecked. `check` writes nothing.
A document with no sidecar was emitted before fingerprints existed: say so and
offer `refresh`, which fingerprints it.

## refresh: a new draft, never an overwrite

1. Run `check`. With nothing stale, stop.
2. Re-run Phase 1 evidence gathering for the stale sources only; the others keep
   their recorded evidence.
3. Re-run synthesis and render as a normal run would, into a new draft directory.
4. Add a Section 23 changelog row naming each refreshed source and its old and
   new version.
5. Validate (`validate-analysis-doc.mjs`), fingerprint the draft, and show the
   diff against the current document.
6. Replacing the document, locally or on its Confluence page, is a separate
   approval. The current document is never edited in place.