§ reference · skill
design
Decomposes a complex feature into vertical slices and produces a design artifact (architecture decisions, slice breakdown, file map) that the planning skills consume.
§ 01 · purpose
Purpose
Establishes the *correct architecture* for a change before any phased plan is written. Decomposes the work into the smallest set of vertical slices that can land independently, locks architectural decisions with developer micro-checkpoints, and emits a plan-compatible artifact. Use it when architecture is the hard part of the change.
§ 02 · when to use
When to use it
- The change touches 6+ files across multiple layers.
- Architecture is genuinely load-bearing — schema, API contract, or wiring across boundaries.
- You already have a
researchorexploreartifact and want a separate decomposition pass. - Prefer
blueprintfor mid-sized features where decomposition + plan can fold into one pass.
§ 03 · inputs
Inputs
| Name | Required | Source |
|---|---|---|
research artifact | yes | Path to .rpiv/artifacts/research/*.md or .rpiv/artifacts/solutions/*.md |
task description | no | Free-text alongside the artifact path |
- research artifact
- Read FULLY; its Open Questions seed the ambiguity queue, its Q/As are inherited decisions.
§ 04 · outputs
Outputs
| Artifact | Path | Format |
|---|---|---|
| Design document | .rpiv/artifacts/designs/ | markdown (plan-compatible) |
§ 05 · key steps
Key steps
- Read research + key source files into context Why: The design proceeds against actual code, not against a re-summary of research. Reading the cited files up-front avoids re-discovery cost mid-design.
- Targeted depth research (parallel) Why:
codebase-pattern-finder,codebase-analyzer,integration-scannerand (when commits are available)precedent-locatorrun in parallel. Focuses on HOW things work — not WHERE — because discovery already happened. - Dimension sweep — triage ambiguities Why: Findings are filtered through six dimensions (data model · API · integration · scope · verification · performance) that map 1:1 to
plansections, guaranteeing nothing the planner needs is missing. Simple decisions are recorded withfile:lineevidence; only genuine ambiguities reach the developer. - Holistic self-critique Why: Reviews the combined design for gaps and contradictions before the developer is asked anything — catches issues that per-finding triage misses.
- Developer checkpoint on genuine ambiguities Why: One question at a time, each grounded in
file:lineevidence. Pulls only NEW information the agents could not find. - Decompose into vertical slices, then generate slice-by-slice Why: Whole-feature decomposition first, then per-slice code generation with developer micro-checkpoints between slices. Stops architectural drift across slices without paying full-rewrite cost.
- Verify cross-slice integration Why: After generation, scan all slices for shared contracts (types, signatures, wiring) and confirm they match — the last step before the artifact is finalized.
§ 06 · related skills