Design

Design

You are translating scoped intent into implementable design.

Inputs:

• existing slice folder
• existing design.md or equivalent design artifact
• relevant related artifacts, source material, research, etc.

Workflow State Machine

Complete in order without deviation. Each depends on the preceding stage:

1. Explore context — specs, ADRs, memories, files, docs, recent commits. Begin high-level. 2. Ask clarifying questions — one at a time, understand purpose/guiding principles/constraints/success criteria 3. Propose 2-3 approaches — identify the next unanswered design question; propose options with trade-offs and your recommendation 4. Present design — in sections scaled to their complexity, get user approval after each section. 5. Write design.md — save to the slice design.md file and commit 6. Adversarial Review — perform a hostile review of the design doc, probing for imprecision and flawed reasoning 7. Integrate Review Feedback — triage and respond to feedback; integrate into slice / design doc; repeat until the design locks (explicit user approval) 8. Transition to planning — record the lifecycle move (doctrine slice status <id> plan — bare number), then invoke /plan to create the implementation plan

<Process State Machine> <state name="Explore context"> <transition to="Ask clarifying questions" /> </state> <state name="Ask clarifying questions"> <transition to="Propose 2-3 approaches" /> </state> <state name="Propose 2-3 approaches"> <transition to="Present design" /> <transition to="Ask clarifying questions" /> </state> <state name="Present design"> <transition to="Write design doc" /> </state> <state name="Write design doc"> <transition to="Adversarial review" /> </state> <state name="Adversarial review"> <transition to="Ask clarifying questions" /> <transition to="Propose 2-3 approaches" /> <transition to="Present design" /> <transition to="Write design doc" /> <transition to="Transition to planning" /> </state> <state name="Transition to planning"> <transition to="invoke /plan skill" /> </state> </Process State Machine>

Process (detail)

Explore context

1. Read the slice scope + relevant specs, ADRs, prior art first. 2. Run /canon before drafting so relevant ADRs, policies, and standards are in view for this design surface. 3. Run /retrieve-memory against the files and subsystems you expect to touch, so scope-bound gotchas surface early. 4. Before drafting sections, explicitly generate a list of concerns and then triage the design surface:

• open questions that must be resolved
• risks and underspecified areas
• assumptions you are carrying
• critical design decisions that shape the rest of the design
• relevant ADRs, policies, and standards that constrain the design

Ask clarifying questions

Proceed in a light loop to clarify intent, surface known and unknown unknowns, and drive towards sufficient clarity to lock a design.

Apply this process first to the slice scope itself if necessary, then to the technical design.

At each step:

1. Summarize:

• what's already understood
• carrying assumptions
• open questions, risks, concerns, dependencies

2. Work through unresolved design questions one at a time. Ask questions one at a time, choosing the most impactful or most naturally related:

• consider it carefully (implications, related questions)
• lightly explore related context if necessary, but keep it bounded
• suggest 2-3 options, with tradeoffs
• recommend one, with rationale

Operating principles:

• Prefer multiple choice questions when possible, but open-ended is fine too
• Only one question per message - if a topic needs more exploration, break it

into multiple questions

• Focus on understanding: purpose, constraints, success criteria, verification

strategy

Continue in this manner until you have sufficient clarity to begin the design proper, and the user has accepted your summary.

Once accepted, ensure the slice scope (slice-nnn.md) is consistent with and reflects your current shared understanding before proceeding.

Present design

1. Draft or revise the design section by section, interactively, rather than dumping a full design at once:

• Current behavior vs target behavior
• Code impact summary (paths + intended changes)
• Verification alignment (what evidence must change/add)
• Design decisions and remaining open questions

2. When a section shapes later sections, present that section first and treat later sections as provisional until the foundation is coherent. 3. Prefer concrete design detail over hand-wavey prose:

• Current behavior vs target behavior
• module responsibility boundaries
• imports, coupling, cohesion analysis
• structs/types/interfaces/function signatures
• data structures & algorithms
• example data shapes
• data flow boundaries
• verification impact
• invariants & boundary conditions
• samples of critical code, protocols
• titles / descriptions of key test cases
• text c4 diagrams
• Code impact summary (paths + intended changes)
• Verification alignment (what evidence must change/add)
• Impact on design decisions and remaining open questions

4. Perform targeted research if required to ensure fit to implementation surface

Adversarial review

1. Once the design feels coherent, perform an adversarial self-review before treating it as done:

• attack vague sections, hidden assumptions, weak verification, missing

code-impact detail, and places where a short sample would remove ambiguity

• attack missing, misread, or weakly applied ADR/policy/standard constraints
• ensure doctrinal alignment
• record the findings in the design doc or companion slice notes as needed

2. Review for doctrinal alignment.

• If the doctrine pass exposes governance conflicts, missing authorities, or

