/refine

Refine Command

You are implementing architect:refine.

Purpose

Evolve an existing architecture instead of designing one from scratch. architect:design produces the first design; architect:refine is how that design changes over time — when a new requirement lands, when a seam's extraction trigger fires, or when a review (the design-adversary, taskmanager design-conformance, scribe:verify, or a human) finds the design no longer fits the code.

Refinement is evolutionary, never destructive. The discipline is the same as design — architecture is tradeoffs, right-sized to the present, with clean seams and explicit triggers (${CLAUDE_PLUGIN_ROOT}/skills/architecture-design/SKILL.md) — but applied to a system that already has decisions of record. The two rules that make this command refine rather than rewrite:

1. Preserve the evolution history. Prior decisions are superseded, never erased. A superseded ADR keeps its number and its body, is marked superseded, and links forward to the ADR that replaced it. Someone reading the history six months from now must be able to see what was decided, why it changed, and what replaced it. Deleting or overwriting an ADR destroys that trail and is a defect.
2. The new decision is itself a first-class decision. Every change that supersedes or adds a boundary, data-model fact, or contract gets its own ADR — accepted, with context that points at what triggered the change (the new requirement, the fired trigger, the review finding) and its own trigger-to-revisit. Evolution does not get a free pass on the discipline; the new decision earns its place exactly like the original did.

The change is then subjected to the design-adversary before it ships, per maestro's canonical adversarial-verify standard — because a change to a working design is exactly the high-risk, easy-to-rationalize move that confirmation bias misses.

Read these before acting — do not improvise the layout, the ADR shape, or the discipline:

• ${CLAUDE_PLUGIN_ROOT}/skills/architecture-design/SKILL.md — the locked discipline + method.
• ${CLAUDE_PLUGIN_ROOT}/skills/architecture-design/references/seam-catalog.md — the seam each extraction trigger maps to (cheap-now → extract-later → boundary → trigger).
• ${CLAUDE_PLUGIN_ROOT}/skills/architecture-design/references/design-heuristics.md — the irreversible-vs-reversible test, the subtraction test, the adversarial challenge set, and how to write a good trigger.
• scribe's documentation-discipline — the docs/ contract this command writes through. Read its SKILL.md, references/docs-layout.md, and templates/adr.md. The architect owns docs/architecture/ but conforms to scribe's layout and ADR template; it never invents its own.

Arguments

The argument names the driver of the refinement — why the design must change. Zero or one should be given; if none is given, ask the user which driver applies (see §1).

• --prd <path> (optional): A new or changed requirement — a new/refined PRD or PRD section (owned by prd-builder, ingested at docs/prd/). The design must now also serve this; trace to it, do not restate it.
• --trigger <seam|adr-id> (optional): A fired extraction trigger — a seam's documented trigger has been observed (a measured latency, a row count, a team split, a compliance event), so the planned extraction is now due. Names the seam (e.g. jobs, database, billing-module) or the ADR whose trigger-to-revisit fired (e.g. 0007).
• --review <findings-path> (optional): Review findings — a path to design-adversary output, a taskmanager design-conformance failure, a scribe:verify drift/conflict report, or a human review that says the design no longer fits. The design must be corrected to resolve them.
• --votes N (optional): Number of independent design-adversary passes to run on the change (§5). Default 3. Minimum 2 — a single pass is not "maximal" and is rejected.

Behavior

0. Read docs/ first — load the design being evolved

Per the read-first rule, you do not refine from memory or from the prompt alone. Confirm the SSOT exists and load the current design as the baseline you are evolving:

test -d docs/architecture || echo "NO_ARCHITECTURE"
test -f docs/STATUS.md     || echo "NO_STATUS"
ls docs/adr/ 2>/dev/null

• If docs/architecture/ does not exist, there is no design to refine: tell the user to run architect:design first (and, if docs/ itself is missing, scribe:init before that), and stop. Refinement evolves an existing design; it does not bootstrap one.
• Read the current docs/STATUS.md, the whole docs/architecture/ set (README.md, boundaries.md, data-model.md, interfaces.md), and the open (accepted) ADRs that constrain the area being changed. These are the decisions of record you are about to evolve.
• For brownfield, also read the reverse-engineered baseline scribe bootstrapped and the relevant code the architecture cites (path:line/symbols), so you evolve within and against the real system, not the doc's idealized version of it.

