Design

Design

You are tasked with designing how code will be shaped for a feature or change. This iterative variant decomposes features into vertical slices and generates code slice-by-slice with developer micro-checkpoints between slices. The design artifact feeds directly into plan, which sequences it into phases.

Input

$ARGUMENTS takes two forms:

1. Start — path to a research artifact (.rpiv/artifacts/research/*.md) or a solutions artifact (.rpiv/artifacts/solutions/*.md).
2. Resume — --resume <path-to-.rpiv/artifacts/designs/*.md>. The design must have status: in-progress; the artifact, not a compaction summary, is authoritative for locked slices and the next pending slice.

Metadata

node "${SKILL_DIR}/../_shared/now.mjs"
echo
node "${SKILL_DIR}/../_shared/git-context.mjs"
echo
echo "### recent (read only in case of empty user input)"
echo "recent research:"
node "${SKILL_DIR}/../_shared/list-recent.mjs" .rpiv/artifacts/research 4
echo
echo "recent solutions:"
node "${SKILL_DIR}/../_shared/list-recent.mjs" .rpiv/artifacts/solutions 4

Copy values verbatim — do not reformat the timezone offset.

Flow

1. Input → 2. Research → 3. Dimension sweep → 4. Checkpoint → 5. Decompose → 6. Generate slices (code + Success Criteria) → 7. Finalize → 8. Present artifact → 9. Handle follow-ups

The final artifact is plan-compatible: ## Slices boundaries become phase boundaries 1:1, and Success Criteria pass through unchanged. Post-finalization code + coverage review runs inside /skill:plan Step 4.

Steps

Step 1: Input Handling

When this command is invoked:

1. Resume mode first — when $ARGUMENTS contains --resume:

   • Parse exactly one design artifact path after the flag. If it is missing, outside .rpiv/artifacts/designs/, unreadable, or not status: in-progress, print the specific error and stop.
   • Read the design artifact FULLY. Extract Decisions, Architecture, Slices, Verification Notes, Developer Context, and Design History.
   • Find the first Design History entry still marked pending. Treat every earlier approved entry and its persisted code fences/Success Criteria as locked; never reconstruct them from conversation or a compaction summary.
   • Read the current source files for that pending slice FULLY, plus Architecture entries for files the slice shares with locked predecessors.
   • Skip Steps 2–5. Enter Step 6 at the pending slice. If no slice is pending, go directly to Step 7.

2. Read research artifact:

   Research artifact provided (argument contains a path to a .md file in .rpiv/artifacts/):

   • Read the research artifact FULLY using the Read tool WITHOUT limit/offset
   • Extract: Summary, Code References, Integration Points, Architecture Insights, Precedents & Lessons, Developer Context, Open Questions
   • Read the key source files from Code References into the main context — especially hooks, shared utilities, and integration points the design will depend on. Read them FULLY. This ensures you have complete understanding before proceeding.
   • These become starting context — no need to re-discover what exists
   • Research Developer Context Q/As = inherited decisions (record in Decisions, never re-ask); Open Questions = starting ambiguity queue, filtered by dimension in Step 3

   No arguments provided, branch on the recent research: and recent solutions: listings in the Metadata block:

   • Both empty — no upstream artifacts available; tell the user and suggest running /skill:research (or /skill:explore for option comparison) first.
   • Exactly one entry total — confirm with ask_user_question: "Design from this artifact?" with options "Design from [<source>] <filename> (Recommended)" and "Pick a different path".
   • Two or more entries total — present up to 4 most-recent across both listings as ask_user_question options, each prefixed [research] or [solutions] to flag source class.

3. Read any additional files mentioned — tickets, related designs, existing implementations. Read them FULLY before proceeding.

Step 2: Targeted Research

This is NOT a discovery sweep. Focus on DEPTH (how things work, what patterns to follow) not BREADTH (where things are).

1. Spawn parallel research agents using the Agent tool — all in a single assistant message with multiple Agent calls (concurrent, synchronous). Never run_in_background: its completion can't re-drive a workflow session, so the skill ends its turn before writing the design and the stage fails with no artifact.

   • Use codebase-pattern-finder to find existing implementations to model after — the primary template for code shape
   • Use codebase-analyzer to understand HOW integration points work in detail
   • Use integration-scanner to map the wiring surface — inbound refs, outbound deps, config/DI/event registration
   • Use precedent-locator to find similar past changes in git history — what commits introduced comparable features, what broke, and what lessons apply to this design. Only when commit is available (not no-commit); otherwise skip and note "git history unavailable" in Verification Notes.

   Novel work (new libraries, first-time patterns, no existing codebase precedent):

   • Add web-search-researcher for external documentation, API references, and community patterns
   • Instruct it to return LINKS with findings — include those links in the final design artifact

   Agent prompts should focus on (labeled by target agent):

   • codebase-pattern-finder: "Find the implementation pattern I should model after for {feature type}"
   • codebase-analyzer: "How does {integration point} work in detail"
   • integration-scanner: "What connects to {component} — inbound refs, outbound deps, config"

   NOT: "Find all files related to X" — that's discovery's job, upstream of this skill.

2. Read all key files identified by agents into the main context — especially the pattern templates you'll model after.

3. Wait for ALL agents to complete before proceeding.

4. Analyze and verify understanding:

   • Cross-reference research findings with actual code read in Step 1
   • Identify any discrepancies or misunderstandings
   • Note assumptions that need verification
   • Determine true scope based on codebase reality

Step 3: Identify Ambiguities — Dimension Sweep

Walk Step 2 findings, inherited research Q/As, and carried Open Questions through six architectural dimensions that map 1:1 to the downstream phased plan's section coverage — the sweep guarantees downstream completeness. Add migration as a seventh dimension only if the feature changes persisted schema.

• Data model — types, schemas, entities
• API surface — signatures, exports, routes
• Integration wiring — mount points, DI, events, config
• Scope — in / explicitly deferred
• Verification — tests, assertions, risk-bearing behaviors
• Performance — load paths, caching, N+1 risks

For each dimension, classify findings into three classes:

• simple — one valid option, obvious from codebase, no directional weight. Record in Decisions with file:line evidence; do not ask.
• directional — obvious fit, but the choice encodes a direction: propagates an existing pattern across new files, picks extend-vs-replace, or spreads a convention the project may be moving off. Queue for the directional confirm (Step 4, one batched ask).
• genuine ambiguity — multiple valid options, conflicting patterns, scope questions, novel choices. Queue for Step 4, one-at-a-time.

Inherited research Q/As land as simple unless directional; Open Questions filter by dimension — architectural survives, implementation-detail defers.

Pre-validate every option before queuing it against research constraints and runtime code behavior. Eliminate or caveat options that contradict Steps 1-2 evidence. Coverage check: every Step 2 file read appears in at least one decision, directional confirm, or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not).

Step 4: Developer Checkpoint

Use the grounded-questions-one-at-a-time pattern. Use a ❓ Question: prefix so the developer knows their input is needed. Each question must:

• Reference real findings with file:line evidence
• Present concrete options (not abstract choices)
• Pull a DECISION from the developer, not confirm what you already found
• Keep Header ≤16 characters (MAX_HEADER_LENGTH = 16 — longer values are rejected).

Directional confirms first. Before the one-at-a-time questions, clear every directional finding from Step 3 in a single batched ask_user_question (up to 4 per call). Do not mark the "follow" option Recommended.

Question: "About to follow {pattern X} (file:line, used ×N) across {the N new files} — confirm that's the direction, or moving off it?". Header: "Direction". Options: "Follow {X}" (propagate as-is); "Moving off {X}" (deliberate departure).

Follow records the decision as stated. Moving off promotes the finding to a genuine ambiguity — ask it one-at-a-time below with the alternative in view.

Question patterns by ambiguity type:

• Pattern conflict: "Found 2 patterns for {X}: {pattern A} at file:line and {pattern B} at file:line. They differ in {specific way}. Which should the new {feature} follow?"
• Missing pattern: "No existing {pattern type} in the codebase. Options: (A) {approach} modeled after {external reference}, (B) {approach} extending {existing code at file:line}. Which fits the project's direction?"
• Scope boundary: "The {research/description} mentions both {feature A} and {feature B}. Should this design cover both, or just {feature A} with {feature B} deferred?"
• Integration choice: "{Feature} can wire into {point A} at file:line or {point B} at file:line. {Point A} matches the {existing pattern} pattern. Agree, or prefer {point B}?"
• Novel approach: "No existing {X} in the project. Options: (A) {library/pattern} — {evidence/rationale}, (B) {library/pattern} — {evidence/rationale}. Which fits?"

Critical rules:

• Ask ONE question at a time. Wait for the answer before asking the next.

• Lead with the most architecturally significant ambiguity.

• Every answer becomes a FIXED decision — no revisiting unless the developer explicitly asks.

• Every ambiguity checkpoint MUST be self-contained: state observed behavior, at least one file:line evidence reference, why the decision matters, and 2-4 concrete decision options in the question or option descriptions.

Choosing question format:

• ask_user_question tool — concrete options include evidence and trade-offs in every description. The user can type a custom answer through the automatically appended Type something. row; do not author Other. Example:

  Use the ask_user_question tool with the following question: "Found 2 mapping approaches — which should new code follow?". Header: "Pattern". Options: "Manual mapping (Recommended)" (Used in OrderService (src/services/OrderService.ts:45) — 8 occurrences); "AutoMapper" (Used in UserService (src/services/UserService.ts:12) — 2 occurrences).

• Open-ended — still use ask_user_question; supply 2-4 concrete hypotheses with behavior, file:line evidence, impact, and decision context, then let the automatic Type something. row capture unanticipated detail.

Batching: When you have 2-4 independent questions (answers don't depend on each other), you MAY batch them in a single ask_user_question call. Keep dependent questions sequential.

Classify each response:

Decision (e.g., "use pattern A", "yes, follow that approach"):

• Record in Developer Context. Fix in Decisions section.

Correction (e.g., "no, there's a third option you missed", "check the events module"):

• Spawn targeted rescan: codebase-analyzer on the new area (max 1-2 agents).
• Merge results. Update ambiguity assessment.

Scope adjustment (e.g., "skip the UI, backend only", "include tests"):

• Record in Developer Context. Adjust scope.

After all ambiguities are resolved, present a brief design summary (under 15 lines):

Design: {feature name}
Approach: {1-2 sentence summary of chosen architecture}

Decisions:
- {Decision 1}: {choice} — modeled after `file:line`
- {Decision 2}: {choice}
- {Decision 3}: {choice}

Scope: {what's in} | Not building: {what's out}
Files: {N} new, {M} modified

Use the ask_user_question tool to confirm before proceeding. Question: "{Summary from design brief above}. Ready to proceed to decomposition?". Header: "Design". Options: "Proceed (Recommended)" (Decompose into vertical slices, then generate code slice-by-slice); "Adjust decisions" (Revisit one or more architectural decisions above); "Change scope" (Add or remove items from the building/not-building lists).

Step 5: Feature Decomposition

After the design summary is confirmed, decompose the feature into vertical slices. Each slice is a self-contained unit: types + implementation + wiring for one concern.

1. Decompose holistically — define ALL slices, dependencies, and ordering before generating any code:

   Feature Breakdown: {feature name}
   
   Slice 1: {name} — {what this slice delivers}
     Files: path/to/file.ext (NEW), path/to/file.ext (MODIFY)
     Depends on: nothing (foundation)
   
   Slice 2: {name} — {what this slice delivers}
     Files: path/to/file.ext (NEW), path/to/file.ext (MODIFY)
     Depends on: Slice 1
   
   Slice 3: {name} — {what this slice delivers}
     Files: path/to/file.ext (NEW)
     Depends on: Slice 2
   

2. Slice properties:

   • End-to-end vertical: each slice is a complete cross-section of one concern (types + impl + wiring)
   • ~512-1024 tokens per slice (maps to individual file blocks)
   • Sequential: each builds on the previous (never parallel)
   • Foundation first: types/interfaces always Slice 1

3. Confirm decomposition using the ask_user_question tool. Question: "{N} slices for {feature}. Slice 1: {name} (foundation). Slices 2-N: {brief}. Approve decomposition?". Header: "Slices". Options: "Approve (Recommended)" (Proceed to slice-by-slice code generation); "Adjust slices" (Reorder, merge, or split slices before generating); "Change scope" (Add or remove files from the decomposition).

4. Create skeleton artifact — immediately after decomposition is approved:

   • Determine metadata from the Metadata block above: filename .rpiv/artifacts/designs/<slug>_<topic>.md (use <slug> from line 1 of the Metadata block above); repository: from repo:; branch: / commit: from matching labels; author: ← matching label (fallback: unknown).
   • Timestamp: use <iso> from line 1 of the Metadata block above for date: and last_updated: (copy the offset verbatim).
   • Write skeleton using the Write tool with status: in-progress in frontmatter
   • Include all prose sections filled from Steps 1-5: Summary, Requirements, Current State Analysis, Scope, Decisions, Desired End State, File Map, Ordering Constraints, Verification Notes, Performance Considerations, Migration Notes, Pattern References, Developer Context, References
   • Architecture section: one ### path/to/file.ext — NEW/MODIFY heading per file from the decomposition, with empty code fences as placeholders
   • Design History section: list all slices with — pending status
   • This is the living artifact — all subsequent writes use the Edit tool

   Artifact template sections (all required in skeleton):

   • Frontmatter: date, author, commit, branch, repository, topic, tags, status: in-progress, parent, last_updated, last_updated_by
   • # Design: {Feature Name}
   • ## Summary: 2-3 sentences — what we're building and the chosen architectural approach. Settled decision, not a discussion.
   • ## Requirements: Bullet list from ticket, research, or developer input.
   • ## Current State Analysis: What exists now, what's missing, key constraints. Include ### Key Discoveries with file:line references, patterns to follow, constraints to work within.
   • ## Scope: ### Building — concrete deliverables. ### Not Building — developer-stated exclusions AND likely scope-creep vectors (alternative architectures not chosen, nearby code that looks related but shouldn't be touched).
   • ## Decisions: ### per decision. Complex: Ambiguity → Explored (Option A/B with file:line + pro/con) → Decision. Simple: just state decision with evidence.
   • ## Architecture: ### per file with NEW/MODIFY label. Empty code fences in skeleton (filled in Step 6.4). NEW files get full implementation. MODIFY files get only modified/added code — no "Current" block.
   • ## Slices: ### Slice N: {name} per slice from the decomposition. In skeleton, each subsection contains a **Files**: line listing the slice's file paths AND empty #### Automated Verification: / #### Manual Verification: subsections (filled in Step 6.4 from 6.1's Success Criteria). This section is the contract handed to /skill:plan: slice ≡ phase 1:1, criteria pass through unchanged.
   • ## Desired End State: Usage examples showing the feature in use from a consumer's perspective — concrete code, not prose.
   • ## File Map: path/to/file.ext # NEW/MODIFY — purpose per line.
   • ## Ordering Constraints: What must come before what. What can run in parallel.
   • ## Verification Notes: Carry forward from research — known risks, build/test warnings, precedent lessons. Format as verifiable checks (commands, grep patterns, visual inspection). plan converts these to success criteria.
   • ## Performance Considerations: Any performance implications or optimizations.
   • ## Migration Notes: If applicable — existing data, schema changes, rollback strategy, backwards compatibility. Empty if not applicable.
   • ## Pattern References: path/to/similar.ext:line-range — what pattern to follow and why.
   • ## Developer Context: Record questions exactly as asked during checkpoint, including file:line evidence. For iterative variant: also record micro-checkpoint interactions from Step 6.3.
   • ## Design History: Slice approval/revision log. - Slice N: {name} — pending/approved as generated/revised: {what changed}. plan ignores this section.
   • ## References: Research artifacts, tickets, similar implementations.

   Architecture format in skeleton:

   • NEW files: heading + empty code fence (filled with full implementation in Step 6.4)
   • MODIFY files: heading with file:line-range + empty code fence (filled with only the modified code in Step 6.4 — no "Current" block, the original is on disk)

Step 6: Generate Slices (Iterative)

Generate code one slice at a time. Each slice sees the fixed code from all previous slices.

For each slice in the decomposition (sequential order):

6.1. Generate slice code and Success Criteria (internal)

Generate complete, copy-pasteable code AND the slice's ### Success Criteria: for every file in this slice — but hold both for the artifact, do NOT present full code to the developer. The developer sees a condensed review in 6.3; the full code and criteria go into the artifact in 6.4.

• New files: complete code — imports, types, implementation, exports. Follow the pattern template from Step 2.
• Modified files: read current file FULLY, generate only the modified/added code scoped to changed sections (no full "Current" block — the original is on disk)
• Test files: complete test suites following project patterns
• Wiring: show where new code hooks into existing code
• Success Criteria: derive ### Success Criteria: from this slice's file changes plus ## Verification Notes entries that map to this slice's scope. Use the same - [ ] format as 6.4 (see template below). Project-baseline checks (the project's whole-repo build/test commands, from its guidance # Commands table) go on the terminal slice only. Commands in backticks. Criteria authored here flow through to plan as the phase's Success Criteria — slice ≡ phase, 1:1.

If additional context is needed, spawn a targeted codebase-analyzer agent.

No pseudocode, no TODOs, no placeholders — the code must be copy-pasteable by implement. Success Criteria must be atomic for this slice: no bullets that depend on symbols/files a later slice introduces.

Context grounding (after slice 2): Before generating, re-read the artifact's Architecture section for files this slice touches AND the ## Slices section for slices already locked. The artifact is the source of truth — generate code and criteria that extend what's already there, not what you remember from conversation.

6.2. Verify slice

Mandatory for every slice — no skipping, no shortcuts. Dispatch the slice-verifier agent with:

• artifact_path: the Step-5 Write file_path (contains the skeleton plus locked prior slices)
• slice_id: Slice N
• current_slice_code: inline the just-generated slice verbatim — every ### path/... block under Architecture with its full code fence AND the slice's ### Success Criteria: block (Automated + Manual subsections from 6.1).
• target_files: files this slice modifies, plus key files prior slices introduced

The agent emits a 3-row summary (Decisions / Cross-slice / Research). On any VIOLATION, take one of:

• Fix-and-re-dispatch: when the finding is a real gap, fix the slice in-place per the citation and re-dispatch until OK.
• Surface-and-proceed: when the finding is plausibly by-design (e.g. foundation-slice atomicity tension, deferred resolution covered by ordering constraints), include the verbatim VIOLATION row in the 6.3 slice presentation with a one-line by-design rationale. The existing 6.3 approve question is the ratification — no separate prompt.

Never proceed to 6.3 with a VIOLATION absent from the presentation.

6.3. Developer micro-checkpoint

Present a condensed review of the slice — NOT the full generated code. The developer reviews the design shape, not every line. For each file in the slice, show:

1. Summary (1-2 sentences): what changed, what pattern used, what it connects to
2. Signatures: type/interface definitions, exported function signatures with parameter and return types
3. Key code blocks: factory calls, wiring, non-obvious logic — the interesting parts that show the design decision in action

Then, once per slice, a mandatory Fit line (always shown, regardless of the omit list below):

Fit — Reused: {existing helpers/utils/types this slice builds on, file:line}. New surface: {new abstractions/exports introduced}. Convention: {naming/error/logging pattern followed + source file:line}.

If the slice introduces a new abstraction where an existing one would serve, or reuses nothing, say so explicitly.

Omit: boilerplate, import lists, full function bodies, obvious implementations. MODIFY files: focused diff (- old / + new) with ~3 lines context. Test files: test case names only.

If the developer asks to see full code, show it inline — exception, not default.

Use the ask_user_question tool to confirm. Question: "Slice {N/M}: {slice name} — {files affected}. {1-line summary}. Approve?". Header: "Slice {N}". Options: "Approve (Recommended)" (Lock this slice, write it exactly to the artifact, then stop at the session boundary); "Revise this slice" (Adjust code before proceeding — describe what to change); "Rethink remaining slices" (This slice reveals a design issue — revisit decomposition); "Revisit a decision" (A Step-4 decision is wrong — return to Step 4 for that decision before continuing).

Checkpoint cadence: One slice per checkpoint. Present each slice individually, regardless of slice count.

6.4. Incorporate feedback

Approve: Lock this slice's code AND Success Criteria and Edit the artifact immediately:

1. For each file in this slice, Edit the skeleton artifact to replace the empty code fence under that file's Architecture heading with the full generated code from 6.1

2. If a later slice contributes to a file already filled by an earlier slice: rewrite the entire code fence with the merged result (do not append alongside existing code)

3. After merge, verify within Architecture: no duplicate function definitions, imports deduplicated, exports list complete

4. Fill the slice's existing ## Slices entry: The skeleton already contains exactly one ### Slice N: {name} subsection. Edit that subsection in place to replace its placeholder verification content with:

   ### Slice N: {slice name}
   
   **Files**: `path/to/file1.ext`, `path/to/file2.ext`
   
   #### Automated Verification:
   - [ ] Type checking passes: `{project typecheck command}`
   - [ ] Tests pass: `{project test command}`
   - [ ] Grep pattern from Verification Note: `grep -r "newApi" packages/ | wc -l` returns >= 3
   
   #### Manual Verification:
   - [ ] New widget renders correctly above the editor
   - [ ] Performance acceptable with 1000+ todo items
   

   This section is the contract handed to /skill:plan — slice boundaries become phase boundaries 1:1, and Success Criteria pass through unchanged. The bullets are the same - [ ] shape implement flips to - [x] and validate extracts commands from. Never add a second Slice N heading; replace the skeleton subsection so heading count remains 1:1 with the decomposition.

5. Update the Design History section: - Slice N: {name} — approved as generated

6. Re-read the just-written code fences and Success Criteria and verify they byte-match the approved payload. A mismatch keeps the slice in progress; correct it before stopping.

7. If another slice remains, STOP THE AGENT RUN. Do not research, generate, or verify the next slice in this session. Print:

   Slice N locked in `<design-path>`.
   Start a fresh session with `/new`, then run:
   `/skill:design --resume <design-path>`
   

   This hard session boundary prevents a sequence of verifier-heavy slices from growing inside one Pi agent run beyond the model context window. The persisted artifact is the handoff; compaction summaries are never exact-code carriers.

8. Only when this was the final slice, continue to Step 7 in the current session.

Revise: Update code per developer feedback. Re-run verify (6.2). Re-present the same slice (6.3). The artifact is NOT touched — only "Approve" writes to the artifact.

Rethink: Developer spotted a design issue. If a previously approved slice is affected, flag the conflict and offer cascade revision — developer decides whether to reopen (if yes, Edit artifact entry). Update decomposition (add/remove/reorder remaining slices) and confirm before continuing.

Revisit a decision: Re-run Step 4 for the flagged ambiguity (one question). If decomposition is unaffected, update ## Decisions and resume 6.1. If affected, cascade like Rethink — for each invalidated approved slice, ask reopen vs. annotate Design History, then update remaining slices. Re-run 6.2 before re-presenting 6.3; artifact untouched until approval.

Step 7: Finalize Design Artifact

The artifact was created as a skeleton in Step 5 and filled progressively in Step 6.4. This step verifies completeness and flips status.

1. Verify all Architecture entries are filled: Every file heading from the decomposition must have a non-empty code block. If any are still empty, return to Step 6 — never fill at finalize time (bypasses 6.2/6.3). Empty here = workflow off-rail.

2. Verify all ## Slices entries are filled: Every ### Slice N: {name} subsection must have a **Files**: line AND non-empty #### Automated Verification: + #### Manual Verification: subsections. If any are still empty, return to Step 6 — Success Criteria authored in 6.1 must be written in 6.4 alongside code. Empty here = workflow off-rail (same invariant as empty code fences).

3. Verify cross-slice file merges: For files touched by multiple slices, confirm the Architecture entry contains the final merged code, not just the last slice's contribution.

4. Update frontmatter via Edit: status: in-progress → status: ready. Design owns no post-finalization review — /skill:plan runs the artifact-code-reviewer + artifact-coverage-reviewer pair against the phased plan that inherits this design's ## Slices boundaries 1:1. Leave last_updated / last_updated_by as-is.

5. Verify template completeness: Ensure all sections from the template reference in Step 5 are present and filled. Edit to fix any gaps.

6. Architecture format reminder:

   • NEW files: ### path/to/file.ext — NEW + one-line purpose + full implementation code block
   • MODIFY files: ### path/to/file.ext:line-range — MODIFY + code block with only the modified/added code (no "Current" block — the original is on disk, implement reads it)

Step 8: Present Design Artifact

Design owns no post-finalization review. Both artifact-code-reviewer and artifact-coverage-reviewer run inside /skill:plan Step 4 against the phased plan that inherits this design's ## Slices boundaries 1:1 — that's where code + Success Criteria + phasing are all visible in one artifact for joint review.

Present the design artifact location to the developer:

Design artifact written to:
`.rpiv/artifacts/designs/{filename}.md`

{N} architectural decisions fixed, {M} new files designed, {K} existing files modified.
{Sl} slices generated, {R} revisions during generation. Success Criteria authored alongside each slice in 6.1 and verified by slice-verifier in 6.2.

Please review and let me know:
- Are the architectural decisions correct?
- Does the code match what you envision?
- Any missing integration points or edge cases?

---

💬 Follow-up: describe the change in chat to append a timestamped Follow-up section to this artifact. Re-run `/skill:design` for a fresh artifact.

**Next step:** `/skill:plan .rpiv/artifacts/designs/{filename}.md` — sequence the design into implementation phases (slice ≡ phase, 1:1) and run the artifact reviewer pair.

> 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window.

Step 9: Handle Follow-ups

• Edit in-place. Use the Edit tool to update the design artifact directly — sliced design code stays one source of truth.
• Bump frontmatter. Update last_updated + last_updated_by; set last_updated_note: "Updated <brief description>".
• Sync decisions ↔ code ↔ criteria. If the change affects decisions, update the Decisions section, the Architecture code, AND the relevant ## Slices Success Criteria. Code is source of truth — if they conflict, the code wins, update the prose and criteria.
• Return to checkpoint on new ambiguities. If new ambiguities surface, return to Step 4 (developer checkpoint) before re-generating slices.
• When to re-invoke instead. If the underlying research is now stale or the feature scope changed materially, re-run /skill:research then /skill:design for a fresh artifact. The previous block's Next step: stays valid for the existing design.

Guidelines

1. Be Architectural: Design shapes code; plans sequence work. Every decision must be grounded in file:line evidence from the actual codebase.

2. Be Interactive: Don't produce the full design in one shot. Resolve ambiguities through the checkpoint first, get buy-in on the approach, THEN decompose and generate slice-by-slice.

3. Be Complete: Code in the Architecture section must be copy-pasteable by implement. No pseudocode, no TODOs, no "implement here" placeholders. If you can't write complete code, an ambiguity wasn't resolved.

4. Be Skeptical: Question vague requirements. If an existing pattern doesn't fit the new feature, say so and propose alternatives. Don't force a pattern where it doesn't belong.

5. Resolve Everything: No unresolved questions in the final artifact. If something is ambiguous, ask during the checkpoint or micro-checkpoint. The design must be complete enough that plan can mechanically decompose it into phases.

6. Present Condensed, Persist Complete: Micro-checkpoints show the developer summaries, signatures, and key code blocks. The artifact always contains full copy-pasteable code. If the developer asks to see full code, show it — but never default to walls of code in checkpoints.

Subagent Usage

Spawn multiple agents in parallel when they're searching for different things. Each agent runs in isolation — provide complete context in the prompt, including specific directory paths when the feature targets a known module. Don't write detailed prompts about HOW to search — just tell it what you're looking for and where.

Important Notes

• Always chained: This skill requires a research artifact produced by the research skill. There is no standalone design mode.
• File reading: Always read research artifacts and referenced files FULLY (no limit/offset) before spawning agents
• Critical ordering: Follow the numbered steps exactly
  • ALWAYS read input files first (Step 1) before spawning agents (Step 2)
  • ALWAYS wait for all agents to complete before identifying ambiguities (Step 3)
  • ALWAYS resolve all ambiguities (Step 4) before decomposing into slices (Step 5)
  • ALWAYS complete holistic decomposition before generating any slice code (Step 6)
  • ALWAYS create the skeleton artifact immediately after decomposition approval (Step 5)
  • ALWAYS generate Success Criteria in Step 6.1 alongside code; NEVER leave Architecture code fences OR ## Slices Success Criteria empty after their slice is approved — both are written via Edit in Step 6.4 from what 6.1 produced
  • NEVER fill empty Architecture content OR empty ## Slices Success Criteria at Step 7 — empty at finalize time = return to Step 6 (preserves the 6.3 micro-checkpoint)
  • ALWAYS dispatch slice-verifier at Step 6.2 for every slice before presenting at 6.3; never skip, never batch across slices; slice-verifier sees code AND Success Criteria together
  • NEVER silently dismiss a slice-verifier VIOLATION — either fix and re-dispatch, or surface the verbatim finding to the developer at 6.3 for ratification
  • Post-finalization code + coverage review runs in /skill:plan Step 4 (not here); design's quality gate is per-slice via slice-verifier at 6.2
  • ALWAYS stop after persisting and byte-checking one approved non-final slice; the next slice starts only through /skill:design --resume <design-path> in a fresh session. Never carry multiple verifier-heavy slices in one agent run.
  • Design flips status: in-progress → status: ready directly at Step 7; no in-review intermediate (no Step 8 reviewer to wait for)
• NEVER skip the developer checkpoint — developer input on architectural decisions is the highest-value signal in the design process
• NEVER edit source files — all code goes into the design document, not the codebase. This skill produces a document, not implementation. Source file editing is implement's job.
• Code is source of truth — if the Architecture code section conflicts with the Decisions prose or the ## Slices Success Criteria, the code wins. Update the prose and criteria.
• Checkpoint recordings: Record micro-checkpoint interactions in Developer Context with file:line references, same as Step 4 questions.
• Frontmatter consistency: Always include frontmatter, use snake_case for multi-word fields, keep tags relevant

Common Design Patterns

• New Features: types first → backend logic → API surface → UI last. Research existing patterns first. Include tests alongside each implementation.
• Modifications: Read current file FULLY. Show only the modified/added code scoped to changed sections. Check integration points for side effects.
• Database Changes: schema/migration → store/repository → business logic → API → client. Include rollback strategy.
• Refactoring: Document current behavior first. Plan incremental backwards-compatible changes. Verify existing behavior preserved.
• Novel Work: Include approach comparison in Decisions. Ground in codebase evidence OR web research. Get explicit developer sign-off BEFORE writing code.