improve-solution git:20260916.8d1a006A

Immutable. This exact content is served forever at /api/v1/blob/033d09d1b291b42b.

---
name: improve-solution
description: Propagates every decision, correction, and override from a solution-design conversation into design-doc.md and implementation_plan_outline.md so that every affected statement is rewritten to the current truth — consumable by agents with zero human interpretation — then spawns an independent /rootcause-review of the updated plan and closes the feedback loop. Use after any dialogue that changed a solution design, by running /improve-solution [path-to-design-dir].
---

# Improve Solution — Conversation-to-Documentation Propagation

## Trigger

`/improve-solution [dir]` after a conversation that produced decisions, corrections, or
overrides about a solution design. `dir` is the directory holding `design-doc.md` and
`implementation-plan/implementation_plan_outline.md` (if omitted, discover it from the
conversation — e.g. `.designs/<issue>/` — and confirm the paths before editing).

## The Contract This Skill Enforces

The consumer of these documents is ALWAYS an agent, an LLM, or a formula/SKILL executing
what is written. It is NEVER a human. An agent consumer takes whatever text it lands on
literally — it does not arbitrate between a correction section and the stale text below it.
Therefore:

**RULE 1 — Single truth, stated everywhere.** After this skill runs, ANY section of either
document read in isolation states the current decision. A document that needs a precedence
rule to be read correctly is BROKEN for agent consumption.

**RULE 2 — Sources are edited; derived documents are reconciled whole.** `design-doc.md`
is the source of truth. `implementation_plan_outline.md` is derived from it. A derived
document is never patched with correction blocks — it is regenerated by the project's
planning pipeline when available, or fully rewritten section-by-section to match the source.

**RULE 3 — Batch propagation, never incremental.** Collect ALL decisions first, then apply
them in ONE propagation pass against a complete impact map. Editing per-decision as answers
arrive guarantees stale cross-references in an interdependent document.

**RULE 4 — Verification is mechanical, and it hunts the OLD text.** After editing, grep for
every superseded term, value, flag, option label, and test name. Verifying only the new
text you wrote proves nothing about the restatements you missed.

## Banned Moves (each one caused a real, documented failure)

1. **Precedence sections.** Never add a "decision register overrides the text below" or
   "where this conflicts, X governs" clause as a substitute for updating the text below.
   A dated decision-history appendix is permitted ONLY after every live statement is
   already rewritten.
2. **Hand-patching derived documents.** No delta blocks, correction sheets, or "deltas
   the implementer must apply" prologues on top of a stale body.
3. **Verifying only what you added.** The gate is a sweep for what should be GONE.
4. **Declaring done without the independent review (Phase 5).** Self-review is not review.
5. **Inferring decisions.** A clarifying question from the operator is not a decision.
   Ambiguous ledger entries go back to the operator before propagation, never guessed.
6. **Jargon in operator communication.** No document-internal shorthand (component numbers,
   option codes) and no invented metaphors. Use the project's own documented terms or
   standard computer-science terms, and spell out any label on first use.

## Process

### Phase 1 — Decision Extraction (whole conversation → one ledger)

Mine the ENTIRE conversation — not just the last exchange — for:
- explicit decisions and choices (including every AskUserQuestion answer)
- rejections and scope cuts ("scrap that", "declined", "cut it")
- overrides of the design's or issue's own acceptance criteria
- factual corrections (wrong citations, contradicting constants, stale justifications)
- clarifications that constrain how something must be implemented

Write a Decision Ledger to a ledger file in the scratchpad (NEVER into the shipped
documents) — every later gate appends its evidence to this same ledger file:

| ID | Decision (operator's words + precise restatement) | What it supersedes | Evidence (quote) |
|----|---------------------------------------------------|--------------------|------------------|

**Ambiguity gate (quote-closure rule):** an entry whose Evidence cell lacks a verbatim
operator quote IS inferred, by definition — no self-judgment involved — and cannot enter
Phase 2. For every inferred entry, and for any operator question that could be mistaken
for a decision, ask the operator NOW via AskUserQuestion — in plain language, with any
physical or technical constraint that bears on the answer stated INSIDE the question,
before they answer. Do not proceed carrying an inferred decision.

### Phase 2 — Impact Map (find every restatement)

For each ledger entry, enumerate EVERY location in `design-doc.md` that states or restates
the superseded content. Design documents restate each decision in many places — check at
minimum: executive summary, constraints list, acceptance-criteria table, every component
section, dependency graph, interface table, data model, decisions table, risk registry,
conflict/trade-off matrices, gap dispositions, and the embedded phase plan — a floor, not
the document's shape: every section the document actually has gets checked.

Mechanical assist: grep the document for every superseded flag name, constant, option
label, test name, and distinctive phrase from the ledger. Record the result as a checklist
(decision × location) in the ledger file. The propagation pass executes this checklist —
nothing is edited that is not on it, and nothing on it is skipped.

### Phase 3 — Source Propagation (design-doc.md)

Apply the impact map completely:
- REWRITE each affected statement to the current truth. Keep provenance as a short dated
  parenthetical in place: "(decided YYYY-MM-DD: X, superseding Y)".
- An overridden acceptance criterion is rewritten IN the acceptance-criteria table itself,
  with the override and its date recorded in that row. This matters: a later peer review
  will otherwise correctly flag the document as failing its own criteria.
- Constants and numbers: fix every restatement — tables AND prose AND test names.

**GATE (mechanical, must pass before Phase 4):** the contradiction sweep. For each ledger
entry, grep `design-doc.md` for its superseded terms. Every remaining hit must sit inside a
dated provenance note. Paste the sweep commands and their output into the ledger file.

### Phase 4 — Derived Reconciliation (implementation_plan_outline.md)

Choose ONE, in this order of preference:

**(a) Regenerate (operator-approved procedure).** If the project has a planning
skill for this document, regeneration is the correct path — and the runner must be explicit
and authorized, never a helper chosen silently:
1. DELETE the old derived file FIRST via `git rm <file>`, so neither the working tree nor
   git's staging area carries the old content (history keeps it recoverable) and no old
   misinformation or bias can enter the regeneration; forbid the regenerator from reading
   prior derived artifacts as sources.
2. Spawn a sub-agent with the Agent tool whose prompt IS the operator's dictated sentence
   VERBATIM — "Use the skill tool to load and run /design-plan-impl on <path>/design-doc.md"
   (substituting the project's planning skill) — with NOTHING prepended and NOTHING
   appended. No source-of-truth glosses, no constraint lists, no return-format demands:
   if the run needs accompanying commentary to come out right, the documents are not
   self-sufficient, and THAT is the defect to fix. Anything beyond the sentence requires
   the operator's own dictation.
3. If the operator's governed pipeline runs elsewhere (e.g. a dispatched factory agent),
   hand the operator the exact dispatch command instead — never substitute a different
   runner without asking.

**(b) Full rewrite in place.** If regeneration is unavailable in this environment, rewrite
every affected phase/section so each is self-contained and consistent with the source — an
extractor reading ONLY that section must build the current design, not the superseded one.
Re-verify every file:line citation your edits touch against the live tree; explicitly mark
anything you did not re-verify as `[not re-verified]`.

**GATE:** run the same contradiction sweep on the plan, PLUS the extraction test: read each
phase section in isolation and record a per-section verdict row in the ledger file —
section name → one superseded term searched → ABSENT/FOUND. A section without a row was
not tested; a FOUND row loops back to the rewrite before this gate can pass.

### Phase 5 — Independent Peer Review (MANDATORY)

Spawn a sub-agent with the Agent tool (general-purpose). Its prompt IS this sentence
VERBATIM, with nothing prepended and nothing appended:
"Use the skill tool to load and run /rootcause-review on <dir>/implementation-plan/implementation_plan_outline.md"

It must NOT receive this conversation's rationale, the ledger, or any summary of the
decisions — the entire value of this step is uncontaminated eyes reading what is actually
on the page, the way the next agent consumer will. Wait for its completion.

### Phase 6 — Feedback Loop

Read the review's appended findings. For each finding, exactly one of:
- **FIX** — re-enter the Phase 3/4 rules for the edit (impact-map the fix, sweep after), or
- **ESCALATE** — a finding that contests an operator decision goes back to the operator as
  a plain-language AskUserQuestion. Never silently reverse an operator decision because a
  reviewer disliked it; never silently dismiss the reviewer either.

Record a disposition table in the ledger file — one row per finding: finding → FIX (with
the exact edit anchor: file plus the old→new fragment) or ESCALATE (with the question
asked and the answer given). A finding without a row is ignored, and ignoring is banned.

Maximum TWO review cycles (re-spawn Phase 5 after a FIX round). Findings still open after
cycle two go to the operator in the final report, stated plainly — and any fixes applied
AFTER the final review round are named there as reviewer-prescribed but unverified.

### Phase 7 — Handoff

Stage the changes (`git add`); never commit unless the operator asked. Deliver the final
report in plain language using only the project's documented terms:
1. Decisions applied — count, one sentence each.
2. Sweep results — the superseded terms searched and the zero-live-hit confirmation.
3. Review verdict per round; what was fixed vs escalated; any fixes applied after the
   final round, named as unverified.
4. Exactly ONE next action for the operator — when unverified fixes exist, that action is
   the offer of a verification-only extra review round.

## Success Criteria

1. Every decision from the conversation appears in the ledger with quoted evidence.
2. `design-doc.md` passes the contradiction sweep — no live statement of any superseded
   decision anywhere in it.
3. `implementation_plan_outline.md` was regenerated or fully rewritten — it contains no
   correction blocks and passes the sweep and the extraction test.
4. An independent `/rootcause-review` ran on the updated plan; every finding is fixed or
   escalated, none ignored.
5. The operator received a plain-language report ending in exactly one next action.