Sdd Design
Turn an approved change proposal into a technical design—architecture, data flow, and a concrete file change plan—before implementation starts.
Overview
sdd-design is an agent skill most often used in Validate (also Build) that produces technical design—architecture, data flow, and a file change plan—for a named SDD change.
Install
npx skills add https://github.com/fearovex/claude-config --skill sdd-designWhat is this skill?
- Bridges proposal artifacts to implementation with architecture decisions and justification
- Produces data-flow documentation and a file-level change plan
- Reads prior SDD proposal via memory search before designing
- Follows shared SDD phase preload (project context + spec context)
- Triggered by /sdd-design <change-name> and design-or-architecture intents
- SDD skill resolution uses a 2-tier path order (project-local then global catalog)
- Shared SDD phase steps include Project Context Load and Spec Context Preload
Adoption & trust: 1 installs on skills.sh; 1 GitHub stars; 3/3 security scanners passed (skills.sh audits); trending (+100% hot-view momentum).
What problem does it solve?
You have a proposal or spec for a change but no documented architecture, data flow, or ordered file plan for your agent to implement safely.
Who is it for?
Named feature or refactor tracks where you already ran SDD proposal and need a design gate before coding.
Skip if: One-off edits with no proposal artifact, or teams that skip written design and want the agent to code immediately.
When should I use this skill?
/sdd-design <change-name>, technical design, change architecture, how to implement, or sdd design
What do I get? / Deliverables
You get a technical design artifact that justifies decisions and lists file-level changes, ready for implementation or downstream SDD coding skills in the same change folder.
- Technical design artifact with architecture decisions
- Data flow documentation
- File change plan for the named change
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Canonical shelf is Validate because design locks scope and implementation approach after intent is captured but before build execution. Scope subphase fits spec-driven changes where requirements must become an explicit HOW plan, not ad-hoc coding.
Where it fits
Freeze HOW for a named change after proposal approval so scope does not drift during implementation.
Break a large change into file-level tasks aligned with the design artifact for agent execution.
Capture data-flow and architecture rationale for future operators and contributors.
Compare implemented PR file list against the design plan during review.
How it compares
Use instead of jumping from chat requirements straight to code—this is the structured design step in an SDD workflow, not a generic brainstorming skill.
Common Questions / FAQ
Who is sdd-design for?
Solo and indie builders using Claude-style agents with spec-driven development who want architecture and file plans before implementation.
When should I use sdd-design?
After a proposal exists for a change name—during Validate when scoping implementation, and in Build when turning specs into an agent-ready design; trigger with /sdd-design <change-name> or when you ask for technical design or change architecture.
Is sdd-design safe to install?
Review the Security Audits panel on this Prism page and inspect project-local vs global skill resolution paths before granting memory and filesystem access to your repo.
SKILL.md
READMESKILL.md - Sdd Design
# sdd-design > Produces the technical design with architecture decisions, data flow, and a file change plan. **Triggers**: `/sdd-design <change-name>`, technical design, change architecture, sdd design --- ## Purpose The design defines **HOW to implement** what the specs say the system MUST do. It is the bridge between requirements and code. It documents technical decisions and their justification. --- ## Process ### Skill Resolution When the orchestrator launches this sub-agent, it resolves the skill path using: ``` 1. .claude/skills/sdd-design/SKILL.md (project-local — highest priority) 2. ~/.claude/skills/sdd-design/SKILL.md (global catalog — fallback) ``` Project-local skills override the global catalog. See `docs/SKILL-RESOLUTION.md` for the full algorithm. --- ### Step 0 — Load project context + Spec context preload Follow `skills/_shared/sdd-phase-common.md` **Section F** (Project Context Load) and **Section G** (Spec Context Preload). Both are non-blocking. --- ### Step 1 — Read prior artifacts I must read: - The proposal artifact: - `mem_search(query: "sdd/{change-name}/proposal")` → `mem_get_observation(id)`. - If not found and Engram not reachable: proposal content passed inline from orchestrator. - The spec artifact: - `mem_search(query: "sdd/{change-name}/spec")` → `mem_get_observation(id)`. - If not found and Engram not reachable: spec content passed inline from orchestrator. - `ai-context/architecture.md` if it exists - `ai-context/conventions.md` if it exists Then I read real code: - Relevant entry points - Files that will be affected according to the proposal - Existing patterns to follow (not reinvent) - Existing tests (they reveal current contracts) ### Step 2 — Design the technical solution I evaluate the solution considering: - Patterns already used in the project (prefer consistency) - Minimal impact on existing code - Testability - Reversibility (rollback plan from the proposal) #### Skills Registry cross-reference When recommending a skill, library, or technology pattern in the design, I MUST check the project Skills Registry extracted in Step 0 and follow these rules: - **Registered skill**: reference it by its exact registered name (e.g., `typescript`, `react-19`). - **Global catalog skill, not registered in project**: mark it as optional with a note, e.g. `[optional — not registered in project; add via /skill-add <name>]`. - **Skill not in the global catalog**: state it as a new dependency and flag it for review. This check applies to the Technical Decisions table, the Testing Strategy table, and any inline recommendations in the design narrative. It ensures design output stays aligned with the project's declared toolset. ### Step 3 — Create design.md I persist the design artifact to engram: Call `mem_save` with `topic_key: sdd/{change-name}/design`, `type: architecture`, `project: {project}`, content = full design markdown. Do NOT write any file. If Engram MCP is not reachable: skip persistence. Return design content inline only. Content format: ```markdown # Technical Design: [change-name] Date: [YYYY-MM-DD] Proposal: engram:sdd/[name]/proposal ## General Approach [High-level description of the technical solution in 3-5 lines] ## Technical Decisions | Decision | Choice | Discarded Alternatives | Justification | | ---------- | ---------------- | ------------------------------ | ----------------- | | [decision] | [what is chosen] | [alternative A, alternative B] | [why this choice] | ## Data Flow [ASCII diagram or description of the flow] Example: ``` Request → Middleware → Controller → Service → Repository → DB ↓ Val