1. Identify and frame the driver

Resolve why the design is changing, most specific first:

1. If --prd, --trigger, or --review was given, use it.
2. Otherwise, ask the user with AskUserQuestion which driver applies — new requirement, a fired extraction trigger, or review findings — and gather the specifics (the PRD path, which seam/ADR trigger fired and the evidence it fired, or the findings to resolve).

Then frame the change precisely as a focused intake (not a full re-elicitation — the original context already lives in the existing ADRs):

• New requirement (--prd): What does the new requirement ask of the architecture that the present design does not serve? Re-elicit only the context that changed (new scale, new risk/compliance, new constraint — design-heuristics.md §A); the rest stands.
• Fired trigger (--trigger): Find the seam in docs/architecture/boundaries.md and the ADR whose trigger-to-revisit names it. Confirm with evidence that the trigger actually fired (the measured signal, not a hunch — a trigger is falsifiable in both directions; if it has not fired, say so and stop, because extracting before the trigger is the over-engineering the seam exists to prevent). The boundary was defined for exactly this moment, so the extraction should be a swap following the seam-catalog entry — the refinement realizes the planned move.
• Review findings (--review): Enumerate each finding as an atomic claim about how the design fails to fit (a leaking boundary, a scale break, an irreversible mistake, an over-engineered component, or a doc-vs-code conflict). Each finding is a thing the refinement must resolve or consciously reject with reasoning.

Capture the driver as a breadcrumb the curator will consolidate:

mkdir -p docs/.scribe
echo "$(date -Iseconds) | decision | architect:refine — evolving design: <driver + one line>" >> docs/.scribe/capture.log

2. Scope the change — what must move, what must NOT

Determine the blast radius of the change within the design, and hold the line on scope (design-heuristics.md — subtraction discipline applies to changes too):

• Which boundaries / data-model facts / contracts must change to serve the driver? List them as the concrete deltas — each delta is a candidate ADR.
• For each delta, re-apply the irreversible-vs-reversible test (design-heuristics.md §B): a one-way door (data migration, a public contract, an ownership line) gets a deliberate ADR now; a two-way door behind an existing interface is noted reversible and deferred to the last responsible moment — do not bake it in just because you have the file open.
• Re-apply the subtraction test (design-heuristics.md §D) to anything the change adds: every new component, layer, or abstraction must EARN its place via the new present requirement or an irreversible-seam need. A trigger firing justifies its own extraction — not a pile of speculative scale-out you reach for while you are in there.
• Explicitly name what stays put: existing boundaries and decisions the change does not touch keep their ADRs untouched. Minimizing the diff to the design is itself the discipline.

3. Design the evolution

Produce the evolved design for the in-scope deltas only, using the method (SKILL.md §2, steps 4–6) applied to the existing system:

• Decide the new irreversibles deliberately (the new/changed data model, ownership lines, contracts) — one ADR per significant decision.
• For a fired trigger, realize the seam-catalog extraction: replace the cheap-now form with the extract-later form behind the boundary that already exists, so call sites do not change. If the boundary turns out to leak (a call site reached past it), that leak is a finding — fix the boundary as part of the extraction and record it.
• Place any new seams the change introduces, each with its own explicit extraction trigger (design-heuristics.md §F) — but build only the cheap-now form. Evolving the design does not license building the next extraction speculatively.
• Keep the design traced to the PRD (docs/prd/) — link, never restate.

4. Stage the doc updates — supersede, don't erase

Prepare (but in §5 do not yet finalize) the docs/ changes per scribe's obligation contract. Compute the next free NNNN for docs/adr/ first:

ls docs/adr/ 2>/dev/null | grep -oE '^[0-9]{4}' | sort -n | tail -1

