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".
license	See LICENSE.txt in repository root

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

Workflow Path Selection

Determine the path before planning:

Path	When	Required Inputs
Standard (Med/High risk)	Spec exists (03-spec.md), multi-file change, brownfield	01-brainstorm.md, 02-decision-log.md, 03-spec.md
Fast (Low risk only)	Isolated change, no existing users, easily reverted	01-brainstorm.md (or inline requirements)

Missing artifacts behavior: If 03-spec.md is absent on a Standard path, stop and ask the user to run the spec stage first. Do NOT infer spec from conversation alone.

Spec Cross-Validation

Before Step 1, test each acceptance criterion (AC) in the spec:

"Can I write a concrete, testable implementation step for this AC?"

• If YES → proceed
• If NO → 1 spec gap: record in ## Spec Gaps section and continue. 2 gaps: surface all gaps to user and wait for clarification or explicit "proceed". ≥3 unresolved gaps: stop (BLOCKED).

This prevents ambiguous ACs from producing unverifiable plan tasks.

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"}

### First TDD Slice
> 🎯 **Start here**: Task {Phase.Task} — {one-line description}
> Minimum testable increment. Code Agent begins implementation from this task.

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

---

## Phase 1: {Phase Name}
**Status**: ⏳ Pending | 🔄 In Progress | ✅ Done | 🚫 Blocked
**Depends on**: None | Phase {N}

### Objective
{What this phase accomplishes}

### Tasks

#### Task 1.1: {Task Name}
**Status**: ⏳ Pending | 🔄 In Progress | ✅ Done | 🚫 Blocked
**Depends on**: None | Task {X.Y}
**Test Tier**: L1 (fully mocked) | 🔌 L2 (requires `{CREDENTIAL_NAME}`) | 🔌 L3 (full environment)

**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"}

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

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

---

## Impact Analysis (Brownfield Changes)

### Affected Components
| Component | Type | Impact Level | Action Required |
|-----------|------|--------------|-----------------|
| `lib/users.ts` | Modified | Medium | Update user model |
| `api/v1/users` | Modified | High | Breaking change (version bump) |
| `components/UserProfile` | Modified | Low | Update props |
| `tests/users.test.ts` | Modified | Medium | Add new test cases |

### Breaking Changes
- ⚠️ API: `/api/v1/users` response schema adds `notificationPreferences` field
  - **Impact**: External clients may break if they validate strict schemas
  - **Migration**: Announce 2 weeks before, provide migration guide
  - **Rollback**: Deploy v1 and v2 endpoints in parallel during transition

### Data Migration
**Required**: Yes
- **Script**: `migrations/2024-01-30-add-notification-prefs.sql`
- **Rollback**: `migrations/2024-01-30-add-notification-prefs-down.sql`
- **Test**: Run on staging first
- **Estimated time**: 30 seconds (10k rows)

### Rollback Strategy
1. Database: Run down migration
2. Code: Deploy previous git commit
3. Feature flag: Disable `notifications_enabled` flag
4. Verify: Check health endpoints and logs

---

## Risks & Mitigations

| 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 |

---

## Testing Strategy

### L1 — Unit Tests (fully mocked)
- All business logic functions
- Target: 80%+ coverage
- No real infrastructure required — runs anywhere, CI/CD included

### L2 — Integration Tests (real infrastructure)
- Tasks annotated 🔌 L2 in the task list above
- Requires real credentials (DB connection strings, API keys, etc.)
- Flag as `PENDING_REAL_CREDS` when credentials unavailable; see tdd-workflow Infrastructure-Gated Test Protocol

### L3 — E2E Tests (full environment)
- Critical user flows only
- Run on staging environment
- Human must confirm environment ready before Phase is considered DONE
- Tools: Playwright

### Performance Tests (if needed)
- Load: {X requests/second}
- Duration: {Y minutes}
- Tool: k6/Artillery

---

## Estimated Timeline

| 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 |
| **Total** | **12 tasks** | **16-22 hours** | Sequential |

---

## Approval & Next Steps

**Plan Status**: ⏳ Awaiting Approval

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

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

---

Vertical Slice Strategy

A vertical slice is the smallest testable increment that traverses all application layers — from the entry point (API / UI / CLI) to the data layer — and delivers a fully verifiable feature unit.

