# Implementation Planning

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

- Skill: `forgivesam168/implementation-planning` (Agent Skill)
- Install (CLI): `npx skillmds@latest add forgivesam168/implementation-planning`
- Raw SKILL.md: https://api.skillmd.com/api/skills/forgivesam168/implementation-planning/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: See LICENSE.txt in repository root
- Author: forgivesam168 (https://skillmd.com/u/forgivesam168)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/forgivesam168/implementation-planning

---


# 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**:
- Selected Simple / Standard / High-Risk execution mode, confirmed requirements, and the declared plan/lifecycle SSOT
- The mode-required Spec (`03-spec.md`) with clear requirements and acceptance criteria only when the selected mode or lifecycle stage requires it

**Recommended**:
- `01-brainstorm.md` for context and chosen approach
- `02-decision-log.md` for architectural decisions

## Execution Mode Input

Read the already selected execution mode from the task's lifecycle SSOT before planning. `WORKFLOW.md` owns all entry, artifact, and escalation semantics.

| Mode | Planning input |
|------|------|----------------|
| **Simple** | Confirmed inline requirements or an existing project plan; a Change Package and Spec are not mandatory. |
| **Standard** | The declared plan/lifecycle SSOT; use `03-spec.md` when the selected stages or contract require it. |
| **High-Risk** | Complete Change Package with approved requirements, decisions, AC, rollback/migration, verification, and operational evidence. |

**Missing artifacts behavior**: If a mode-required artifact is absent, stop and identify the exact missing prerequisite. Do not infer a required 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**:

```markdown
# 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 TDD handoff only when the selected Standard mode is risk-triggered or the High-Risk **Pre-Implementation Readiness** gate requests supporting self-evaluation. It cannot replace independent review or override deterministic failure:

| 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 direct plan-from-spec route — the spec is already your source of truth. It is not a separate execution mode.

## 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](../specification/SKILL.md) - Previous stage
- [TDD Workflow Skill](../tdd-workflow/SKILL.md) - Next stage
- [WORKFLOW.md](../../WORKFLOW.md) - Overall workflow

---

💡 **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 均為可機械驗證的陳述式（非意圖性描述）