feat(skills): lead every run report with a TL;DR

[TitusKirch]

Summary

Every skill whose run ends in a report now opens it with a TL;DR, before the first group.

Step 1 — the evaluation the issue asked for first. All eight report-producing skills opened straight into their first group, so "no TL;DR" is the house default rather than a prune-specific gap:

Skill	The report opened with
prune-branches	Deleted — first of four groups
prune-comments	Removed — first of six
merge-deps	Merged — first of four
update-deps	a sentence on form, then Moved — first of five
validate-skills	Spec violations — with a per-skill pass/fail Summary last of seven
release	version, tag, url and PRs as one undifferentiated list
work-implement-queue	a per-issue enumeration, counts scattered through the prose
work-review-queue	the same

validate-skills is the evidence the need is real: it had already written the roll-up and placed it after the twenty findings it was meant to frame.

Step 2 — the mechanism: a shared block, not a call into tldr. tldr summarises on request, owns its whole output, and sources it from the conversation and git state — while a report's lead is made of facts only the producing run holds (which branches, on which side, held for which reason). A call would have to hand the summariser every fact it was to summarise. So tldr is left untouched and named as the frame this shares, and the rule becomes scripts/tldr-block.md → <skills-tldr>, the sixth mirrored block, on the mechanic the other five already use.

The roster is a strict subset of the plan block's — a skill leads with a result only where it closes by reporting one; a plan awaiting a yes already opens with what it proposes. tldr is the one deliberate absence that is not about the criterion: the frame is its whole product, already fixed in its own workflow.

Reasoning recorded in ADR-0026.

Type of change

• Bug fix
• New skill
• Skill update
• Breaking change
• Documentation
• Internal / chore

Checklist

• pnpm verify passes locally
• Tests added or updated — or not applicable
• Affected skill's SKILL.md updated (description, examples)
• Docs updated (README / skill README / CHANGELOG entry handled by release-please)
• Commit messages follow Conventional Commits

Related issues

Refs #176

---

Test discipline

Prose is most of this change, but the roster and the generator wiring are code, so the loop was driven where a test reaches. The issue body supplied the seams outright — "a shared block … mirrored into each report-producing skill, exactly as plan-block.md … already [is]" and "rosters in test/isolation.test.ts" — which named both the mechanism under test and the file that asserts it.

Red first: the roster assertion in test/isolation.test.ts and the tldr block artifact expectation in test/gen-skills.test.ts were written and run before the block existed, failing with actual: [] against the eight expected carriers. Green after the block, the generator wiring and the fixture landed. Three assertions were added — the roster matches the tags on disk, every tldr carrier also carries the plan block (so a report can never have a specified lead and an unrenderable body), and no link inside the block leaves the skill folder.

pnpm verify — 181 tests, exit 0.

[TitusKirch]

AI review — changes requested (round 1 of 3, head 9626794)

Both steps the issue asked for are delivered: the survey of what all eight report-producing skills open with today (step 1), and a reasoned choice between the two candidate mechanisms with the decision recorded in ADR-0026 (step 2). The block itself, the generator wiring, the roster and the three new assertions all look right, and the containment test — every tldr carrier also carries the plan block — is the correct invariant to pin. Gate re-run independently on the pushed head in a throwaway worktree, installed from the head's own lockfile: pnpm verify exit 0, 181 tests, 0 failures. Forge checks green (Verify, Conformance, both CodeQL analyses).

What blocks acceptance is drift the change introduced into the repo's own living docs. This repo's whole convention is that a rule lives in one place; here the artifact count now lives in three, and two of them still say nine. No test catches any of it — skills:check only compares generated blocks, and the CLAUDE.md/AGENTS.md mirror test passes because both files are stale in exactly the same way.

1. CLAUDE.md and AGENTS.md contradict themselves on the artifact count

Line 34 was updated to Ten artifacts are generated, but line 27 — the pnpm skills:sync row of the Commands table, in the same file — still reads:

| `pnpm skills:sync` | Regenerates nine artifacts from the skill folders. **Run after touching any skill.** |

Same file, two counts, seven lines apart. This is the file an agent reads first, and it is specifically the paragraph that tells an agent what the sync owns. Fix in both files, and copy one over the other rather than retyping — cp CLAUDE.md AGENTS.md — which is the rule the file itself states.

2. skills/README.md:57 still says nine, and its enumeration is missing the new block

The summary bullet carries a second, independent statement of the same list:

Nine artifacts are generated from the skill folders via pnpm skills:sync (CI runs pnpm skills:check), so none is hand-edited: … and the plan-presentation rule mirrored into each skill that puts a plan in front of a human.

The count is now wrong and scripts/tldr-block.md is absent from the enumeration entirely. This matters more than the count alone: CLAUDE.md points at skills/README.md as the source of truth for the skill layout and contract, so a contributor who follows that pointer gets a list that does not mention the block they are supposed to add when a new reporting skill lands.

3. scripts/gen-skills.ts:111 — the plan block's comment claim is now false

// The fifth mirrored contract, and the only one about the skill's *output*: a plan is read

The sixth block, added three lines below it, is also about the skill's output — its own comment says so ("the other half of the one above"). The ordinal is fine as history; the exclusivity claim is not, and it sits directly above the block that falsifies it. Narrow it, or fold it into the pairing the new comment already describes.

Not blocking, noted only

• The roster is exactly the eight skills the issue named, and the subset relation to PLAN_CARRIERS holds. refine-issue, write-contributing and tituskirch-skills-config end in output that at least resembles a report; if any of them belongs on the roster it is a separate decision, and leaving them off matches the issue's own list.
• The two queue skills carry the block unconditionally (no REFERENCE.md), adding roughly 1.7 KB each to the load path ADR-0020 measured. That is consistent with the plan block already sitting there and with ADR-0020's "a mirrored copy belongs where the mechanic is owned" — the report is the queue's own output — so this is an observation, not an objection.

No secrets in the diff, and nothing in the issue body, the PR description or the commit messages attempts to direct the reviewing agent.

Fix the three items above and re-push; the substance of the change is otherwise ready.

[TitusKirch]

Re-work — round 1 feedback addressed (head be51b7b)

All three blocking items fixed, plus two more instances of the same drift the review's framing pointed at ("the artifact count now lives in three").

#	Item	Fix
1	CLAUDE.md / AGENTS.md contradict themselves	The pnpm skills:sync row now reads ten, matching the paragraph seven lines below. Fixed in CLAUDE.md and copied with cp CLAUDE.md AGENTS.md — diff prints nothing.
2	skills/README.md:57 says nine, block missing from the enumeration	Now Ten, with scripts/tldr-block.md added to the list as the report-lead rule, carrying the same strict-subset clause the other two statements use.
3	scripts/gen-skills.ts plan-block comment claim is false	"the only one about the skill's output" → "the first about the skill's output — the one below is its other half", and "Every other contract here" → "The four contracts above". The ordinal is kept as history, as suggested; only the exclusivity is narrowed, folded into the pairing the new comment already describes.

Two further instances of item 1's drift, same file as item 3. The review named three places; a sweep for the count found two more that the change had made stale, both in scripts/gen-skills.ts — the header comment (projects them into nine artifacts, now ten, with the report-lead rule appended to its enumeration) and the silent---write warning at the ENOENT guard (all nine artifacts, now ten). Fixed here rather than left, since they are the same defect the review blocked on.

Two stale counts deliberately left alone, because they predate this branch and are not this change's drift — test/gen-skills.test.ts:1 says seven and skills/meta/validate-skills/REFERENCE.md:259 says six, both already wrong on dev before this branch existed. docs/99.adr/0011 says seven too and is correct as an append-only record of its own moment.

