--- name: design description: Design complex features by decomposing them into vertical slices and producing a design artifact (architecture decisions, slice breakdown, file map) in thoughts/shared/designs/. The design feeds the plan or blueprint skill. Use for complex multi-component features touching 6+ files across multiple layers, when the user wants a feature designed before implementation. Requires a research artifact or a solutions artifact (from explore). Prefer design over plan or blueprint when the focus is architecture and decomposition rather than phased execution steps. argument-hint: [research artifact path] --- # 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. **How it works**: - Read input and key source files into context (Step 1) - Spawn targeted research agents for depth analysis (Step 2) - Identify ambiguities — triage into simple decisions and genuine ambiguities (Step 3) - Holistic self-critique — review the combined design for gaps and contradictions (Step 4) - Developer checkpoint — resolve genuine ambiguities one at a time (Step 5) - Decompose into vertical slices holistically before generating code (Step 6) - Generate code slice-by-slice with developer micro-checkpoints (Step 7) - Verify cross-slice integration consistency (Step 8) - Finalize the design artifact (Step 9) - Review and iterate with the developer (Step 10) The final artifact is plan-compatible. ## Step 1: Input Handling When this command is invoked: 1. **Read research artifact**: **Research artifact provided** (argument contains a path to a `.md` file in `thoughts/`): - Read the research artifact FULLY using the Read tool WITHOUT limit/offset - Extract: Summary, Code References, Integration Points, Architecture Insights, 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**: ``` I'll design a feature iteratively from a research artifact. Please provide: `/skill:design [research artifact] [task description]` Research artifact is required. Task description is optional. ``` Then wait for input. 2. **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: - 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 `plan` extract sections — 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 as **simple decisions** (one valid option, obvious from codebase — record in Decisions with `file:line` evidence, do not ask) or **genuine ambiguities** (multiple valid options, conflicting patterns, scope questions, novel choices — queue for Step 5). Inherited research Q/As land as simple; 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 or ambiguity; every dimension is addressed (silently-resolved valid, skipped-unchecked not). ## Step 4: Holistic Self-Critique Before presenting ambiguities to the developer, review the combined design picture holistically. Step 3 triages findings individually — this step checks whether they fit together as a coherent whole. **Prompt yourself:** - What's inconsistent, missing, or contradictory across the research findings, resolved decisions, and identified ambiguities? - What edge cases or failure modes aren't covered by any ambiguity or decision? - Do any patterns from different agents conflict when combined? **Areas to consider** (suggestive, not a checklist): - Requirement coverage — is every requirement from Step 1 addressed by at least one decision or ambiguity? - Cross-cutting concerns — do error handling, state management, or performance span multiple ambiguities without being owned by any? - Pattern coherence — do the simple decisions from Step 3 still hold when viewed together, or does a combination reveal a conflict? - Ambiguity completeness — did Step 3 miss a genuine ambiguity by treating a multi-faceted issue as simple? **Remediation:** - Issues you can resolve with evidence: fix in-place — reclassify simple decisions as genuine ambiguities, or resolve a genuine ambiguity as simple if holistic review provides clarity. Note what changed. - Issues that need developer input: add as new genuine ambiguities to the Step 5 checkpoint queue. - If no issues found: proceed to Step 5 with the existing ambiguity set. ## Step 5: 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 **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. **Choosing question format:** - **`ask_user_question` tool** — when your question has 2-4 concrete options from code analysis (pattern conflicts, integration choices, scope boundaries, priority overrides). The user can always pick "Other" for free-text. 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). - **Free-text with ❓ Question: prefix** — when the question is open-ended and options can't be predicted (discovery, "what am I missing?", corrections). Example: "❓ Question: Integration scanner found no background job registration for this area. Is that expected, or is there async processing I'm not seeing?" **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 6: 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: filename `thoughts/shared/designs/YYYY-MM-DD_HH-MM-SS_topic.md`, repository name from git root, branch and commit from the git context injected at the start of the session (fallbacks: "no-branch" / "no-commit"), author from the injected User (fallback: "unknown") - Timestamp: run `date +"%Y-%m-%dT%H:%M:%S%z"` — raw for `date:` and `last_updated:`, first 19 chars (`T`→`_`, `:`→`-`) for filename slug. - 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 7d). NEW files get full implementation. MODIFY files get only modified/added code — no "Current" block. - **## 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 7c. - **## 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 7d) - **MODIFY files**: heading with `file:line-range` + empty code fence (filled with only the modified code in Step 7d — no "Current" block, the original is on disk) ## Step 7: 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):** ### 7a. Generate slice code (internal) Generate complete, copy-pasteable code for every file in this slice — but **hold it for the artifact, do NOT present full code to the developer**. The developer sees a condensed review in 7c; the full code goes into the artifact in 7d. - **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 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. **Context grounding** (after slice 2): Before generating, re-read the artifact's Architecture section for files this slice touches. The artifact is the source of truth — generate code that extends what's already there, not what you remember from conversation. ### 7b. Self-verify slice Before presenting to the developer, cross-check this slice and produce a structured summary: ``` Self-verify Slice N: - Decisions: {OK / VIOLATION: decision X — fix applied} - Cross-slice: {OK / CONFLICT: file X has inconsistent types — fix applied} - Research: {OK / WARNING: constraint Y not satisfied — fix applied} ``` If violations found: fix in-place before presenting. Include the self-verify summary in the 7c checkpoint presentation. ### 7c. 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 **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 to artifact, proceed to slice {N+1}); "Revise this slice" (Adjust code before proceeding — describe what to change); "Rethink remaining slices" (This slice reveals a design issue — revisit decomposition). **Checkpoint cadence**: Slices 1-2: always individual. Slices 3+: individual if (a) mid-generation agent spawn was needed, (b) MODIFY touches an undiscussed file, or (c) self-verify fixed a violation. Otherwise batch 2-3 slices (max 3). ### 7d. Incorporate feedback **Approve**: Lock this slice's code 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 7a 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: no duplicate function definitions, imports deduplicated, exports list complete 4. Update the Design History section: `- Slice N: {name} — approved as generated` - Proceed to next slice **Revise**: Update code per developer feedback. Re-run self-verify (7b). Re-present the same slice (7c). 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. ## Step 8: Integration Verification After all slices are complete, review cross-slice consistency: 1. **Present integration summary** (under 15 lines): ``` Integration: {feature name} — {N} slices complete Slices: {brief list of slice names and file counts} Cross-slice: {types consistent / imports valid / wiring complete} Research constraints: {all satisfied / N violations noted} ``` 2. **Verify research constraints**: Check each Precedent & Lesson and Verification Note from the research artifact against the generated code. List satisfaction status. 3. **Confirm using the `ask_user_question` tool**. Question: "{N} slices complete, {M} files total. Cross-slice consistency verified. Proceed to design artifact?". Header: "Verify". Options: "Proceed (Recommended)" (Finalize the design artifact (verify completeness, update status)); "Revisit slice" (Reopen a specific slice for revision — Edit the artifact after); "Add missing" (A file or integration point is missing — add to artifact). ## Step 9: Finalize Design Artifact The artifact was created as a skeleton in Step 6 and filled progressively in Step 7d. This step verifies completeness and finalizes. 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 (e.g., a slice was skipped), generate and fill them now. 2. **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. 3. **Update frontmatter** via Edit: set `status: complete`. `last_updated` and `last_updated_by` were set at skeleton creation — leave as-is. 4. **Verify template completeness**: Ensure all 17 sections from the template reference in Step 6 are present and filled. Edit to fix any gaps. 5. **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 10: Review & Iterate 1. **Present the design artifact location**: ``` Design artifact written to: `thoughts/shared/designs/{filename}.md` {N} architectural decisions fixed, {M} new files designed, {K} existing files modified. {S} slices generated, {R} revisions during generation. 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 thoughts/shared/designs/{filename}.md` — sequence the design into implementation phases. > 🆕 Tip: start a fresh session with `/new` first — chained skills work best with a clean context window. ``` ## Step 11: 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 "`. - **Sync decisions ↔ code.** If the change affects decisions, update both the Decisions section AND the Architecture code. Code is source of truth — if they conflict, the code wins, update the prose. - **Return to checkpoint on new ambiguities.** If new ambiguities surface, return to Step 5 (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 | Context | Agents Spawned | |---|---| | Default (research artifact provided) | codebase-pattern-finder, codebase-analyzer, integration-scanner, precedent-locator | | Novel work (new library/pattern) | + web-search-researcher | | During code writing (if needed) | targeted codebase-analyzer for specific files | 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 5) before decomposing into slices (Step 6) - ALWAYS complete holistic decomposition before generating any slice code (Step 7) - ALWAYS create the skeleton artifact immediately after decomposition approval (Step 6) - NEVER leave Architecture code fences empty after their slice is approved — fill via Edit in Step 7d - 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, the code wins. Update the prose. - **Checkpoint recordings**: Record micro-checkpoint interactions in Developer Context with `file:line` references, same as Step 5 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.