Autonomous Design Refinement

Multi-pass workflow that refines requirements documents (PRD, technical design, assumptions, and any supporting materials they reference) to implementation-ready state. Each pass runs implementation-readiness-check for a small, ranked batch of questions, investigates them one at a time, folds each answer into the documents the moment it is known, and records progress in a state file on disk — so an interrupted run loses at most the questions in flight (three or fewer) and resumes from where it stopped.

The name says which stage it serves. autonomous-prd-refinement refines a draft PRD on its own, before any design exists; this skill runs once the technical design exists and refines the PRD, design and assumptions together.

What Is This Skill?

This skill automates the loop humans do manually: run a readiness check, get questions, investigate them, update the requirements documents, check again, find the new questions the updates exposed, and repeat until the documents are solid enough to implement against.

The goal: by the end of the run, the PRD, technical design, and assumptions document are complete enough that implementation can proceed without the AI needing to guess or ask. Remaining uncertainties live in the assumptions document as implementable assumptions: business ones a stakeholder can validate, and the few facts research could not reach as technical assumptions naming what blocked it. Build choices are decisions in the Technical Design, not assumptions.

The shape of the work matters as much as the goal. The run is long — hours, often more than one session — and sessions end without warning: usage limits, sleep, network. So the skill is built around three rules:

1. Every answer lands immediately. An investigated question is written into the documents before the next question starts. Nothing valuable waits in memory for a later "fold" step.
2. State lives on disk, not in the conversation. A small markdown state file records every question and its status. A fresh session reads it and continues; it never restarts.
3. Small batches, ranked by impact. A pass handles a dozen questions, not a hundred. More passes are cheap because each one is checkpointed; one giant pass is expensive because losing it loses everything.

This is an orchestrator skill — it coordinates:

• implementation-readiness-check — to surface gaps and questions each pass
• investigate-question — one question at a time, in a subagent
• assumptions-document-writing, technical-design-writing-standards, prd-writing-standards — applied when writing into each document

When to Use

Use this skill when:

• You have a draft PRD and Technical Design document for a feature
• You want them implementation-ready with minimal manual intervention
• You are willing to let the AI run for a long time, possibly across several sessions
• You want the AI to dig into code, data, and APIs to answer its own questions rather than asking you

Do NOT use this skill when:

• You want to stay closely involved in every decision — run implementation-readiness-check yourself and use investigate-question on specific items
• One readiness-check pass is enough for the feature's size
• You need to implement immediately and cannot wait for multiple passes

Required Inputs

