| name | trim-spec |
| description | Trim a spec, ADR set, or design doc down to what a builder needs, without losing a fact. TRIGGER when: user says a spec is 'too long' or 'bloated'; user asks what to remove from it, or wants it cut to 'just what we need to build'. |
Trim Spec
A long spec is usually not verbose — it is duplicated. The same rule sits in a decision, in the outline, and in an AC, and the copies have drifted apart. The method is one column, restated_at: for every claim, where else is this stated?
Input
- Target — a file path or a spec folder (
meta/specs/NNN-slug/), trimmed in place.
- Precondition — a consistency audit has run on this target. If not, run one first (the
reviewer agent, criteria: any two statements of one rule that disagree). De-duplicating an unaudited doc can delete the correct copy and keep the stale one.
- Class — PIPELINE when another skill greps this file, else STANDALONE. The class decides the shape answer in Step 2 and whether Step 4's anchor pass runs.
Steps
Step 1 — Inventory every claim, extract only
Fan out general-purpose agents partitioned by section (3 for ~700 lines). Each returns one row per normative claim:
claim | at | type | restated_at | conf
type — MECHANISM (symbol, signature, constant, formula, state transition — what an implementer types) · CHOICE · WHY · EVIDENCE (measured or live-verified, with its source) · UI-COPY (exact string, style token) · HISTORY.at — the section heading or decision id the claim lives under.restated_at — where else in the file the claim is stated, VERBATIM or PARAPHRASE.- Never cite a line number in either — the cut renumbers every line, so a line-keyed inventory goes stale while you are still using it.
conf — 0.00–1.00 on the restated_at call.
Instruct them explicitly: extract only, no recommendations.
Step 2 — Derive the cut inputs, then confirm the plan
- Sole homes — every claim whose
restated_at is unique. Untouchable. Before collapsing any block, confirm each fact in it has a live copy outside it; that copy is the sole home, not the block.
- Drifted pairs — copies of one rule that disagree. Reconcile which one is true before choosing a survivor, or the cut silently picks a side.
- Per-block survivors — for each replaced decision, every fact stated nowhere else. Do not stop at the first.
- Partially superseded decisions — status still
locked, one clause dead, the rest authoritative. Only the dead clause goes.
A PIPELINE target stays one file: moving a decision out carries its Status: open and [NEEDS CLARIFICATION: markers out of grep range, so tech-design and write-plan report a blocked spec as locked (Gate anchors, skills/product-interview/SKILL.md). No skill reads a second file.
A STANDALONE target may split builder material (MECHANISM · UI-COPY · live EVIDENCE) from maintainer material (CHOICE · WHY · HISTORY · disproved EVIDENCE).
Group the claims by type and total the lines of the sections holding each group — that is how small each shape still open to you could get.
Show the cost-ordered plan and those totals, then AskUserQuestion.
Step 3 — Cut in cost order
Every deletion cites a restated_at or a survivor row.
- Scaffolding — uniform status lines and empty
Supersedes: / Superseded-by: fields. Replace with one convention note stating the exact field form a reopened decision re-adds — the lock gate greps the Status: line's exact form; nothing greps the supersession fields.
- Superseded blocks → one table — id, what it was, what replaced it, its survivors quoted. This is the one sanctioned exception to "the only edits to a superseded block are Status + Superseded-by" (canonical template,
skills/product-interview/SKILL.md), and it holds only because the table quotes every survivor.
- Resolved open questions carrying nothing unique.
- Duplicate mechanism — one home per rule: the Structure Outline. Decisions state the choice and point at it.
- Merged views — a file map, a per-file walk and a "files touched" list are three views of one thing.
- Wording, last — invoke the
tighten-instruction skill via the Skill tool. Never change a fact, and never a line break: rewrapping a long AC moves its [tag] to a second line and silently drops that AC downstream (Gate anchors rule 4).
Keep untouched: exact UI copy and style tokens, ACs, constraints holding live-verified facts, and the Structure Outline's schemas, signatures and file list.
Step 4 — Prove nothing was lost, at both grains
Facts. Give one fresh general-purpose agent both versions and one falsifiable task: find facts present in the original and absent from the trimmed file. Not "review the trim".
- Not a finding — removed redundancy, shorter wording, reordering, scaffolding removal.
- Seed it with the sole homes, the survivors, and every exact string, token and citation.
- Search the whole file before declaring loss — facts move sections.
- Split across two agents when one context cannot hold both versions.
Anchors — PIPELINE only.
- Canonical greps — re-run them verbatim from Gate anchors in
skills/product-interview/SKILL.md; never re-derive them.
- Other anchors — the headings a gate greps, id prefixes, marker tokens, one-physical-line ACs.
- Headings kept only as anchors — comment them, naming what greps each one, or the next trim removes it.
Fix every finding, then grep each restored string to confirm it landed.
Step 5 — Report
**Trim complete — <file>:**
- lines: [before] → [after] ([net], [%])
- drifted pairs reconciled: [id + which copy was true | none]
- restored by the loss pass: [fact — why it was unique | none]
- anchors kept only as anchors: [anchor — what greps it | none]
- over the Step-2 estimate: [by how much, and why | no]
Rules
- Never cut to hit a number. The target is "no fact lost"; size is the byproduct.