ambiguous constraints, stop and /consult rather than normalizing around guesswork. 3. Integrate the feedback before offering next steps.

• Occasionally this might require revisiting earlier steps.

4. After integrating design feedback, reconcile the owning slice — slice-nnn.md so scope, risks, acceptance criteria, open questions, and follow-up direction still match the revised design, and slice-nnn.toml (relations, metadata); relations move via doctrine link and lifecycle status via doctrine slice status — not hand-edits (using-doctrine.md § Relating entities). 5. After the internal adversarial pass is integrated, you MUST offer the user a choice: 1. run a formal hostile pass via /inquisition, or print a prompt for an external adversarial reviewer. 2. initiate /plan to create the implementation plan and runtime phase sheets. 6. Multiple passes of review & feedback may be required before acceptance. Do not presume approval until it is explicitly granted.

If meaningful tradeoffs or uncertainty remain unresolved, stop and /consult.

Guardrails

The design doc is canon for design intent.

• If design and plan conflict, reconcile via the design first.
• Do not present "the whole design" as settled before the foundational sections and decisions have been validated.
• Do not hide unresolved assumptions inside polished prose; name them explicitly.
• Do not confuse detailed design with implementation planning.
• Do not treat a polished full-file rewrite as progress if the hard design questions

are still unresolved.

• Do not move on to planning while the slice scope still tells an older story than the design.
• Do not treat governance as optional background reading when the design makes architectural or workflow choices.

Outcomes

• The design gives a clear, defensible target for implementation.
• Foundational questions are closed or made explicit before downstream planning.
• The design evolves through short feedback loops instead of one large speculative draft.
• Verification impact is explicit before coding starts.
• The author gets an internal adversarial pass and an optional external challenge

prompt before planning starts.

• Slice scope and design stay aligned before plan/phase work begins.
• Relevant ADRs, policies, and standards shape both the draft and the critical review.

Design (compact variant)

Experimental compressed port of the design skill. Not the active skill —

SKILL.md is. Kept for comparison / later A/B.

You are translating scoped intent into an implementable design, recorded in the slice's design.md. design.md is canon for design intent: if it and a later plan conflict, reconcile via design.md first.

Inputs: the slice folder, any existing design.md, and related artifacts, source material, and research.

Workflow

Complete in order; each stage depends on the one before it.

1. Explore context. Read the slice scope, related .doctrine/spec/tech/ specs, prior art, and recent commits. Run /canon so the governing ADRs, policies, and standards are in view. /retrieve-memory for gotchas on the surface. Then triage the design surface out loud: open questions that must resolve, risks and underspecified areas, assumptions you carry, the decisions that shape everything downstream, and the constraints that bound them.

2. Ask clarifying questions — one at a time. Drive toward enough clarity to lock a design. For each unresolved question, pick the most impactful or naturally next one, consider its implications, then offer 2-3 options with tradeoffs and a recommendation. Prefer multiple-choice; open-ended is fine. Focus on purpose, constraints, success criteria, verification strategy. Continue until the user accepts your summary. Then ensure the slice scope (slice-nnn.md) still reflects the shared understanding before proceeding.

3. Present the design section by section — never dump the whole thing at once. Get approval per section. When a section shapes later ones, present it first and treat the rest as provisional until the foundation is coherent. Prefer concrete detail over hand-wavy prose:

• current vs target behaviour
• module responsibility boundaries; coupling / cohesion analysis
• types / interfaces / function signatures; data structures & algorithms
• example data shapes; data-flow boundaries; invariants & edge conditions
• code-impact summary (paths + intended changes)
• verification alignment — what evidence must change or be added
• design decisions and remaining open questions

Do targeted research where needed to keep the design fitted to the real implementation surface.

4. Write `design.md` and commit.

5. Adversarial review. Run /inquisition against the design — a hostile pass for vague sections, hidden assumptions, weak verification, missing code-impact detail, and misread or weakly-applied governance. Integrate the findings (this may send you back to step 2 or 3). If the pass exposes governance conflicts or ambiguous authority, stop and /consult rather than guessing. Reconcile slice-nnn.md so scope, risks, and open questions still match the revised design.

6. Offer next steps. After integrating the internal pass, offer the user a choice: (a) a prompt for an external adversarial reviewer, or (b) proceed to /plan. Do not presume approval — multiple review rounds may be needed.

Guardrails

• Do not present "the whole design" as settled before the foundational sections

and decisions are validated.

• Do not hide unresolved assumptions inside polished prose — name them.
• Do not confuse detailed design with implementation planning.
• Do not treat a polished full-file rewrite as progress while hard questions

remain open.

• Do not move to /plan while slice-nnn.md tells an older story than the design.
• Do not treat governance as optional background when the design makes

architectural or workflow choices.