• docs/architecture/ — update boundaries.md, data-model.md, interfaces.md, and the README.md index to describe the design as it now is. For a realized extraction, move the seam's row from cheap-now to its extracted form and update/clear its trigger. Architecture files are system facts — they must match the code (drift = defect), so anchor changed claims to the code (path:line/symbol) and keep them lean (tables over prose).
• Supersede the old ADR(s): for each decision the change replaces, edit the existing ADR to Status: superseded, add superseded by [ADR NNNN](./NNNN-title.md) on YYYY-MM-DD, and leave its body intact. Never delete it, never reuse its number. This is the evolution history.
• Add the new ADR(s): one docs/adr/NNNN-*.md per significant new decision, using scribe's templates/adr.md exactly — Status: accepted, an absolute date, an owner, the Context naming the driver (link the PRD / the fired trigger / the review finding) and, when superseding, linking back to the old ADR; Options considered; the Decision; Consequences; and its own Trigger to revisit (for a realized extraction, the next threshold; for a new seam, its extraction trigger). A change that adds a contract/boundary with no superseded predecessor is still a new accepted ADR.
• Obligation contract knock-on (docs/STATUS.md is scribe's domain — flag, don't rewrite it here): a change that ships behavior touches STATUS.md; a now-planned-but-not-yet-built extraction goes to roadmap.md with its trigger; a deferred-but-undecided question goes to open-questions.md with an owner. Note these so the curator (scribe:sync) reconciles them.

Do not finalize these writes until the design-adversary (§5) has run — you challenge the change before it ships, then write only what survives.

5. Re-run the design-adversary ON THE CHANGE (maximal, multi-vote)

This is the gate. Dispatch the design-adversary agent via the Task tool (subagent_type: design-adversary) --votes N independent times (default 3, floor 2), in parallel, each told to refute the change, not affirm it — assume each claim about the evolution is likely wrong and go find the evidence (real PRD, real baseline code, the elicited context — never "should be"). This embodies maestro's adversarial-verify standard (maestro/skills/adversarial-verify/SKILL.md): refute-first, fresh independent eyes, evidence over assertion, atomic claims, multi-vote always.

Aim each pass through the four core lenses (design-heuristics.md §E), focused on the delta:

1. Where does the changed boundary leak? Did the supersede actually move the seam, or do call sites still reach past it so the "swap" isn't a swap? Did the new contract leave an old one half-honored?
2. At what scale does the new design break? Does the change introduce a new first-thing-to- fall-over under the elicited plausible future — or, for a realized extraction, did it stop at the right place rather than over-scaling?
3. What irreversible mistake is the change baking in? A new data-model or ownership line, a contract change with dependents — is it backed by its own deliberate accepted ADR, or slipped in casually?
4. What did the change over-engineer? Run the subtraction test adversarially on everything the change adds: name any new component that earns neither the new requirement nor an irreversible seam, and demand it be cut.

Also have the adversary check the history integrity specific to refinement: is every replaced ADR actually marked superseded and linked (not deleted, not overwritten)? Does each new ADR have its own trigger-to-revisit? Does docs/architecture/ now match the code the change targets?

Converge (adversarial-verify §4): overturned claims are dropped, not patched. If most of the change is overturned, the frame is wrong — re-elicit (§1) and redesign (§3) rather than defend it delta by delta. Deliver only what survives.

6. Write the surviving change into docs/

Apply the §4 doc updates for only the deltas that survived §5:

• Write/update docs/architecture/ (boundaries.md, data-model.md, interfaces.md, README.md) to the evolved, adversary-survived design — anchored, lean, with every seam's trigger current.
• Mark each superseded ADR superseded + linked (body intact); write each new accepted ADR from scribe's template with its own trigger-to-revisit.
• Note the obligation knock-on for the curator: STATUS.md if behavior shipped, roadmap.md for a planned extraction, open-questions.md for a deferral. Append a closing breadcrumb:

echo "$(date -Iseconds) | decision | architect:refine — applied: ADR <new NNNN> supersedes <old NNNN>; architecture/<files> updated" >> docs/.scribe/capture.log

