System recap (visual plan / visual recap)
Produce a high-altitude, visual review aid directly in the PR description. No
deployment, no third-party service: GitHub renders the block (including mermaid
diagrams), and the PR itself is the storage. A future viewer app can ingest the
same marker-delimited block via the GitHub API, so follow the format exactly.
The recap is informational and non-blocking. It supplements the PR description
and normal code review; it never replaces reading the diff.
Two modes, one format
- Plan mode (before/while implementing): describe the intended change
against the current system. If no PR exists yet, put the block in the plan
document or message; move it into the PR description once the PR exists.
- Recap mode (PR creation and every meaningful update): describe what the
diff actually does. Replaces a plan-mode block if one exists.
Source-of-truth rules (non-negotiable)
- Recap mode reads the diff, not memory. Generate the recap from
git diff <base>...HEAD (plus git diff --stat) against the PR base branch.
Session context may explain intent, but every claim about what changed must
be checkable against the diff.
- Classification is checked against the primitives map. Read
docs/contributing/architecture/primitives.yaml
before classifying. Use its id values verbatim in the block.
- The map stays current. If the PR adds, removes, or materially reshapes a
primitive, update
primitives.yaml in the same PR and say so in the block.
Risk classification
Classify each touched primitive, then roll up to the highest severity as the
overall classification (adds > extends > composes):
| Classification |
Meaning |
Risk |
composes |
Uses existing primitives as-is; wiring and call sites only |
Low |
extends |
Changes a primitive's behavior, shape, or contract |
Medium |
adds |
Introduces a new primitive (must update primitives.yaml) |
High |
A change touching invariants from primitives.yaml (for example per-user
isolation) is called out explicitly regardless of classification.
Block format
The block lives in the PR description between HTML comment markers, wrapped in
<details>. Fixed section order — a future ingestion process parses this
structure. Omit optional sections rather than leaving them empty.
<!-- system-recap:start -->
<details>
<summary>System recap — <b>composes existing primitives</b> (low risk)</summary>
**Mode:** recap · **Base:** `main` @ `abc1234` · **Head:** `def5678`
**Classification:** composes — no primitives added or changed; this PR wires
existing primitives together.
### Primitives touched
| Primitive | Group | Impact |
| ------------ | -------- | --------------------------------------- |
| `mcp-server` | surfaces | composes |
| `d1-app-db` | storage | extends — new `jobs.retry_count` column |
### System map
```mermaid
flowchart LR
mcpServer["mcp-server"]:::touched
capabilityRegistry["capability-registry"]:::untouched
d1AppDb["d1-app-db"]:::extended
mcpServer --> capabilityRegistry --> d1AppDb
classDef touched fill:#1a7f37,color:#fff
classDef extended fill:#9a6700,color:#fff
classDef added fill:#cf222e,color:#fff
classDef untouched fill:#57606a,color:#fff
```
### Change flow
_Optional: a mermaid flowchart or sequence diagram of the specific change._
### Before / after
_Optional: schema, API shape, or route changes as compact before/after fenced
blocks or tables._
### Invariants
_Optional: only when the change touches an invariant from primitives.yaml._
### Plan vs actual
_Recap mode only, when a plan-mode block existed: what shipped as planned and
what drifted, in a short list._
</details>
<!-- system-recap:end -->
Format rules:
- The
<summary> line always carries the overall classification and risk in
bold so reviewers see it without expanding.
- Blank line after
<summary> and around every fenced block, or GitHub will not
render the markdown/mermaid inside <details>.
- System map: show touched primitives plus their immediate neighbors from
the map — not all ~25 nodes. Color with the four
classDef styles above
(touched = composes, extended, added, untouched for context nodes).
Quote node labels containing spaces or special characters.
- Keep the whole block scannable: prefer tables and diagrams over prose, and
keep it well under ~120 lines.
Workflow
Recap mode (PR create/update)
Read docs/contributing/architecture/primitives.yaml.
Get the facts: gh pr view <n> --json baseRefName,headRefName, then
git diff <base>...HEAD --stat and the full diff for anything you did not
author this session.
Map changed paths to primitives via the map's code entries; classify each;
roll up the overall classification.
Author the block following the format above.
Upsert it into the PR description:
node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> <block-file>
The script replaces the content between the markers, or appends the block to
the end of the description on first run. It never touches text outside the
markers.
Re-run steps 2-5 after pushing significant new commits to the PR.
Plan mode
Same steps, except: **Mode:** plan, no Base/Head commits required, "Primitives
touched" describes intended impact, and add a one-line note when the plan
requires no change to any primitive — that is the lowest-risk outcome and
worth stating explicitly. When implementation later diverges from the plan, the
recap's "Plan vs actual" section records the drift.
1---2name: visual-recap-23description: Generate and maintain the system recap block in a PR description - a GitHub-rendered visual summary of which system primitives a change touches, how risky it is, and what changed. Use when planning a non-trivial change (plan mode), when creating or updating a pull request (recap mode), or when the user asks for a visual recap, visual plan, system review, or PR recap.4---56# System recap (visual plan / visual recap)78Produce a high-altitude, visual review aid directly in the PR description. No9deployment, no third-party service: GitHub renders the block (including mermaid10diagrams), and the PR itself is the storage. A future viewer app can ingest the11same marker-delimited block via the GitHub API, so follow the format exactly.1213The recap is informational and non-blocking. It supplements the PR description14and normal code review; it never replaces reading the diff.1516## Two modes, one format1718- **Plan mode** (before/while implementing): describe the intended change19 against the current system. If no PR exists yet, put the block in the plan20 document or message; move it into the PR description once the PR exists.21- **Recap mode** (PR creation and every meaningful update): describe what the22 diff actually does. Replaces a plan-mode block if one exists.2324## Source-of-truth rules (non-negotiable)25261. **Recap mode reads the diff, not memory.** Generate the recap from27 `git diff <base>...HEAD` (plus `git diff --stat`) against the PR base branch.28 Session context may explain intent, but every claim about what changed must29 be checkable against the diff.302. **Classification is checked against the primitives map.** Read31 [`docs/contributing/architecture/primitives.yaml`](../../../docs/contributing/architecture/primitives.yaml)32 before classifying. Use its `id` values verbatim in the block.333. **The map stays current.** If the PR adds, removes, or materially reshapes a34 primitive, update `primitives.yaml` in the same PR and say so in the block.3536## Risk classification3738Classify each touched primitive, then roll up to the highest severity as the39overall classification (`adds` > `extends` > `composes`):4041| Classification | Meaning | Risk |42| -------------- | ---------------------------------------------------------- | ------ |43| `composes` | Uses existing primitives as-is; wiring and call sites only | Low |44| `extends` | Changes a primitive's behavior, shape, or contract | Medium |45| `adds` | Introduces a new primitive (must update primitives.yaml) | High |4647A change touching invariants from `primitives.yaml` (for example per-user48isolation) is called out explicitly regardless of classification.4950## Block format5152The block lives in the PR description between HTML comment markers, wrapped in53`<details>`. Fixed section order — a future ingestion process parses this54structure. Omit optional sections rather than leaving them empty.5556````markdown57<!-- system-recap:start -->5859<details>60<summary>System recap — <b>composes existing primitives</b> (low risk)</summary>6162**Mode:** recap · **Base:** `main` @ `abc1234` · **Head:** `def5678`6364**Classification:** composes — no primitives added or changed; this PR wires65existing primitives together.6667### Primitives touched6869| Primitive | Group | Impact |70| ------------ | -------- | --------------------------------------- |71| `mcp-server` | surfaces | composes |72| `d1-app-db` | storage | extends — new `jobs.retry_count` column |7374### System map7576```mermaid77flowchart LR78 mcpServer["mcp-server"]:::touched79 capabilityRegistry["capability-registry"]:::untouched80 d1AppDb["d1-app-db"]:::extended81 mcpServer --> capabilityRegistry --> d1AppDb82 classDef touched fill:#1a7f37,color:#fff83 classDef extended fill:#9a6700,color:#fff84 classDef added fill:#cf222e,color:#fff85 classDef untouched fill:#57606a,color:#fff86```8788### Change flow8990_Optional: a mermaid flowchart or sequence diagram of the specific change._9192### Before / after9394_Optional: schema, API shape, or route changes as compact before/after fenced95blocks or tables._9697### Invariants9899_Optional: only when the change touches an invariant from primitives.yaml._100101### Plan vs actual102103_Recap mode only, when a plan-mode block existed: what shipped as planned and104what drifted, in a short list._105106</details>107108<!-- system-recap:end -->109````110111Format rules:112113- The `<summary>` line always carries the overall classification and risk in114 bold so reviewers see it without expanding.115- Blank line after `<summary>` and around every fenced block, or GitHub will not116 render the markdown/mermaid inside `<details>`.117- **System map**: show touched primitives plus their immediate neighbors from118 the map — not all ~25 nodes. Color with the four `classDef` styles above119 (`touched` = composes, `extended`, `added`, `untouched` for context nodes).120 Quote node labels containing spaces or special characters.121- Keep the whole block scannable: prefer tables and diagrams over prose, and122 keep it well under ~120 lines.123124## Workflow125126### Recap mode (PR create/update)1271281. Read `docs/contributing/architecture/primitives.yaml`.1292. Get the facts: `gh pr view <n> --json baseRefName,headRefName`, then130 `git diff <base>...HEAD --stat` and the full diff for anything you did not131 author this session.1323. Map changed paths to primitives via the map's `code` entries; classify each;133 roll up the overall classification.1344. Author the block following the format above.1355. Upsert it into the PR description:136137 ```bash138 node .agents/skills/visual-recap/scripts/upsert-recap-block.mjs <pr-number> <block-file>139 ```140141 The script replaces the content between the markers, or appends the block to142 the end of the description on first run. It never touches text outside the143 markers.1441456. Re-run steps 2-5 after pushing significant new commits to the PR.146147### Plan mode148149Same steps, except: `**Mode:** plan`, no Base/Head commits required, "Primitives150touched" describes intended impact, and add a one-line note when the plan151requires **no** change to any primitive — that is the lowest-risk outcome and152worth stating explicitly. When implementation later diverges from the plan, the153recap's "Plan vs actual" section records the drift.