/specs.technical-plan

description: "Creates a Technical Plan document that captures architectural decisions, stack, and implementation phases. Use after specs.brainstorm to document HOW the feature will be built."
argument-hint: "[ --spec=docs/specs/XXX-feature ] [ --from-spec ]"
allowed-tools: Task, Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, TodoWrite
model: inherit

Technical Plan

Creates a Technical Plan document that captures: 1. **Architecture Decisions**: Why choices were made 2. **Technology Stack**: Libraries, versions, alternatives considered 3. **Implementation Phases**: How the feature will be built 4. **Risks & Mitigations**: What could go wrong

Overview

After `specs.brainstorm` generates the functional specification, use this command to document:

• **Stack choices** with exact versions
• **Architecture patterns** to follow
• **Implementation phases** / milestones
• **Performance targets** with metrics
• **Risks** and how to detect them

Usage

# Create from existing spec
/developer-kit-specs:specs.technical-plan --spec=docs/specs/001-feature/

# Create with custom focus
/developer-kit-specs:specs.technical-plan docs/specs/001-feature/

Arguments

| Argument | Required | Description | |----------|----------|-------------| | `--spec` | No | Path to spec folder | | `--from-spec` | No | Generate from spec (implied if spec path provided) |

Examples

Basic Usage

/developer-kit-specs:specs.technical-plan --spec=docs/specs/001-feature/

With Custom Focus

/developer-kit-specs:specs.technical-plan docs/specs/001-feature/

Workflow Position

brainstorm → technical-plan (this) → spec-to-tasks → implementation → review
       ↓
   [WHEN ARCHITECTURAL DECISIONS ARE NEEDED]

Core Principles

• **Concrete over Abstract**: "Node 20.11 LTS" not "Node ≥18"
• **Decision with Rationale**: Why this choice over alternatives
• **Version Pinning**: Every dependency has exact version
• **Risks First**: What could go wrong before how to build it
• **Performance as Requirements**: Metrics are not optional

---

Phase 1: Specification Analysis

**Goal**: Load the functional specification and extract technical implications

**Actions**:

1. **Create todo list** for the technical planning process:

   [ ] Phase 1: Specification Analysis
   [ ] Phase 2: Technology Stack Definition
   [ ] Phase 3: Architecture Decisions
   [ ] Phase 4: Implementation Phases
   [ ] Phase 5: Performance Requirements
   [ ] Phase 6: Risk Assessment
   [ ] Phase 7: File Structure
   [ ] Phase 8: Summary

2. **Parse the spec path** from `$ARGUMENTS`:

• If `--spec=` flag present, extract the path
• If plain path provided, use as-is
• If no path provided, ask user for spec location

3. **Read the functional specification** from the specified path:

• Identify the main spec file (`YYYY-MM-DD--feature-name.md`)
• Read user-request.md for original intent
• Read brainstorming-notes.md for context

4. **Identify technical implications** from the spec:

• What types of components are needed?
• What external integrations are required?
• What data models must be supported?
• What performance expectations are stated?
• What security considerations exist?

5. **List technical concerns** that need decisions:

• Create a working list of decisions to make
• Group by category (stack, architecture, risk)
• Prioritize by implementation order

---

Phase 2: Technology Stack Definition

**Goal**: Document the technology choices with versions

**Actions**:

1. **Check for existing architecture**:

• Look for `docs/architecture.md`
• Look for `docs/specs/architecture.md`
• If exists, inherit existing stack choices
• Add new libraries only if needed for this feature

2. **Ask user for stack components** (or derive from existing architecture):

• Language + version
• Runtime + version
• Framework + version
• Key libraries with exact versions
• Database choices (if applicable)
• Infrastructure components (if applicable)

3. **For each choice, document**:

• What the technology is
• Why this choice over alternatives
• Exact version (no ranges, no "latest")
• Any constraints or requirements

4. **Use AskUserQuestion** for ambiguous choices:

• Present 2-3 options with trade-offs
• Ask for preference with context
• Document the decision and rationale

5. **Generate Technology Stack table**:

## Technology Stack

| Component | Technology | Version | Rationale |
|-----------|-----------|--------|-----------|
| Language | [e.g., TypeScript] | [e.g., 5.4.2] | [Why this over alternatives] |
| Runtime | [e.g., Node.js] | [e.g., 20.11 LTS] | [Performance/stability reasons] |
| Framework | [e.g., NestJS] | [e.g., 10.3.0] | [Why NestJS over Express/Fastify] |
| ORM | [e.g., Drizzle] | [e.g., 0.29.4] | [Type-safety over Prisma] |
| API | [e.g., REST] | [OpenAPI 3.0] | [Simplicity over GraphQL] |
| Auth | [e.g., JWT] | [e.g., passport-jwt 7.0.0] | [Stateless over session] |
| Validation | [e.g., Zod] | [e.g., 3.22.4] | [Type inference over class-validator] |
| Testing | [e.g., Jest] | [e.g., 29.7.0] | [Ecosystem integration] |

6. **Document Forbidden Technologies**:

## Forbidden Technologies

| Technology | Reason Not Used | Alternative Chosen |
|-----------|-----------------|-------------------|
| MongoDB | [Reason: e.g., ACID compliance needed] | PostgreSQL |
| GraphQL | [Reason: e.g., over-engineering for simple API] | REST |
| Mongoose | [Reason: e.g., prefer type-safe ORM] | Drizzle |

7. **Update todo**: Mark Phase 2 complete

---

Phase 3: Architecture Decisions

**Goal**: Document key architectural choices with full context

**Actions**:

1. **Identify 3-5 key decisions** that shape implementation:

• Focus on decisions with trade-offs
• Avoid obvious or constrained choices
• Prioritize decisions that affect multiple components

2. **Chec