| name | plan |
| description | Creates a technical plan from a functional spec. Defines HOW to build it: architecture decisions, data models, testing strategy, constraints. Reads the actual codebase for context. Use when user says "plan this", "technical plan", "how to build", "architect", "design the solution", or after running /spec. Do NOT use without a spec — run /spec first.
|
| allowed-tools | Read, Glob, Grep, Bash |
| argument-hint | [path to spec or spec content] |
| metadata | {"author":"roberto-ramirez","version":"1.0.0","category":"sdd","tags":["plan","architecture","technical-design","sdd"]} |
/plan
You are creating a technical plan: Define HOW to build what the spec describes.
The plan is the technical layer. This is where the developer's expertise matters most — not in writing the code, but in making the architectural decisions. The plan transforms the abstract spec into a concrete, bounded implementation guide.
Input
You need the functional spec from /spec. If it is not in context:
$ARGUMENTS
If $ARGUMENTS is empty and no spec is in context, ask the user to paste the spec before continuing.
Step 0 — Consult the wiki
Before reading the codebase, check the repo-scoped wiki for prior plans on related topics. A past plan may already describe the technical approach — reusing it avoids rediscovering architecture decisions.
bash "${CLAUDE_PLUGIN_ROOT}/skills/wiki-ingest/scripts/wiki-query.sh" <keywords from the spec>
Extract 3-6 meaningful keywords from the spec in context (feature name, major components, domain terms). Run the query:
- Exit 0 (matches found): present the top 3 matches to the user and ask:
"Found related plans in .wiki/. Reuse one, extend one, or ignore and write a fresh plan?"
If the user chooses to reuse or extend, read the selected page(s) and use them as prior-art context when reading the codebase in Step 1.
- Exit 1 (no matches): continue silently to Step 1.
- Exit 2 (no
.wiki/): continue silently to Step 1. Absence of a wiki is not an error.
Do not block the flow. If the query script is missing or errors, continue with Step 1 — the wiki is optional context, not a hard dependency.
Step 1 — Read the codebase
Before writing the plan, understand the existing codebase:
- Project structure: Read the directory layout, configuration files, and entry points
- Existing patterns: How is similar functionality already implemented? Follow those patterns.
- Conventions: Naming, file organization, testing approach, error handling patterns
- Dependencies: What libraries, frameworks, and tools are already in use?
- Architecture: What layers exist? How does data flow? Where does new code belong?
Do not guess. Read the files. The plan must be coherent with what already exists.
Step 2 — Write the technical plan
Output the following structure:
Technical Plan
Feature: [from spec]
Date: [today's date]
Architecture Decisions
Numbered list of the significant design choices and their rationale. Each decision should reference existing patterns in the codebase when applicable.
- Decision: [what] — Rationale: [why] — Reference: [existing pattern or file if applicable]
Affected Components
List every file, module, service, or layer that will be created or modified.
path/to/component — what changes and why
Data Models / Contracts
If the feature involves data:
- New entities, types, or schemas (describe fields and constraints)
- API contracts (request/response shapes)
- State changes (what data is created, read, updated, deleted)
Keep descriptions structural — field names and types, not code.
Testing Strategy
Define what must be tested and how:
- Unit tests: What logic to test in isolation
- Integration tests: What interactions to test end-to-end
- Edge case tests: Derived directly from the spec's acceptance criteria
- What NOT to test: Explicitly exclude trivial or framework-provided behavior
Technical Constraints
- Performance requirements (if any)
- Security considerations (auth, input validation, data exposure)
- Compatibility constraints (API versioning, backward compatibility)
- Infrastructure requirements (if any)
Risks / Unknowns
Gotchas
These are common failure modes when writing plans. Watch for them:
- Inventing new patterns. Claude loves to introduce new abstractions, design patterns, or folder structures. If the codebase already has a pattern for similar functionality, follow it — even if you think yours is "better." New patterns add cognitive load and inconsistency.
- Not actually reading the codebase. Claude sometimes writes a plausible-sounding plan based on general knowledge instead of reading the actual files. If a decision isn't grounded in a specific file or pattern you read, it's a guess.
- Proposing libraries not in the project. Check
package.json, *.csproj, go.mod, Cargo.toml, etc. before suggesting a new dependency. If the project already has a library that does the job, use it.
- Duplicating the spec. The plan should not restate functional requirements. If you find yourself writing "The system shall...", you're writing spec, not plan. Focus on HOW, not WHAT.
- Vague component descriptions. "Add a new service for handling payments" is useless. "Create
src/services/payment-processor.ts following the pattern in src/services/order-processor.ts, implementing the PaymentService interface" gives the agent something to work with.
- Over-architecting for a single feature. If the spec describes one feature, the plan should not introduce a generic framework that "could support future features." Build what's needed now.
Important constraints
- Ground decisions in the codebase. Every architectural decision should reference existing patterns. If you're introducing something new, explain why.
- Don't over-architect. The plan should describe the minimum viable approach. No premature abstractions, no "just in case" features.
- Don't repeat the spec. The plan assumes the reader has the spec. Focus on technical decisions, not functional descriptions.
- Be specific about locations. "Add a new service" is too vague. "Create
src/services/payment-processor.ts following the pattern in src/services/order-processor.ts" is useful.
- Reference existing conventions. If the project uses a specific testing library, pattern, or folder structure, name it.
- Use extended thinking for complex decisions. When the architecture involves trade-offs between multiple valid approaches, use high-effort reasoning to evaluate each option before committing.
Next step
After the plan is reviewed and approved, run:
/tasks
The spec + plan become the input for task breakdown.
