Technical design documents — problem analysis, solution exploration, architectural decisions. Invoke when creating, updating, reviewing, or asking questions about design documents.
Creates structured technical design documents that analyze problems, explore solutions, and record architectural decisions.
npx claudepluginhub xobotyi/cc-foundryThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Technical artifacts that explore problems and solutions before implementation. The deliverable must be equally useful to a person reading it and to an agent consuming it to plan implementation.
Design docs catch mistakes when they're cheapest to fix — before code exists. Writing forces clarity: vague ideas that sound reasonable in conversation fall apart when you have to commit them to structured prose. The act of exploring alternatives surfaces trade-offs that would otherwise emerge as surprises during implementation or review.
They also become architecture decision records. Every design doc captures not just what was decided, but what alternatives were considered and why they were rejected. When someone asks "why did we build it this way?" six months later, the reasoning is preserved — not lost in chat history or someone's memory.
For agent-driven workflows, design docs serve as the contract between human intent and agent execution. An agent that implements from a design doc has explicit goals, non-goals, and constraints — reducing drift from the intended solution.
Write a design doc when 3+ of these apply:
Don't write one when:
Document how the affected system works today:
Verify against source code and configuration — don't rely on secondhand descriptions.
A single option is acceptable when it results from exploration — not when exploration was skipped.
design-docs/ following the file conventions.When to update:
How to update:
Never silently edit — the update trail shows how thinking evolved.
# [Problem/Feature Name]
## Problem Statement
What's broken or needed. Include root cause and impact.
## Current State
How it works now. Architecture, data flow, limitations.
## Goals
- [What this effort must achieve]
## Non-Goals
- [What is deliberately excluded and why]
## Key Insight
(Optional) The realization that shapes the solution space.
## Proposed Solutions
### Option 1: [Name]
[Description]
**Pros:**
- ...
**Cons:**
- ...
### Option 2: [Name]
[Description]
**Pros:**
- ...
**Cons:**
- ...
## Comparison
| Aspect | Option 1 | Option 2 |
|--------|----------|----------|
| ... | ... | ... |
## Recommendation
Which option and why. Include conditions that might change this.
## Cross-Cutting Concerns
Security, privacy, observability, performance, compatibility — as relevant.
## Next Steps
What remains to decide or do before implementation.
## Updates
(Added as document evolves)
### Update (YYYY-MM-DD)
What changed and why.
Before considering a design doc complete:
Weak:
Users complain about slow search.
Strong:
Search latency p95 is 3.2s, up from 800ms after the October data migration. Root cause: the new schema lacks a compound index on (tenant_id, created_at), forcing full table scans. Impact: enterprise customers (40% of revenue) report degraded experience; 3 support tickets this week.
The strong version includes: metric, timeline, root cause, and business impact.
design-docs/ within project directoryNN-short-description.md (e.g., 02-cache-layer-redesign.md)design-docs/completed/ when implementedUnexplored single-option documents: Presenting one solution is fine when alternatives were genuinely considered and found unviable. It's a problem when the author skipped exploration and jumped to "the obvious answer."
Implementation manuals: Design docs explore WHAT and WHY, not HOW. A doc that reads "this is how we implement it" without exploring trade-offs is not a design doc — it's a task description. Save implementation for task decomposition.
No recommendation: Analysis without conclusion forces readers to re-do the thinking. Take a position.
Stale documents: Outdated design docs mislead. Update or mark as superseded.
Missing non-goals: Without explicit non-goals, scope creep is invisible. Readers assume everything related is in scope.
When the design document is complete and the recommendation is accepted:
The design document is complete. The next step is creating a technical design that maps the chosen solution onto the codebase — affected components, tool selection, and sequencing. Would you like to proceed with the technical design?
technical-design skill.This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.