420 lines
29 KiB
Markdown
420 lines
29 KiB
Markdown
---
|
|
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 <brief description>"`.
|
|
- **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.
|