plan-tighten

Plan Tighten

Surgically trim a plan doc. The git commit is the audit trail — author reverts specific chunks they disagree with. Different mental mode from plan-review (correctness) and plan-incorporate (applying review feedback): this is a focused pass on writing tightness only. Do not change technical decisions, do not re-litigate scope, do not rewrite voice — only cut.

Inputs

• $0: Doc identifier (e.g., 04d-oltp-sql-engine) or path to a single plan doc
• Plans directory: docs/plans/ (or the project's established plans directory)

Phase 0: Preconditions

1. Refuse if uncommitted review files exist for this doc: docs/plans/$0*review*.md. Reviews must be incorporated first — they may inform what's canonical or load-bearing. Tell the user "run /plan-incorporate first" and exit.
2. Refuse if the working tree is dirty for this doc. git diff --quiet -- docs/plans/$0*.md must succeed. Each tighten pass should be a clean, reviewable commit so the author can revert specific chunks.

Phase 1: Read Context

1. Read the target doc docs/plans/$0.md and its companion test harness docs/plans/$0-test-harness.md (if it exists)
2. Read the parent architecture doc and plan index — so you know what's canonical there vs. duplicated here
3. Read sibling plan docs only as needed to verify candidates are duplicates (do not read everything proactively — that's a waste of context)
4. Record wc -l baseline for the diff stats at the end

Phase 2: Identify Cut Candidates

Pass through the doc and tag candidates by pattern. Do NOT edit yet — build the full list first so Phase 3 can decide whether the total reduction is worth it.

Patterns to cut

• Review residue: "Previously open: …", "addressed in R2", parenthetical references to prior-round feedback. Once incorporated, these are noise — the disposition table is the audit history.
• Restated rationale: the same "why" appears in 3 places (motivation, summary, decision log) without each adding distinct content. Keep the canonical occurrence; cut the others or replace with a one-line cross-reference.
• Defensive justification: "Why X over Y" sections that are 10× longer than the decision warrants. Two sentences usually suffice unless Y is a non-obvious alternative a reader will independently propose.
• Pre-explained tables / table-explained prose: prose paragraph immediately followed by a table that says the same thing. Keep one (usually the table).
• Illustrative code with no non-obvious logic: a 30-line code block where the function signature + a sentence of prose conveys the same information. Cut the body, keep signature + prose. But keep code that shows non-obvious logic, ordering invariants, edge-case handling, or wire-format details.
• Duplicate code blocks: same function shown twice with small diffs across sections. Show once, note the variant in prose.
• Test enumeration verbosity: 12 bullet-points each starting "test_a_does_…" where the difference is one phrase per bullet. Group by what's covered (e.g., "test_a covers id-based dedup across 4 cases: empty seen-set, single-id seen, multi-id seen, post-compaction id …"). Keep the test count and coverage commitment; cut the per-bullet ceremony.
• Adjacent overlapping sections: "What this supersedes" + "What gets removed" + "Migration" often re-cover the same deletions. Consolidate into one section per concern.
• Stale "Open questions" entries: questions that have been answered elsewhere in the body. Move the answer to its proper section if needed, delete the open-questions entry.
• Defensive doc sections: paragraphs anticipating reviewer questions where the answer is already implicit in the design.
• Connecting phrases that don't connect: "Note that…", "It's worth mentioning…", "As discussed above…" leading into a sentence that stands on its own. Cut the lead-in.