Recommend the user run scribe:sync so the doc-curator consolidates the knock-on docs and the doc-verifier confirms the evolved architecture matches the code (the read-after-write half of the contract). architect:refine writes docs/architecture/ + ADRs directly; it does not rewrite STATUS.md/roadmap.md/open-questions.md itself — those are scribe's to curate.

7. Report the evolution

End with a concise, honest report:

1. Driver — what triggered the refinement (new requirement / fired trigger + its evidence / review findings), in one line.
2. Decisions evolved — the table of superseded → replaced by, and any net-new ADRs, each a one-liner with its trigger-to-revisit.
3. Architecture changed — which docs/architecture/ files changed and the delta (e.g. "jobs seam realized: in-process → worker queue behind the existing JobQueue.dispatch boundary").
4. Adversary result — votes run, what was overturned and dropped, what survived. Never report a clean pass that didn't happen.
5. History preserved — confirm explicitly that no prior ADR was deleted or overwritten; each replaced decision is superseded and linked.
6. Owed next — the STATUS.md/roadmap.md/open-questions.md knock-on for scribe:sync, and any conflict that must go to a human (see Error Handling).

Error Handling

• No docs/architecture/ — nothing to refine; direct the user to architect:design (and scribe:init if docs/ itself is missing) and stop. Do not bootstrap a design here.
• Trigger has not actually fired — if a --trigger extraction's evidence shows the documented threshold is not met, do not extract: say so and stop. Extracting before the trigger is the over-engineering the seam exists to prevent.
• Driver unclear — if no driver is given and the user cannot specify one via AskUserQuestion, stop: a refinement with no reason is scope creep, not evolution.
• ADR-vs-code conflict in a review finding — a --review finding where an accepted ADR contradicts the code is flagged for human resolution (per documentation-discipline §3): the code may have regressed or the decision may be stale. The architect does not auto-resolve it by superseding the ADR to match drifted code — surface both sides and let a human decide; only then refine.
• Most of the change overturned by the adversary — the frame is wrong. Do not patch delta by delta; re-elicit (§1) and redesign (§3), or report that the driver needs rethinking.
• Brownfield drift — if the existing docs/architecture/ already disagrees with the code before you change anything, that drift is a defect; note it (recommend scribe:verify) and refine against the code as the referent, not the stale doc.

Usage Examples

# A new requirement landed — evolve the design to serve it
architect:refine --prd docs/prd/0003-multi-region.md

# A seam's extraction trigger fired — realize the planned extraction (the swap)
architect:refine --trigger jobs

# An ADR's trigger-to-revisit fired — revisit that decision
architect:refine --trigger 0007

# Review findings say the design no longer fits — resolve them
architect:refine --review docs/deep-analysis/2026-06-16/findings.md

# Refine with extra adversarial passes on a high-stakes change
architect:refine --trigger database --votes 5

Related Commands & Components

• architect:design — produces the first design; architect:refine evolves it. Both run the architecture-design discipline and write docs/architecture/ + docs/adr/.
• architect:review — adversarially re-checks an existing design and produces the findings that architect:refine --review consumes.
• design-adversary (agents/design-adversary.md) — the independent refute-first agent dispatched in §5; embodies maestro's adversarial-verify standard.
• architecture-design skill — the locked discipline, the method, the seam catalog, and the design heuristics this command applies to a change.
• scribe:sync / scribe:verify — consolidate the obligation knock-on (STATUS.md, roadmap, open-questions) and adversarially confirm the evolved docs/architecture/ matches the code.
• prd-builder owns docs/prd/ — the --prd driver's input; trace to it, never restate it.
• taskmanager decomposes and verifies against the evolved docs/architecture/ + ADRs, so a refinement re-specifies the downstream design-conformance gate.
• maestro is the untouched canonical home of adversarial-verify; the §5 design-adversary pass references and embodies it.

The mantra

Refine, don't rewrite: evolve the design to the new reality, supersede old decisions instead of erasing them, give the new decision its own ADR and its own trigger, and let the design-adversary refute the change before it ships — so the architecture grows with a history, not a fresh start.