implementation-planning

name	implementation-planning
description	Break down specifications into executable implementation plans with TDD integration. Use when asked to "create plan", "break down tasks", "implementation roadmap", "規劃實作", "拆解任務", "執行計畫", or need step-by-step implementation guidance with test strategies and impact analysis. Use when asked to "plan from spec", "spec to plan", "generate plan from requirements". Use when this capability is needed.
metadata	{"author":"forgivesam168"}

Implementation Planning

💡 Recommended Agent: plan-agent (Strategic Planner)

• CLI: Input /agent and select plan-agent
• VS Code: Use @workspace #plan-agent in Chat

⚠️ CLI Note: In CLI, use natural language like "規劃實作計畫". VS Code users can use /create-plan shortcut.

When to Use This Skill

Use this skill when:

• Spec is complete and ready for implementation breakdown
• Need to divide feature into manageable tasks
• Want TDD-integrated task planning
• Need impact analysis for brownfield changes
• 規格文件完成,要開始拆解實作任務
• 需要評估變更對現有系統的影響

Prerequisites

Required:

• 03-spec.md with clear requirements and acceptance criteria

Recommended:

• 01-brainstorm.md for context and chosen approach
• 02-decision-log.md for architectural decisions

Step-by-Step Workflow

Step 1: Requirements Review

Review the spec and confirm:

1. Goals are clear
2. User stories have acceptance criteria
3. Technical requirements are defined
4. Dependencies are identified

Step 2: Task Breakdown

Break down implementation into phases:

Phase Structure

Each phase should:

• Be independently testable
• Take 2-4 hours max (break larger tasks)
• Include clear entry/exit criteria
• Specify test strategy

Example Breakdown

Phase 1: Data Model & Database
Phase 2: Core Business Logic
Phase 3: API Layer
Phase 4: Frontend Integration
Phase 5: E2E Testing & Polish

Step 3: TDD Integration

For each task, specify:

1. Test First: What tests to write
2. Implementation: Minimal code to pass
3. Refactor: Cleanup and optimization
4. Verification: How to confirm completion

Step 4: Impact Analysis (Brownfield)

If modifying existing system:

1. Affected Components: Which files/modules change
2. Breaking Changes: API/schema changes
3. Migration Requirements: Data migration needs
4. Rollback Strategy: How to revert if needed

Step 5: Generate Plan Document

Create changes/<YYYY-MM-DD>-<slug>/04-plan.md:

---

Template:

# Implementation Plan: {Feature Name}

## Overview
{Brief summary of what will be implemented}

**Spec Reference**: `03-spec.md`

## Implementation Strategy

### Approach
{High-level approach: e.g., "Bottom-up: DB → Logic → API → UI"}

### Phases
{Number of phases: e.g., "5 phases, estimated 16-20 hours total"}

---

## Phase 1: {Phase Name}

### Objective
{What this phase accomplishes}

### Tasks

#### Task 1.1: {Task Name}
**Test Strategy** (RED):
- Write test: `{test file path}`
- Test case: {What the test validates}
- Expected failure: {Why it should fail initially}

**Implementation** (GREEN):
- File: `{implementation file path}`
- Changes: {Brief description}
- Minimal code to pass test

**Refactor** (REFACTOR):
- Extract common logic
- Improve naming
- Remove duplication

**Acceptance Criteria**:
- [ ] {Criterion 1}
- [ ] {Criterion 2}
- [ ] Test coverage ≥80%

**Estimated Time**: {X hours}

---

#### Task 1.2: {Task Name}
{Repeat structure}

---

### Phase 1 Exit Criteria
- [ ] All Phase 1 tests passing
- [ ] Code reviewed and refactored
- [ ] Coverage ≥80%
- [ ] No blocking issues

---

## Phase 2: {Phase Name}
{Repeat phase structure}

---

## Dependencies

### External
- {Dependency 1: e.g., "Redis for job queue"}
- {Dependency 2: e.g., "SendGrid API key for email"}


 {Dependency 1: e.g., "User authentication must be complete"}
 {Dependency 2: e.g., "Database migration #123 deployed"}


 Phase 1 must complete before Phase 2
 Phase 3 and Phase 4 can run in parallel

---




| Component | Type | Impact Level | Action Required |
|-----------|------|--------------|-----------------|
|  | Modified | Medium | Update user model |
|  | Modified | High | Breaking change (version bump) |
|  | Modified | Low | Update props |
|  | Modified | Medium | Add new test cases |


 ⚠️ API:  response schema adds  field
 : External clients may break if they validate strict schemas
 : Announce 2 weeks before, provide migration guide
 : Deploy v1 and v2 endpoints in parallel during transition