1. Document paths — both of the following are required (the skill will not run without them):

   • PRD document
   • Technical Design document

   The skill also looks for these optional supporting materials:

   • Assumptions document (created if it doesn't exist and assumptions are identified)
   • Any other documents the PRD or tech design reference (data model docs, mockups, API specs, etc.)
2. Access to the codebase and relevant environments — investigation reads code and may query databases, test APIs, or inspect infrastructure. Credential discovery follows investigate-question: check for skills that document credential handling, then the README, then existing config, before asking the user.

Parameters

There is no minimum pass count: per-question checkpointing makes extra passes cheap, so the yield rule decides when to stop. The final verification in Phase 7 is the mandatory re-check.

Effort. Every subagent this skill launches — discovery, investigation, writer, conformance — runs at high effort or above (subagents inherit the session's effort unless the launcher sets one, so a session at a higher level carries that level through); the work is real research and careful editing, and the caps above are what bound cost, not the effort of individual agents. The caps are binding regardless of session mode: a session running in an exhaustive or "ultracode" mode does not license parallel discovery panels, a larger batch, or auditing everything adjacent to the feature. Those are exactly what the scope gate below exists to prevent.

Operator note: a skill cannot change the session's effort or mode. If you want the run to stay inside a session limit, start it in a normal session, not an exhaustive one.

The Scope Gate

A question earns a place in a pass only if someone writing this feature's code would have to make a judgment call without it. That is the whole test.

Things that fail the test, even when they are true and interesting:

• Pre-existing defects in surrounding systems that do not block this feature
• Infrastructure hygiene, hardening, or audit findings across the fleet
• "Would it be better if…" redesigns of contracts the documents already settle
• Questions answerable in two minutes by reading the code — answer those during discovery and never raise them
• Questions whose answer would create an obligation no PRD statement implies. Refinement never adds scope. A question passes when its answer narrows or makes precise something the PRD already requires (which records, what format, what happens when a required step fails). A gap the feature cannot work without goes to the design's Open Questions, not to Noticed, out of scope
• Under the Salvage posture (below), questions about how existing code behaves in cases the PRD does not call for

When an investigation trips over something out of scope, write one line under Noticed, out of scope in the state file and move on. Do not investigate it, do not write a script for it, do not fold it into the documents. Those lines are the user's to act on later.

The implementation-readiness-check skill's own guidance — prefer fewer, high-signal questions over exhaustive lists — governs discovery here. One reader of the documents, in implementation mode, capped and ranked. Not a panel of independent reviewers each producing a list.

Existing Code Posture

Before the first discovery, record in the state file how existing code in the feature's area is treated. These are the same two terms technical-design-writing-standards uses:

• Preserve (the default): the existing code is in production, or other work relies on it. Its behavior constrains the design, and questions about fitting the new work to it pass the gate normally.
• Salvage: the existing code is unreleased, or left over from earlier work being restarted. The design reuses what fits the PRD and switches off, one line each, what the PRD does not ask for. It never designs around that code, and questions about how it behaves in cases the PRD does not call for fail the gate.

An area can be mixed; record it per component ("Salvage for the retry worker; Preserve otherwise").

The posture is stated, not researched. Take it from the user, then the PRD, then the design's Existing Code section, in that order when they disagree. Never work it out from deploy or merge history. If none of them says, use Preserve, and say so in one line when the run starts so the user can correct it before a pass runs; repeat it in the first checkpoint summary.

Every subagent gets the posture: discovery, investigation and writers. For Salvage code it overrides implementation-readiness-check's invitation to ask about the behavior of existing code: only behavior a PRD requirement relies on is in scope. The writer records the posture as one line in the design's Existing Code section, so it outlives the state file.

State File

Location: alongside the PRD — {feature}-design-refinement-state.md in its directory, under docs/prds/ or docs/changes/.

Lifecycle: created in Phase 1, updated after every question, committed with the documents at each pass checkpoint, and deleted in Phase 7 when the run completes. It is scaffolding, not a deliverable.

Editing rule: update rows and counts in place. Never regenerate the whole file from memory — that is how status gets silently lost.

Template

# Design Refinement State — {feature}

Started: {date}   Current pass: {N}   Status: {In progress | Paused: reason}
Branch: {branch the documents are on}
Existing code posture: {Preserve | Salvage | per component} (source: {user | PRD | TD | default})
PRD words: at start {wc -w} · growth baseline {wc -w; reset when the user says continue after a growth pause}
Last updated: {date time}

## Documents
| Document | Path |
|---|---|
| PRD | … |
| Technical Design | … |
| Assumptions | … |
| Supporting | … |

## Passes
| Pass | Surfaced (new) | Taken | Resolved | Assumptions | Deferred | Blocked | Dropped |
|---|---|---|---|---|---|---|---|
| 1 | 31 | 12 | 9 | 2 | 1 | 0 | 0 |

## Questions
| ID | Pass | Question (one line) | Type | Impact | Conf. start → now | Status | Landed in |
|---|---|---|---|---|---|---|---|
| Q1 | 1 | … | Technical | HIGH | 55 → 95 | Resolved | TD §Data Models |
| Q2 | 1 | … | Business | HIGH | 40 → 80 | Assumption | DATA-001 |
| Q3 | 1 | … | Technical | MEDIUM | 60 → 60 | Blocked: needs dev DB access | — |

Status values: Pending · Investigating · Answered, not folded · Resolved · Assumption · Deferred (carried to next pass) · Blocked · Dropped (failed the scope gate on closer look; reason in notes). A Reframed question is replaced by a new row marked Pending with "reframed from Qn" in its notes.

## Question notes
One block per question that is not simply Resolved — required for Deferred, Blocked, and Answered-not-folded — holding the current proposed answer, evidence pointers (file:line, query, doc section), and what was checked. This is what the next investigation starts from and what a resumed session folds from.

### Q3
Proposed answer: … Evidence: … Checked: …

## Exploration scripts
| Script | Question | Finding |
|---|---|---|

## Conflict check
Pass 1: {date} · {n} earlier criteria changed · {r} Replaces lines written · {q} raised as questions ({Q ids})
Changed after pass 1: {labels of criteria added or changed since the pass-1 check}
Completion: {date} · {criteria re-checked} · {result}

## Register re-sort
Pass 1: {date} · {n} open entries · {d} moved to design · {w} written up · {s} settled by lookup · {t} moved to technical · {q} raised as Technical questions ({Q ids}) · {b} stay business

## Noticed, out of scope
- {one line each — things investigation tripped over that fail the scope gate}

## Blockers
| Blocker | Questions affected | What unblocks it |
|---|---|---|

## Next action
{The single next thing to do. A resuming session starts here.}

Orchestration Model

The orchestrator stays thin. It reads the state file, decides what to do next, launches subagents up to the concurrency limit, and records each result. It does not read full documents or do investigation itself.

Subagents return distilled results, not transcripts. If a subagent's result would run past a page, it is doing too much per call — split the work.

Interruption Recovery

If the session ends at any point:

• Every question already marked Resolved or Assumption is in the documents. Nothing to redo.
• Questions marked Investigating were in flight (at most three). On resume, re-run them; that is the whole cost.
• A question marked Answered, not folded has its answer in Question notes. On resume, fold it first; no re-investigation.
• The state file's Next action says where to pick up.

If a subagent fails, retry once. If it fails again:

• Investigator: mark the question Blocked with the error and continue with the next question.
• Writer: the answer is already known — never discard it. Record it verbatim under Question notes, mark the question Answered, not folded, and retry the fold before launching the next investigation.
• Discovery: the pass cannot proceed. Set Status to Paused: discovery failed with the error and report to the user.
• Conflict check: record not run and the error under Conflict check, and say so in the completion report. The completion commit then carries no Conflict check: line, so the build runs its own full check.
• Conformance: skip it for this pass, note the skip in the state file, and run it at the next checkpoint.
• Final verification: report the documents as not verified; do not mark them ready.
• Consolidation writer: leave that document as the completion commit has it and say so in the consolidation summary.
• Consolidation check: do not stage the consolidation; report it as unchecked.

Never let one failure end a pass.

If a session-limit or context warning appears: finish the in-flight question, update the state file, set Status to Paused: session limit, and stop cleanly. Do not start new questions into a closing window.

Process

Phase 1: Setup and Re-orientation

Pending feedback changes come first, on a fresh start and on every resume. A {name}-pending-feedback-changes.md beside the PRD means a stakeholder round has changed what it must say: apply it with assumptions-document-feedback, which resumes from that file (its Step 4a, "Resuming"), commit that amendment on its own, then continue.

1. Check for a state file at the expected location. If present, read it, confirm the documents still exist, and continue from Next action. Do not restart from discovery unless the state file says the current pass is complete.
2. If starting fresh, locate all requirements documents — PRD, technical design, assumptions (if any), and supporting materials the documents reference — and create the state file from the template. Record the paths, the PRD's word count, and the existing code posture; do not read full contents here (search the PRD and design for a stated posture rather than reading them whole).
3. Verify environment access — databases, APIs, infrastructure, whatever investigation may need. Record limitations up front under Blockers rather than discovering them mid-pass.
4. Confirm the repo state — the documents' branch, and that the tree is clean apart from the requirements documents and state file. Record the branch in the state file.

Phase 2: Discovery (once per pass)

Launch one subagent to run implementation-readiness-check against all the requirements documents, including supporting materials, with the scope gate and the existing code posture in its instructions. (That skill is not model-invocable; the subagent reads its SKILL.md and follows it.) It returns questions with proposed answers, confidence, impact, and Technical/Business classification.

Pass the subagent the state file too. A question is new only if it is not already tracked there under any status and is not on the out-of-scope list. Everything else the subagent would have raised is a repeat — it reports the repeat count and moves on. This is what makes the Surfaced count and the yield stop mean something.

The subagent must:

• Apply the scope gate before including anything
• Do its homework — answer by reading code where reading code answers it, and not raise those
• Skip questions the assumptions document already dispositions, unless it found evidence the assumption is wrong
• Return at most 2× the per-pass cap candidates, ranked by impact and uncertainty (HIGH impact and low confidence first)

The orchestrator takes the top Questions per pass into this pass, marks the rest Deferred in the state file, and records the pass's Surfaced (new) and Taken counts.

In pass 1 only, run the conflict check (implementation-lifecycle, "When Later Work Changes Earlier Requirements") in a second subagent alongside discovery, against the whole PRD. Tell every readiness-check subagent this skill launches, each pass's discovery and the final verification, to skip its own. The check finds the criteria in the repo's other PRDs and change directories that this PRD changes. An intended change is folded in as a Replaces: line on the new criterion (prd-writing-standards) by a writer subagent, serialized with the other folds, with no question. An unintended one, where this PRD would break behavior someone asked for, enters the Questions table as a Business question and competes for a slot on impact like any other. Record the result under Conflict check in the state file. From then on, the orchestrator adds under Changed after pass 1 the label of every criterion a writer or conformance subagent reports adding or changing.

In pass 1 only, re-sort the assumptions register in one more subagent alongside discovery: every open entry, not only ones this run adds, by assumptions-document-writing's "Sort Every Entry by What Would Settle It", with its Gate 1 lookup. Entries written before the design existed were sorted without it, and they are what fills a stakeholder review with questions no stakeholder needed. Tell the subagent that business is not the kind left over and that an entry's importance plays no part: for each entry it keeps as business, it returns what would be built differently if they chose otherwise. The subagent edits nothing; it returns each entry it would move, with its kind and one line of reason. When it moves nothing, the orchestrator sends the kept entries to a second fresh subagent, which reads only each entry and those answers and says which it doubts; the orchestrator re-sorts each doubted entry itself. The orchestrator then:

• Build choice: hands it to a writer, serialized with the other folds, who records the decision in the Technical Design with its reasoning and the alternative it beat, and moves the entry to the validated table as Moved to design.
• Fact or prior ruling the lookup settled: the same writer folds the answer where it belongs and moves the entry out of the body, as Gate 1 says.
• One sensible answer, or both answers building the same thing: the same writer states it where it governs and moves the entry to the validated table as Written up.
• Fact with its blocker already named: the same writer moves it, under its ID, to the register's Technical Assumptions section in that section's format.
• Fact not yet researched: enters the Questions table as a Technical question, pointing at its entry, and competes for a slot like any other; its disposition (below) decides where it ends.
• Business: stays, and is not a question for this run unless discovery finds evidence it is wrong. The same writer adds its If they choose otherwise line from the subagent's answer, says whose it is if it was asked of the wrong person, restates a question worded for the build, and rates its Impact.

Record the counts under Register re-sort in the state file.

Questions carried from a prior pass (Deferred, or Blocked with the blocker cleared) come first in the ranking. Draining the backlog beats surfacing new questions.

Phase 3: Resolve, One Question at a Time

For each question in the pass, in rank order, with at most Concurrent investigations in flight:

1. Triage. A pure business-judgment question — one no amount of technical investigation can move — skips investigation (that is investigate-question's own exclusion) and goes straight to step 3 as an assumption at the best-supported answer. Everything else proceeds.
2. Mark it Investigating in the state file, then investigate — launch investigate-question in a subagent with the question, proposed answer, confidence, impact, classification, the existing code posture, the Question notes evidence so far, and the document paths. It returns a verdict (Resolved / Refined / Blocked / Reframed), confidence, the answer written as document-ready prose, evidence pointers, and any exploration script it created.
3. Fold immediately — launch a writer subagent to integrate that one answer into the right document and section, following the disposition rules below, the writing standard for the target document (for the design, including its section on existing systems) and the existing code posture. Integrate into the most relevant existing section; create a section only when nothing fits. Folds are serialized: investigations may overlap, but only one writer runs at a time, so two writers never touch the same document at once.
4. Update the state file — status, confidence, where it landed, the script (if any), the Question notes block for anything not simply Resolved, and Next action.

Do not batch steps 3–4 for later. The pass's value is only as safe as the last question written.

Disposition rules

• Technical, confidence ≥ 90%: fold into the Technical Design.
• Technical, confidence < 90%: mark Deferred for another pass, with the improved answer and evidence in Question notes. Never park a technical question in the business sections of the assumptions document to make the counts look clean. If a technical question is deferred in two consecutive passes at unchanged confidence, investigation has hit its ceiling, and what ends it depends on its kind (assumptions-document-writing, "Sort Every Entry by What Would Settle It"). A build choice is recorded in the Technical Design as an explicit design decision with rationale, the alternative it beat and the evidence gap stated, and marked Resolved by decision: an engineer must choose, and the design is where that choice belongs. A fact whose source investigation could not reach is written as a technical assumption, naming the blocker and what would settle it, and marked Assumption.
• Business, ≥ 95%, whatever the impact: fold the decision into the PRD.
• Business, < 95%: write it as an assumption stating the best-supported implementable answer, following assumptions-document-writing — plain-language proposed answer in the business's own terms, what their answer changes, why we believe it, confidence, Impact by that skill's definition rather than the question's own rating, confirm-or-correct format. Technical detail the stakeholder cannot judge goes in the Technical Design, not the assumption. Proceed on that basis; stakeholder validation is asynchronous and is not a reason to pause. Use a Blocking Open Question only for the rare case that skill defines.
• Blocked: record what is needed. If three or more questions share one blocker, pause and report rather than continuing degraded. A blocked fact still blocked at completion becomes a technical assumption naming the blocker; a blocked question is never left only in the state file, which completion deletes.
• Reframed: the investigation showed the question was wrong. Mark the original Dropped (reason: reframed) and add the reframed question as a new Pending row noting its origin; it competes for a slot in the next pass on its own merits.

Whenever a fold changes what the PRD says a screen shows, at any confidence, the writer redraws every mockup state it changes in the same fold (prd-writing-standards, "Mockups Show What the Criteria Require").

Phase 4: Conformance (once per pass)

After the pass's questions are landed, launch one subagent to read all requirements documents and check placement and standards. It fixes what it finds and returns a short list.

Relocate, never delete. The exceptions are the decision history and descriptions of existing code in the row above, which git already keeps, and superseded entry text and edit narratives in the assumptions document, which version control likewise keeps (assumptions-document-writing). Every other detail is preserved — copied to the right document, integrated (not appended), then removed from the wrong one. Apply each document's writing standard. Verify cross-document links and assumption-ID references resolve.

Conformance also confirms that the Technical Design's Open Questions section, and any statement it makes about which PRD acceptance criteria or assumptions it covers, are still true after this pass's edits. Anything conformance cannot fix because it is design work, not placement, goes into the state file as a Pending question for the next pass — not into a report the next session never reads.

Phase 5: Checkpoint

1. Update the Passes table and Next action in the state file.
2. Commit the requirements documents (including any mockups a fold redrew) and the state file — only those files; exploration scripts are the user's to stage — as docs({feature}): design refinement pass {N} — {one-line summary}, with a body naming what changed. This is the default; the user's instructions override it (pre-commit-validation, "Who Commits"), and then the files are staged and the message presented. Committing at the pass boundary is what protects the work from other sessions' git operations in the same checkout. It never pushes.
3. Output the checkpoint summary:

=== Pass {N} complete ===
Surfaced (new) {S} · taken {T} · resolved {R} · assumptions {A} · deferred {D} · blocked {B} · dropped {X}
Documents: PRD +{n}/-{m} ({start} → {now} words) · TD +{n}/-{m} ({now} words) · Assumptions +{n}/-{m} ({k} entries)
Exploration scripts this pass: {list or none} (not staged — yours to add)
Out of scope noticed: {count} (see state file)
Blockers: {list or none}
Committed: {short hash} (or: staged, message follows, when the user said not to commit)
Next: {pass N+1 | final verification | paused: reason}

Phase 6: Convergence

Using the state file's counts only:

• Stop and go to Phase 7 when the pass's discovery surfaced fewer than Discovery yield stop new questions below the threshold and no Deferred questions remain, or when Maximum passes is reached.
• Otherwise start the next pass at Phase 2.

An implementable business assumption written to standard counts as dispositioned. It is not unresolved merely because stakeholder validation is still pending.

Pause and report to the user instead of continuing when:

• A business question genuinely meets the Blocking Open Question standard in assumptions-document-writing
• Three or more questions are blocked by the same missing access or prerequisite
• Two consecutive passes each resolved fewer than two questions — the run has hit a ceiling worth a human look
• The PRD (wc -w at the checkpoint) has grown by more than a quarter and more than 500 words since the growth baseline. Refinement clarifies requirements, so growth that large usually means scope or decision history is being added. Report what grew and let the user decide; if they say continue, reset the baseline to the current count

The ordinary count of business assumptions awaiting validation is never a reason to pause.

Phase 7: Completion

1. Final conformance pass (as Phase 4).
2. Re-run the conflict check for the criteria listed under Changed after pass 1. An empty list counts as a check that ran. Fold or raise its findings as in pass 1; a raised question goes to Phase 3 like the final verification's. Record the result under Conflict check.
3. Final verification — one more implementation-readiness-check subagent, scope-gated, against the finished documents. If it surfaces new questions below the threshold and passes remain, treat them as a new pass and go to Phase 3. If the maximum is reached with questions still below threshold, report Maximum passes reached and mark the documents not ready. Never label that result Converged.
4. Write the completion report (below) from the state file, while it still exists.
5. Delete the state file. The questions that mattered are in the documents; the rest is in the report.
6. Final commit — commit the requirements documents and the state-file deletion as docs({feature}): design refinement complete — {passes} passes, {questions} questions, under the same default as Phase 5. Put the Noticed, out of scope lines in the message body — once the state file is gone, the commit is their only durable home. Put the conflict check's result in the body too, as one line starting Conflict check: (Conflict check: 3 earlier criteria replaced, 1 raised as a question, or Conflict check: no earlier criteria changed): implement-from-requirements reads that line to narrow its own check. Write the line only when both checks ran.
7. Output the completion report:

=== Autonomous Design Refinement Complete ===

Passes: {N}   Final status: {Converged | Maximum passes reached}
Existing code posture: {posture} (source: {source})   PRD words: {start} → {end}
Questions across all passes: {total} — resolved {R}, captured as assumptions {A}, still below threshold {W}

Document updates:
- PRD: {significant changes}
- Technical Design: {significant changes}
- Assumptions: {n} entries added or amended
- Mockups: {screens redrawn, or none}

Exploration scripts: {list, or none}
Out of scope, noticed and not acted on: {list from the state file}

Conflict check: {n earlier criteria replaced, q raised as questions | no earlier criteria changed | not run: reason}
Register re-sort: {d} moved to design · {w} written up · {s} settled by lookup · {t} moved to technical · {q} raised as questions · {b} stay business
Final verification: {clean | N questions, listed below}

Items below threshold (if any): {question — confidence — why}
Blockers not resolved (if any): {blocker — what's needed}

Ready for implementation? {Yes | No — items needing attention}
Next: consolidation (Phase 8), once this commit lands

Recommended next steps:
1. Review assumptions awaiting business validation
2. Address blockers or final-verification items
3. When requirements are ready, after consolidation prepare `stakeholder-review-package` unless declined, then run `phase-split` to size and plan the work without implementing

Phase 8: Consolidation (the last refinement step, after the completion commit)

Refinement folds each answer where it is needed, so after several passes the same rule is often stated in several places. This pass removes those repeats. It is the last refinement pass, it runs once, and it runs whatever the final status.

It starts from a commit. The completion commit is its baseline, so the pass's whole effect is one diff the user can review and one revert. A session that may not commit stops after Phase 7 and runs this phase as soon as the user's commit lands. Never run it on uncommitted refinement work.

It does two things and nothing else:

1. Replaces a repeat with a pointer. When a rule, value, contract or behavior is stated in more than one place, one statement stays, word for word, in the section that owns its subject. Each other statement becomes a pointer to it: the section heading within the design, or the criterion label or assumption ID in another document. A repeat that carries anything the kept statement lacks (a case, condition, number, exception or example) is not a pure repeat: that part stays where it is or, within the same document, moves into the kept statement word for word. A short phrase that names a rule so its sentence reads ("refused as busy, §Locks") is already a pointer, not a repeat.
2. Deletes what the writing standards already exclude: decision history, descriptions of how existing code works (Phase 4's table), and narration about the document itself ("as noted above", "this section describes").

It never rewords. No summarizing, paraphrasing, tightening, or merging sentences into shorter ones. Every sentence that stays reads exactly as it did, except where a pointer replaces a repeated clause. The precision the passes built lives in the exact wording, and shorter wording is how it gets lost.

Two statements that disagree are not repeats. Leave both and add the disagreement to the design's Open Questions; choosing between them is design work.

The PRD and the design stay separate. The PRD says what is being built and why; the design says how. Consolidation never moves text from one into the other. A rule both state belongs to the PRD: its wording stays there, and the design points to the criterion and keeps only how the rule is built. Stakeholders read the PRD and assumptions document on their own, so neither ever gains a pointer into the design. Repeats within the PRD consolidate under the same rules. Criteria labels, Replaces: and Superseded by: lines and assumption IDs are already pointers and stay. The design's criteria coverage table stays too: its test definitions say what each test proves, which is not a repeat of the rule.

Writers. One per document; documents can run side by side, but writers on the same document run one at a time. For a design too long for one careful read, give each writer a range of top-level sections to edit; each still reads the whole document to find where else a rule is stated. A writer replaces a statement with a pointer only when the target still holds the full statement and no pointer already leads to the one it would replace, so two writers never each point at the other's copy and lose the rule.

The check, a separate subagent, compares the documents with the completion commit:

• Every identifier in the baseline is still present: error codes, field and parameter names, numbers with their units, criteria labels, assumption IDs, named tests, quoted user-facing text, and any heading a pointer names.
• Every removed or changed line's content exists word for word where its pointer leads, or falls under item 2.
• Every pointer resolves.

A failed hunk is put back as the completion commit has it; the check never rewrites text to repair it.

If the session ends mid-pass, the edits already made stay. Resume with the documents not yet done, then run the check, which compares everything with the completion commit.

Finish by committing the documents, under the same default as Phase 5, as docs({feature}): consolidate repeats after design refinement — design {before} → {after} words, with a body giving each document's words before and after, the number of repeats replaced, the deletions by category, any disagreements added to Open Questions, and the check's result.

When the requirements are ready, invoke stakeholder-review-package after the consolidation commit to create or refresh the HTML from the final sources, unless the user declined it. Do not wait to be asked; sharing and stakeholder feedback remain optional, and the package skill's existing delivery rules apply. Then hand off to phase-split.

Exploration Scripts

Investigation subagents create scripts in scripts/exploration/ at the project root, per investigate-question:

• Descriptive names: explore-notification-preference-codes.py, test-email-provider-api.py
• Header comment stating the question being investigated
• Read-only operations only — SELECT, GET, list/describe/read
• Dev and sandbox first — read production only read-only, only when nothing else can answer the question, and only where the project allows it (engineering-principles, "Production Data")
• Limit result sets — TOP/LIMIT clauses

A script is warranted only when the question is in scope and a one-off read cannot answer it. Scripts written to audit systems outside the feature's scope are a sign the scope gate was skipped.

Rules and Constraints

DO

• Fold every answer into the documents the moment it is known
• Keep the state file current after every question; resume from it, never restart
• Apply the scope gate at discovery and again during investigation
• Take questions in impact-and-uncertainty order, backlog first
• Relocate misplaced content during conformance (never delete, except decision history and descriptions of existing code in the design, and superseded entry text and edit narratives in the assumptions document; see Phase 4)
• Follow each document's writing standard
• Document evidence and sources for findings
• Stop cleanly on a session-limit warning with the state file updated
• Delete the state file at completion
• Finish refinement with the consolidation pass, on top of the completion commit (Phase 8), then prepare the stakeholder package when ready before handing off to phase planning

DO NOT

• Write to production, or read it beyond what engineering-principles, "Production Data" allows
• Perform write operations (INSERT, UPDATE, DELETE, POST, PUT) against external systems
• Hold investigation results in memory for a later batch fold
• Run more than the configured concurrent investigations
• Run more than one fold writer at a time, or discard a known answer because its fold failed
• Fan discovery out across multiple parallel reviewers to be "thorough"
• Treat an exhaustive or "ultracode" session mode as license to exceed the caps or fan out discovery
• Investigate or script anything that fails the scope gate
• Regenerate the state file wholesale; update it in place
• Delete content during conformance cleanup, other than the decision history, descriptions of existing code, and superseded assumption-entry text and edit narratives Phase 4 names
• Reword, summarize or tighten a sentence during consolidation, or start consolidation before the completion commit lands
• Continue past the maximum number of passes
• Pause merely because business assumptions await asynchronous validation
• Report completion when the final verification surfaced unresolved work
• Commit anything but the requirements documents and state file, or push (pre-commit-validation, "Who Commits")
• Embed client-specific references (credential paths, private repo names) — those belong in your house engineering standards (docs/enso-method-setup-guide.md, "Plugging in your house engineering standards")

Relationship to Other Skills

Example Walkthrough

Starting state

PRD:          docs/prds/user-notifications/user-notifications-prd.md
Tech design:  docs/prds/user-notifications/technical-design.md
Assumptions:  (none yet)
State file:   (none — fresh run)

Pass 1

• Discovery surfaces 23 candidates after the scope gate; the top 12 by impact and uncertainty are taken, 11 marked Deferred.
• Resolve, three at a time. Q1 (notification preference codes in the source system): subagent writes a read-only query, finds 12 codes mapping to 5 delivery channels, 55% → 98%, folded into the Technical Design's mapping section — state file updated before Q4 starts. Q2 (include deactivated accounts?): a meeting note says "import everything for audit trail", 40% → 80%, written as assumption DATA-001. Q7 is pure business judgment: written as an assumption at the best-supported answer. Q9 is blocked on database access; recorded. While investigating Q5, the subagent notices an unrelated retry bug in the sync job — one line under Noticed, out of scope, no investigation.

The session ends here on a usage limit, mid-Q11.

Pass 1, resumed in a new session

• Phase 1 finds the state file: Q11 is Investigating, Next action says "re-run Q11, then Q12, then conformance." Q11 is re-run — the only cost of the interruption, because Q10 had already been folded.
• Conformance moves one API rate-limit detail from the assumption into the Technical Design; fixes a missing confidence line.
• Checkpoint: documents and state file committed as docs(user notifications): design refinement pass 1 — preference mapping, deactivated-account policy, 9 of 12 resolved.

Pass 2

• Discovery surfaces 6 new questions (the preference mapping added in pass 1 raised one about unknown codes) plus the 11 deferred, and Q9 rejoins them — its blocker cleared when the user granted the dev database access the pass 1 checkpoint listed. The top 12 are taken, Q9 among them. Ten resolve, including Q9, and two become assumptions.
• Checkpoint committed and reported.

Pass 3

• Discovery surfaces 2 new questions — below the yield stop. With the 6 carried over from pass 2, all 8 are taken: six resolve, two become assumptions. No Deferred questions remain; convergence reached.

Completion

• Final conformance clean. Final verification clean. State file deleted. Final commit. Report: 3 passes, Converged; 31 questions — 25 resolved, 6 captured as assumptions (4 awaiting validation), 0 still below threshold; ready for implementation.

Consolidation

• On top of the completion commit, one writer replaces 41 repeats in the design with pointers and removes two dated correction notes; the PRD has none. The check finds every identifier present and every removed line's content where its pointer leads. Design 14,200 → 12,900 words, committed on its own.