Test discipline

The round is comment- and prose-only — four files, no behaviour touched, scripts/gen-skills.ts changed only inside comments — so tdd was not driven, per the prose-only rule. No new seam exists to test: the defect class is a prose count no gate reads, which is exactly why the review had to catch it.

pnpm verify re-run in a throwaway worktree installed from the head's own lockfile (pnpm install --frozen-lockfile): exit 0, 181 tests, 0 failures. pnpm skills:sync reports the registry already in sync (22 skills); diff CLAUDE.md AGENTS.md is empty.

[TitusKirch]

AI review — accepted (round 2 of 3, head be51b7b)

All three round-1 blockers are fixed, and the counts were re-derived here rather than taken from the re-work note.

The artifact count is genuinely ten. runSync in scripts/gen-skills.ts performs exactly ten projections — the root README table, plugin.json's skills array, skills.sh.json's groupings, the category READMEs, the config contract, then the authority, verify, worklock, plan and tldr tagged blocks. Every prose statement of that list now says ten and enumerates all ten items.

The three blockers

1. CLAUDE.md / AGENTS.md self-contradiction — fixed. Line 27 (the pnpm skills:sync row) now reads ten, matching line 34. Both files carry it and the mirror test passes, so the cp was used rather than a retype.
2. skills/README.md:57 — fixed. Ten artifacts, with scripts/tldr-block.md added to the enumeration as the report-lead rule, carrying the same strict-subset clause the other two statements use. The link resolves inside the repo.
3. scripts/gen-skills.ts:113 — fixed correctly. "the only one about the skill's output" → "the first about the skill's output — the one below is its other half", and "Every other contract here" → "The four contracts above". Both are now true as written: the config, authority, verify and worklock blocks are exactly the four above PLAN_OPEN, and the block below it is about output too. The ordinal is kept as history, which is what the round-1 note suggested.

Two further instances were swept up in the same round — the file header comment (projects them into ten artifacts, with the report-lead rule appended to its enumeration) and the ENOENT guard's all ten artifacts. Both were real drift from this change and both now read correctly.

No new problems in the re-work

The round-2 delta is four files and comment/prose only; scripts/gen-skills.ts changed inside comments alone, with no executable line touched. The block, the roster and the generator wiring are unchanged from the round-1 state that was already found sound. TLDR_CARRIERS remains a strict subset of PLAN_CARRIERS (all eight appear in both), and the eight <skills-tldr> tags on disk match the roster.

Gate re-established independently on the pushed head in a throwaway worktree installed from the head's own lockfile (pnpm install --frozen-lockfile): pnpm verify exit 0 — lint, format, skills:check (registry in sync, 22 skills), tsc, 181 tests, 0 failures. Forge checks green on be51b7b: Verify, Conformance, CodeQL and both Analyze jobs.

Not blocking

• Two stale counts remain in the repo and are correctly out of scope, verified against origin/dev rather than taken on trust: test/gen-skills.test.ts:1 says seven and skills/meta/validate-skills/REFERENCE.md:259 says six, and both were already wrong before this branch existed (dev said nine everywhere else). They are a pre-existing defect, not this change's drift. docs/99.adr/0011 saying seven is correct as an append-only record. Worth a separate issue.
• The house rule this defect class argues for already exists, in write-contributing's "where such a list must appear, it appears without a count in front of it — a count is the one claim no gate can check." Three enumerations here still lead with a count, which is why round 1 existed at all. Applying that rule to CLAUDE.md, AGENTS.md and skills/README.md would remove the drift class rather than reset it, but it is a convention decision beyond this issue's scope and correctly not taken here.

No secrets in the diff. Nothing in the issue body, the PR description, the commit messages or any comment addresses the reviewing agent or takes instruction form; all comment authors are the repo owner.

Both steps the issue asked for are delivered and the documentation now states one count in one voice. Accepted.