: Yes
 : 
 : 
 : Run on staging first
 : 30 seconds (10k rows)


 Database: Run down migration
 Code: Deploy previous git commit
 Feature flag: Disable  flag
 Verify: Check health endpoints and logs

---



| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| Email deliverability issues | Medium | High | Configure SPF/DKIM, use reputable service |
| Performance degradation | Low | High | Load test with 10x expected traffic |
| Notification spam | Medium | Medium | Rate limiting, user preferences |

---




 All business logic functions
 Target: 80%+ coverage
 Tools: Jest/Vitest


 API endpoints
 Database operations
 External service mocks


 Critical user flows only
 Tools: Playwright
 Run on: Staging environment


 Load: {X requests/second}
 Duration: {Y minutes}
 Tool: k6/Artillery

---



| Phase | Tasks | Estimated Time | Dependencies |
|-------|-------|---------------|--------------|
| Phase 1 | 3 tasks | 4-6 hours | None |
| Phase 2 | 4 tasks | 5-7 hours | Phase 1 complete |
| Phase 3 | 2 tasks | 3-4 hours | Phase 2 complete |
| Phase 4 | 3 tasks | 4-5 hours | Phase 3 complete |
|  |  |  | Sequential |

---



: ⏳ Awaiting Approval

:
 [ ] All phases reviewed
 [ ] Risks acceptable
 [ ] Timeline reasonable
 [ ] Dependencies available
 [ ] Impact analysis complete (if brownfield)

:
→ Start Phase 1 with TDD: "開始 TDD 實作"
→ Or use workflow orchestrator: "what's next?"

---

Quality Criteria

Must Have:

• ✅ Each task has TDD strategy (Red-Green-Refactor)
• ✅ Acceptance criteria are testable
• ✅ Dependencies identified
• ✅ Estimated timeline provided
• ✅ Impact analysis (if brownfield)

Financial Systems Must Have:

• ✅ Money handling tasks specify precision (no floats)
• ✅ Transaction tasks include idempotency plan
• ✅ Audit logging tasks defined

Nice to Have:

• Sequence diagrams for complex flows
• Risk matrix visualization
• Automated dependency checks

Next Step

After plan approval:

CLI:

Input: "開始 TDD 實作"
[System loads tdd-workflow skill]
→ /agent → Select coder-agent
→ Follow Red-Green-Refactor cycle

VS Code:

Input: /tdd
Or: "start TDD implementation"

Or use workflow orchestrator:

Input: "what's next?"
[System detects plan complete, recommends TDD stage]

When You Have a Spec Ready (Simplified Mode)

If 03-spec.md is already complete, you can skip straight to task breakdown:

1. Load the spec: Review changes/<slug>/03-spec.md acceptance criteria
2. Map AC → Tasks: Each acceptance criterion becomes one or more tasks
3. Generate plan: Use the Phase template above, but reference spec sections
4. Output: changes/<slug>/04-plan.md linked to spec

This is the "plan from spec" fast path — spec is already your source of truth.

Troubleshooting

"The tasks are too large"

Solution: Break down further. Each task should take 2-4 hours max. Use sub-tasks if needed.

"I don't know the estimate"

Solution: Use t-shirt sizing (S/M/L/XL) or Fibonacci (1/2/3/5/8). Refine after Phase 1.

"Should I include ALL edge cases?"

Solution: Include critical edge cases in initial plan. Document "known limitations" for non-critical ones to address later.

"How detailed should test strategy be?"

Solution:

• Specify what to test (behavior, not implementation)
• Name the test file
• List key test cases
• Don't write full test code yet (that's in TDD phase)

Financial Systems Best Practices

Task Breakdown Example

Task 3.2: Implement Transaction Creation Endpoint
Test Strategy:
- Test happy path: valid transaction with idempotency key
- Test duplicate idempotency key returns 409 Conflict
- Test invalid amount (negative, zero) returns 422
- Test money precision: decimal with 4 places

Implementation:
- Use decimal for amount (NOT float)
- Store currency as string (ISO 4217)
- Implement idempotency-key check
- Log all transaction events for audit

Refactor:
- Extract amount validation to shared utility
- Use money value object pattern

Related Documentation

• Specification Skill - Previous stage
• TDD Workflow Skill - Next stage
• WORKFLOW.md - Overall workflow
• TDD Guide - TDD methodology

---

💡 Tip: A good plan is detailed enough to start implementation without confusion, but flexible enough to adapt when reality diverges from expectations.

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.