§ 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. This guarantees nothing the planner needs is missing. Simple decisions are recorded withfile:lineevidence; only genuine ambiguities reach the developer. - 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 every slice with
slice-verifierbefore the micro-checkpoint Why: Mandatory at Step 6.2 for every slice — no skipping, no batching across slices. The agent sees the slice's generated code *and* its Success Criteria together and emits a three-rowDecisions / Cross-slice / Researchsummary. A VIOLATION is either fixed and re-dispatched, or surfaced verbatim at the 6.3 micro-checkpoint for developer ratification — never silently dismissed. This is design's only quality gate: theartifact-code-reviewer+artifact-coverage-reviewerpair runs later, inside/skill:planStep 4. - 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