Dimension	Vertical Slice ✅	Horizontal Slice ❌
Definition	One feature path end-to-end	All tests in Task 1, all impl in Task 2
Commit size	≤ 1 focused commit	Multiple commits before anything verifiable
Validation point	Each task produces a runnable, testable increment	Only verifiable after all tasks complete

Slice Size Standard

• Each task = one vertical slice = at most 1 focused commit
• Split a task when it touches ≥ 3 independent feature paths
• Pure backend / DB migration: UI layer is optional, but the task must still cover a complete, independently verifiable functional unit (e.g., "migration runs + data is correct + query returns expected rows")

Plan-Agent Enforcement Rule

Before accepting any Task, apply this check:

"Does this Task contain BOTH a test strategy AND an implementation step for the same feature path?"

• YES → vertical slice confirmed; proceed
• NO → flag as Spec Gap; do NOT accept a Task that contains only tests or only implementation

---

Anti-Pattern: Horizontal Slicing

❌ HORIZONTAL SLICING (Forbidden):
  Task 1: Write all unit tests for the feature
  Task 2: Implement all production code
  Task 3: Refactor everything

✅ VERTICAL SLICING (Required):
  Task 1: User can create a basic transaction (RED → GREEN → REFACTOR)
  Task 2: Transaction validates amount precision (RED → GREEN → REFACTOR)
  Task 3: Transaction idempotency key enforced (RED → GREEN → REFACTOR)

Why horizontal slicing is harmful:

1. Tests written without implementation drift from actual behavior
2. No verifiable increment until all tasks complete — entire phase becomes a single blast radius
3. Violates Red-Green-Refactor: there is no RED phase without a specific implementation target

plan-agent enforcement rule: Any Task whose Test Strategy contains only tests or whose Implementation contains only code with no corresponding test strategy must be flagged as a Spec Gap and rewritten as a vertical slice before the plan is approved.

---

Plan Handoff Gate

Run /agentic-eval before approving for TDD implementation stage:

Check	Threshold
Spec Coverage	Every AC in 03-spec.md has ≥1 Task — HARD STOP if any AC unaddressed
Task Executability	Each task has Depends on, Test Tier, Test Strategy, AC — flag if missing
First TDD Slice	Explicitly marked in Implementation Strategy — HARD STOP if missing
Infrastructure Gaps	All 🔌 L2/L3 tasks flagged with required credential names
Risk Coverage	All High-risk items from brainstorm have mitigation in Risks table

Gate PASS → Human approves → Code Agent starts TDD Gate FAIL → Fix the failing dimension and re-run

---

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.

Common Rationalizations

在建立實作計畫過程中，AI 可能以下列藉口略過關鍵步驟：

常見藉口	反制說明
"水平切片是合理起點：先把所有測試建好，再來實作"	⛔ 水平切片是反模式——任何只含測試或只含實作的 Task 均為 Spec Gap，必須重新拆分為垂直切片（每個 Task 從接口到資料層完整可驗證）
"計畫越詳細越好，我把所有 Task 都先列出來"	過度規劃會凍結設計決策——計畫精細度應到「可開始實作」為止，過多預期細節反而阻礙 TDD 的探索性
"依賴關係很明顯，不需要明確標記"	隱性依賴是計畫失敗的主因——每個 Task 的依賴必須明確列出，Phase 順序必須可機械驗證
"Spec 還不完整，我先計畫，邊實作邊補"	Spec Gap 未解決前計畫等於在沙上建房——必須先標記 BLOCKED 並回到 spec-agent 釐清，不得帶著已知 Gap 進入實作

Verification

在輸出 04-plan.md 前，逐項確認（Gate = 交付前閘門；Verification = 自我完成確認）：

• Test-Path changes/<slug>/04-plan.md 回傳 True（計畫文件已實際建立於 Change Package 目錄）
• 所有 Task 均為垂直切片（無只含測試或只含實作的 Task）
• 所有 Task 依賴關係均明確標記（Depends on: 欄位填寫）
• First TDD Slice 已確認（最小可測增量，可立即開始 RED 驗證）
• Spec Coverage Matrix 已完成（所有 FR 和 Story 有對應 Task）
• 無 BLOCKED 狀態 Task（或 BLOCKED 原因已明確說明並回報使用者）
• Phase Exit Criteria 均為可機械驗證的陳述式（非意圖性描述）