diff-recap
Turn a git diff into a PR-pasteable recap — one row per changed file whose path, status, and line counts are transcribed verbatim from `git diff --name-status` and `--numstat` (the model writes only the labels), emitted as a `diff-recap/1` record whose totals equal the sum of the
Install
npx skills add https://github.com/allemaar/open-skills/tree/main/skills/diff-recap
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install allemaar-open-skills@llmmart
git clone https://github.com/allemaar/open-skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole allemaar/open-skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
/diff-recap
Turns a git diff into a recap you can paste into a pull request — a per-file change table whose numbers are transcribed from git, grouped and labelled, backed by a diff-recap/1 record, with a complete ASCII recap for human readers and an inline widget when the render-face contract permits it. It fills the gap the orient- family leaves open: orient-map shows the shape of the work and orient-status shows where you stand, but neither recaps what a concrete change-set contains for a reviewer. diff-recap does exactly that, and only that.
Its differentiator is true by construction: the structured numbers (per-file added/removed/status and the headline totals) come straight from git diff --numstat and --name-status — the model authors only the prose labels. A record whose totals don't equal the sum of its rows is rejected by a value gate before it can be shown, which checks internal arithmetic; source fidelity still depends on the required Git capture and transcription. And unlike a hosted recap renderer, it has zero external dependency — the ASCII twin is self-contained and PR-pasteable in any channel.
Structured execution spec:
protocol.yon. Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the@STAMPdate.
When to use
- "Recap this diff / summarize these changes for a PR" — you want a reviewer-ready change summary, not a fresh read of the whole tree.
- "What changed in this branch" as a change-set, grouped by area with a one-line why per file.
- Right before opening a pull request, when you want a paste-able summary whose numbers you can trust.
How it works (self-sufficient — works without protocol.yon)
Every call recomputes from the real diff; nothing is stored.
Take
range,repo, andintentas inputs — never prompt.rangedefaults to the working tree againstHEAD(or aA..Brange, or--staged);repodefaults to the cwd.intent(the PR's goal) shapes the labels — if it's ungrounded, the recap still emits the mechanical facts but caps the labels to descriptive and never invents a rationale.Gather from git, transcribe verbatim. Run
git diff --name-statusandgit diff --numstatover the range. Hold the exact repository, range and rename/copy-detection settings constant across both captures. Before transcribing rows, inspect the status and path arity. Any rename/copy status (R,C,R100,C75, or another score) or two-path rename/copy form is UNSUPPORTED INPUT for the current single-path record: report the exact source case and stop without emitting a recap. Do not strip scores, collapse paths, drop rows, silently disable detection, or mislabel this as barren/NO DIFF. For ordinary single-path files, copystatus(A/M/D) andadded/removedexactly as git reports them. A binary file reports-/-in numstat → record0/0and mark the row binary in its label. The model never counts by hand — the numbers are git's.Group and label — the only model-written fields. Cluster the files by area (feature / tests / docs / config / …), and write one concise label per file and a one-line summary per group.
path,status,added,removedare git-attested;labelandgroupare the model's only freedom.Set the totals as the sum of the rows.
total_files,total_added,total_removedare the exact count and sums of the per-file rows — that is the true-by-construction invariant: the headline is, by definition, the sum of the attested rows.Fail closed. No git, or an empty diff →
gate_status = barren,attested = false, and a NO DIFF card — never a fabricated recap. Acleanrecap requires a real git source (attested = true); a partial source caps the verdict atpartial.Emit the selected bundle. Emit the YON record (below); human-facing branches add the PR-pasteable markdown summary and selected visual face. diff-recap honors the three render-face branches: a human on Claude Code with the visualize tool present on an explicit invocation gets the widget + ASCII twin; an agent gets the YON record only; any other runtime / no tool / indeterminate
handler_typegets the ASCII twin (fail-closed). See the bundled, self-containedrender-face contract. diff-recap adopts only this branching, not the orient family's footer roster, "you are here" breadcrumb, or staleness short-circuit. Every human-facing or indeterminate branch emits the information-complete ASCII twin — it carries every file row, count, group, and total the widget does (worked trio atexamples/diff-recap.{ascii.txt,widget.svg,example.yon}).
Record emission (the YON face — reserved tags only)
The record is a diff-recap/1 instance (recap-schema.yon). Reserved tags only. The envelope is @CFG id=recap; each changed file is one @CFG id=file.<n>; list fields (groups, provenance) go in a sidecar @MAP, never an in-set bracket-list (an in-set list corrupts the record silently and still validates). Never run yon format on an instance — CANON mode is destructive on set-internal lists. Validate with --profile exec, then run the value gate. Skeleton:
@CFG id=recap | set=[schema_version=diff-recap/1,computed_at:ts=…,ephemeral:bool=true,tool=diff-recap,range="HEAD",repo=".",total_files:int=4,total_added:int=155,total_removed:int=7,attested:bool=true,gate_status=clean,overall_trust=high]
@CFG id=subject | set=[name=…,kind=repo,purpose=…,intent_status=stated]
@CFG id=file.f1 | set=[path="src/rate-limit.ts",status=A,added:int=88,removed:int=0,group=feature,label="new token-bucket limiter"]
@CFG id=file.f2 | set=[path="src/server.ts",status=M,added:int=24,removed:int=6,group=feature,label="wire the limiter in"]
@MAP name=groups | pairs=["feature"->"limiter + wiring (2 files, +112/-6)"]
@MAP name=provenance | pairs=["recap.total_added"->"git-attested:high:git diff --numstat"]
Unsupported input is a separate diagnostic, not a diff-recap/1 record or a new gate enum. The legacy R schema enum does not provide an old/new-path encoding. Supporting scored renames/copies requires a separately selected compatible format. The value checker does not inspect --name-status; the emitter must perform this input boundary before value validation.
On barren evidence the envelope degrades honestly: gate_status=barren, attested:bool=false, no file rows, and the visual is the NO DIFF card. A full worked instance ships at examples/diff-recap.example.yon.
The value gate — why the recap can't lie
yon validate checks structure, not values: a record can be valid YON yet state total_added=999 while its rows sum to 155. references/tools/diff-recap-check.mjs travels inside this skill folder and is the missing half — it asserts Σ per-file == totals, enum membership, and the fail-closed/attested gates, and with --numstat it compares row paths and counts against the supplied capture. It does not compare statuses with --name-status or establish capture origin or freshness; an attested flag alone is not source evidence. The emitter still verifies the bound Git source and transcribes statuses. An emitter runs it before emit; the source repository additionally exercises the worked and deliberately broken fixtures as release evidence.
node <skill-dir>/references/tools/diff-recap-check.mjs <skill-dir>/examples/diff-recap.example.yon --numstat <skill-dir>/examples/diff-recap.numstat
Output — worked examples (markdown / ASCII face)
📋 acme-api — add per-route rate limiting. range: HEAD [counts: ◆ git --numstat]
## 4 files · +155 / −7 ◆ git diff --numstat
feature +112 / −6
+ src/rate-limit.ts +88 / −0 new token-bucket limiter (per-route) ◆ A
~ src/server.ts +24 / −6 wire limiter in; drop old fixed counter ◆ M
tests +40 / −0
+ test/rate-limit.test.ts +40 / −0 burst, refill, per-route isolation ◆ A
docs +3 / −1
~ README.md +3 / −1 document the RATE_LIMIT env var ◆ M
Σ rows = +155 / −7 == headline ✓ (true by construction)
**→ PR summary:** per-route token-bucket rate limiter + unit tests + env-var doc.
Trust: ◆◆◆ every count git-attested · the model wrote only the labels · gate: clean
Barren (honest degradation is the success case):
📋 ToDo — no git, or an empty diff.
┌───────────────────────────────┐
│ NO DIFF │ nothing to recap — no commits, no changes.
└───────────────────────────────┘
**→ Next:** stage or commit a change, and the recap becomes visible.
Trust: ◌◌◌ · [gate: barren · attested: false]
The ASCII twin + the Σ rows == headline line + the trust trailer are mandatory on human-facing and indeterminate output; an agent consumer receives only the record.
Boundaries
- Not
/orient-map— that shows the shape + delta of the work (done → here → next); diff-recap recaps a concrete change-set for a reviewer. They never overlap: orient-map is trajectory, diff-recap is a PR table. - Not
/orient-status— that reports position + remaining + ETA; diff-recap reports what a diff contains. - Not a code review — it summarizes what changed, it does not judge whether the change is good. Pipe it into
/cold-reviewfor that. - Read-only. It runs
git diffand reads the tree; it never mutates state. - No hosted dependency. Unlike a hosted recap renderer, the ASCII twin is the floor and is self-contained — the recap works with no visualize tool, no server, no account.
Rules
- MUST be true by construction — transcribe
path,status,added,removedverbatim fromgit diff --name-status/--numstat; never count by hand. The model authors onlylabelandgroup. - MUST set
total_files/total_added/total_removedto the exact count and sums of the rows, so the headline equals the sum of the attested rows; the value gate rejects any record where they drift. - MUST fail closed — no git or an empty diff →
gate_status = barren,attested = false, NO DIFF card; acleanverdict requiresattested = true. - MUST emit the information-complete ASCII twin on human-facing and indeterminate branches — it is the only human render in a no-SVG channel and is PR-pasteable verbatim. The agent-only branch emits only the record.
- MUST select the output per the render-face contract (the widget is Claude Code only, via
mcp__visualize__show_widget): agent → YON record only; human + Claude + tool + explicit invocation → widget + ASCII twin; other runtime / no tool / indeterminatehandler_type→ ASCII twin (fail-closed). Widget and ASCII twin are projections of one row-structure (same rows + totals), chrome-compliant (no hardcoded color,role="img"with non-empty title/desc, fixed 680 viewBox). - MUST emit file rows as
@CFG id=file.<n>and list fields (groups,provenance) as sidecar@MAP; never a bare in-set bracket-list; neveryon formatan instance. - MUST take
intentas input and cap labels to descriptive when it's ungrounded — never fabricate a rationale.
Next skills. On completion, run the Next Skills protocol (
next-skills/SKILL.md): surface thenext-skillsrecommendations from front-matter for the caller to pick. Offer only — never auto-invoke.
Self-improvement. On completion, run the Self-Improvement Protocol (
self-improve/SKILL.md): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Files (open-skills)
-
examples
-
bad
-
fabricated-counts.yon 1.7 KB · in bundle
-
fail-open.yon 1.7 KB · in bundle
-
numstat-mismatch.yon 1.8 KB · in bundle
-
-
diff-recap.ascii.txt 1.1 KB
Loading… -
diff-recap.example.yon 2.2 KB · in bundle
-
diff-recap.numstat 85 B · in bundle
-
diff-recap.widget.svg 2.6 KB · in bundle
-
-
references
-
tools
-
diff-recap-check.mjs 18.7 KB · in bundle
-
-
render-face-contract.md 842 B
Loading…
-
-
protocol.yon 9.5 KB · in bundle
-
recap-schema.yon 2.3 KB · in bundle
-
SKILL.md 13.5 KB
--- name: diff-recap description: > Turn a git diff into a PR-pasteable recap — one row per changed file whose path, status, and line counts are transcribed verbatim from `git diff --name-status` and `--numstat` (the model writes only the labels), emitted as a `diff-recap/1` record whose totals equal the sum of the rows, with a complete ASCII recap for human readers and an inline widget when the render-face contract permits it. Fills the PR-summary gap the orient- family does not cover. Not /orient-map (shape + delta of the work) or /orient-status (position + ETA) — diff-recap recaps a concrete change-set. Zero external dependency: it renders inline, never to a hosted service. visibility: public self-improvable: true companions: - path: references/tools/diff-recap-check.mjs optional: false why: "The required value and git-numstat gate; bundled inside this skill." - path: references/render-face-contract.md optional: false why: "The required self-contained render-face behavior used by this skill." triggers: - "/diff-recap" - "recap this diff" - "summarize these changes for a PR" - "what changed in this branch" - "write a PR summary" next-skills: - skill: cold-review phrase: "/cold-review" why: "Before you open the PR, hand the recapped change-set to a fresh-context reviewer." - skill: handoff phrase: "/handoff" why: "Turn the recap into an inter-session brief — it already carries the attested change-summary the next agent needs." --- # /diff-recap Turns a **git diff into a recap you can paste into a pull request** — a per-file change table whose numbers are *transcribed from git*, grouped and labelled, backed by a `diff-recap/1` record, with a **complete ASCII recap for human readers** and an inline widget when the render-face contract permits it. It fills the gap the `orient-` family leaves open: `orient-map` shows the *shape* of the work and `orient-status` shows *where you stand*, but neither recaps **what a concrete change-set contains** for a reviewer. diff-recap does exactly that, and only that. Its differentiator is **true by construction**: the structured numbers (per-file `added`/`removed`/`status` and the headline totals) come straight from `git diff --numstat` and `--name-status` — the model authors *only* the prose labels. A record whose totals don't equal the sum of its rows is **rejected by a value gate before it can be shown**, which checks internal arithmetic; source fidelity still depends on the required Git capture and transcription. And unlike a hosted recap renderer, it has **zero external dependency** — the ASCII twin is self-contained and PR-pasteable in any channel. > **Structured execution spec:** [`protocol.yon`](protocol.yon). Read it for the canonical steps, rules, and gates; this file is the human-readable, self-sufficient explanation. The two must stay in sync — if you edit one, update the other and refresh the `@STAMP` date. ## When to use - "Recap this diff / summarize these changes for a PR" — you want a reviewer-ready change summary, not a fresh read of the whole tree. - "What changed in this branch" as a **change-set**, grouped by area with a one-line why per file. - Right before opening a pull request, when you want a paste-able summary whose numbers you can trust. ## How it works (self-sufficient — works without `protocol.yon`) Every call recomputes from the real diff; nothing is stored. 1. **Take `range`, `repo`, and `intent` as inputs — never prompt.** `range` defaults to the working tree against `HEAD` (or a `A..B` range, or `--staged`); `repo` defaults to the cwd. `intent` (the PR's goal) shapes the labels — if it's ungrounded, the recap still emits the mechanical facts but **caps the labels to descriptive** and never invents a rationale. 2. **Gather from git, transcribe verbatim.** Run `git diff --name-status` and `git diff --numstat` over the range. Hold the exact repository, range and rename/copy-detection settings constant across both captures. Before transcribing rows, inspect the status and path arity. Any rename/copy status (`R`, `C`, `R100`, `C75`, or another score) or two-path rename/copy form is **UNSUPPORTED INPUT** for the current single-path record: report the exact source case and stop without emitting a recap. Do not strip scores, collapse paths, drop rows, silently disable detection, or mislabel this as barren/NO DIFF. For ordinary single-path files, copy `status` (`A`/`M`/`D`) and `added`/`removed` **exactly as git reports them**. A binary file reports `-`/`-` in numstat → record `0`/`0` and mark the row binary in its label. **The model never counts by hand** — the numbers are git's. 3. **Group and label — the only model-written fields.** Cluster the files by area (feature / tests / docs / config / …), and write one concise label per file and a one-line summary per group. `path`, `status`, `added`, `removed` are git-attested; `label` and `group` are the model's only freedom. 4. **Set the totals as the sum of the rows.** `total_files`, `total_added`, `total_removed` are the exact count and sums of the per-file rows — *that* is the true-by-construction invariant: the headline is, by definition, the sum of the attested rows. 5. **Fail closed.** No git, or an empty diff → `gate_status = barren`, `attested = false`, and a **NO DIFF card** — never a fabricated recap. A `clean` recap requires a real git source (`attested = true`); a partial source caps the verdict at `partial`. 6. **Emit the selected bundle.** Emit the YON record (below); human-facing branches add the PR-pasteable markdown summary and selected visual face. diff-recap honors the **three render-face branches**: a human on Claude Code with the visualize tool present on an explicit invocation gets the **widget + ASCII twin**; an **agent** gets the YON record only; any **other runtime / no tool / indeterminate `handler_type`** gets the **ASCII twin** (fail-closed). See the bundled, self-contained [`render-face contract`](references/render-face-contract.md). diff-recap adopts only this branching, **not** the orient family's footer roster, "you are here" breadcrumb, or staleness short-circuit. Every human-facing or indeterminate branch emits the **information-complete ASCII twin** — it carries every file row, count, group, and total the widget does (worked trio at [`examples/diff-recap.{ascii.txt,widget.svg,example.yon}`](examples/)). ## Record emission (the YON face — reserved tags only) The record is a `diff-recap/1` instance ([`recap-schema.yon`](recap-schema.yon)). **Reserved tags only.** The envelope is `@CFG id=recap`; each changed file is one `@CFG id=file.<n>`; **list fields (`groups`, `provenance`) go in a sidecar `@MAP`, never an in-set bracket-list** (an in-set list corrupts the record *silently and still validates*). **Never run `yon format` on an instance** — `CANON` mode is destructive on set-internal lists. Validate with `--profile exec`, then run the value gate. Skeleton: ``` @CFG id=recap | set=[schema_version=diff-recap/1,computed_at:ts=…,ephemeral:bool=true,tool=diff-recap,range="HEAD",repo=".",total_files:int=4,total_added:int=155,total_removed:int=7,attested:bool=true,gate_status=clean,overall_trust=high] @CFG id=subject | set=[name=…,kind=repo,purpose=…,intent_status=stated] @CFG id=file.f1 | set=[path="src/rate-limit.ts",status=A,added:int=88,removed:int=0,group=feature,label="new token-bucket limiter"] @CFG id=file.f2 | set=[path="src/server.ts",status=M,added:int=24,removed:int=6,group=feature,label="wire the limiter in"] @MAP name=groups | pairs=["feature"->"limiter + wiring (2 files, +112/-6)"] @MAP name=provenance | pairs=["recap.total_added"->"git-attested:high:git diff --numstat"] ``` **Unsupported input is a separate diagnostic, not a `diff-recap/1` record or a new gate enum.** The legacy `R` schema enum does not provide an old/new-path encoding. Supporting scored renames/copies requires a separately selected compatible format. The value checker does not inspect `--name-status`; the emitter must perform this input boundary before value validation. On **barren** evidence the envelope degrades honestly: `gate_status=barren, attested:bool=false`, no file rows, and the visual is the **NO DIFF card**. A full worked instance ships at [`examples/diff-recap.example.yon`](examples/diff-recap.example.yon). ### The value gate — why the recap can't lie `yon validate` checks *structure*, not *values*: a record can be valid YON yet state `total_added=999` while its rows sum to `155`. [`references/tools/diff-recap-check.mjs`](references/tools/diff-recap-check.mjs) travels inside this skill folder and is the missing half — it asserts **Σ per-file == totals**, enum membership, and the fail-closed/attested gates, and with `--numstat` it compares row paths and counts against the supplied capture. It does not compare statuses with `--name-status` or establish capture origin or freshness; an `attested` flag alone is not source evidence. The emitter still verifies the bound Git source and transcribes statuses. An emitter runs it before emit; the source repository additionally exercises the worked and deliberately broken fixtures as release evidence. ```bash node <skill-dir>/references/tools/diff-recap-check.mjs <skill-dir>/examples/diff-recap.example.yon --numstat <skill-dir>/examples/diff-recap.numstat ``` ## Output — worked examples (markdown / ASCII face) ``` 📋 acme-api — add per-route rate limiting. range: HEAD [counts: ◆ git --numstat] ## 4 files · +155 / −7 ◆ git diff --numstat feature +112 / −6 + src/rate-limit.ts +88 / −0 new token-bucket limiter (per-route) ◆ A ~ src/server.ts +24 / −6 wire limiter in; drop old fixed counter ◆ M tests +40 / −0 + test/rate-limit.test.ts +40 / −0 burst, refill, per-route isolation ◆ A docs +3 / −1 ~ README.md +3 / −1 document the RATE_LIMIT env var ◆ M Σ rows = +155 / −7 == headline ✓ (true by construction) **→ PR summary:** per-route token-bucket rate limiter + unit tests + env-var doc. Trust: ◆◆◆ every count git-attested · the model wrote only the labels · gate: clean ``` **Barren (honest degradation is the success case):** ``` 📋 ToDo — no git, or an empty diff. ┌───────────────────────────────┐ │ NO DIFF │ nothing to recap — no commits, no changes. └───────────────────────────────┘ **→ Next:** stage or commit a change, and the recap becomes visible. Trust: ◌◌◌ · [gate: barren · attested: false] ``` The ASCII twin + the `Σ rows == headline` line + the trust trailer are **mandatory** on human-facing and indeterminate output; an agent consumer receives only the record. ## Boundaries - **Not `/orient-map`** — that shows the *shape + delta* of the work (done → here → next); diff-recap recaps a *concrete change-set* for a reviewer. They never overlap: orient-map is trajectory, diff-recap is a PR table. - **Not `/orient-status`** — that reports *position + remaining + ETA*; diff-recap reports *what a diff contains*. - **Not a code review** — it summarizes *what changed*, it does not judge whether the change is good. Pipe it into `/cold-review` for that. - **Read-only.** It runs `git diff` and reads the tree; it never mutates state. - **No hosted dependency.** Unlike a hosted recap renderer, the ASCII twin is the floor and is self-contained — the recap works with no visualize tool, no server, no account. ## Rules - MUST be **true by construction** — transcribe `path`, `status`, `added`, `removed` verbatim from `git diff --name-status`/`--numstat`; never count by hand. The model authors **only** `label` and `group`. - MUST set `total_files`/`total_added`/`total_removed` to the exact count and sums of the rows, so the headline equals the sum of the attested rows; the value gate **rejects** any record where they drift. - MUST **fail closed** — no git or an empty diff → `gate_status = barren`, `attested = false`, NO DIFF card; a `clean` verdict requires `attested = true`. - MUST emit the **information-complete ASCII twin** on human-facing and indeterminate branches — it is the only human render in a no-SVG channel and is PR-pasteable verbatim. The agent-only branch emits only the record. - MUST select the output per the render-face contract (the widget is Claude Code only, via `mcp__visualize__show_widget`): agent → YON record only; human + Claude + tool + explicit invocation → widget + ASCII twin; other runtime / no tool / indeterminate `handler_type` → ASCII twin (fail-closed). Widget and ASCII twin are projections of **one row-structure** (same rows + totals), chrome-compliant (no hardcoded color, `role="img"` with non-empty title/desc, fixed 680 viewBox). - MUST emit file rows as `@CFG id=file.<n>` and list fields (`groups`, `provenance`) as sidecar `@MAP`; never a bare in-set bracket-list; never `yon format` an instance. - MUST take `intent` as input and cap labels to descriptive when it's ungrounded — never fabricate a rationale. > **Next skills.** On completion, run the Next Skills protocol (`next-skills/SKILL.md`): surface the `next-skills` recommendations from front-matter for the caller to pick. Offer only — never auto-invoke. > **Self-improvement.** On completion, run the Self-Improvement Protocol (`self-improve/SKILL.md`): apply its signal taxonomy and threshold to this run; surface any surviving proposal for handler approval. Conservative — silent otherwise. Never auto-apply.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.