visual-recap

Visual Recap

Help a reviewer understand a non-trivial change and choose where to inspect first.

A useful recap answers these questions in less than one minute:

• What outcome changes?
• Which system parts and relationships are affected?
• What path should the reviewer trace?
• Where is the risk or evidence gap?

The recap supplements the plan, source, change set, and normal review. It does not replace them.

Choose the Mode

• Plan: Show intended work against the current system. Label assumptions, open decisions, and unverified paths.
• Recap: Show what the current change set does. Rebuild the recap from current evidence.

State the mode. If a plan and an implementation both exist, use Recap. Add a short plan-versus-actual view only when they differ.

Ground the Recap

Use the smallest sufficient set of project evidence:

1. Follow the instructions and context that the Host Agent already supplied.
2. Look for project-local CONTEXT-MAP.md and CONTEXT.md files. Use CONTEXT-MAP.md for bounded-context locations and relationships. Use the relevant CONTEXT.md files for canonical domain terms. Link to each file that informed the recap.
3. Use existing architecture documents, diagrams, ownership maps, and decision records when they cover the affected area.
4. In Plan mode, inspect the current implementation and the proposed plan or requirements.
5. In Recap mode, inspect the actual change set, affected source, and validation results. Use a source-control comparison when available, but do not require one version-control system.

A CONTEXT.md glossary supplies language, not architecture or path ownership. Do not create or update context files for this recap.

Use session memory to find evidence, not to prove a claim. Label facts when the distinction matters:

• documented: defined by canonical project material;
• observed: present in the current implementation or change set;
• planned: intended but not implemented;
• inferred: derived from source boundaries or behavior;
• unknown: not verified.