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:

Goals are clear
User stories have acceptance criteria
Technical requirements are defined
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:

Test First: What tests to write
Implementation: Minimal code to pass
Refactor: Cleanup and optimization
Verification: How to confirm completion

Step 4: Impact Analysis (Brownfield)

If modifying existing system:

Affected Components: Which files/modules change
Breaking Changes: API/schema changes
Migration Requirements: Data migration needs
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:

Tests written without implementation drift from actual behavior
No verifiable increment until all tasks complete — entire phase becomes a single blast radius
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:

Load the spec: Review changes/<slug>/03-spec.md acceptance criteria
Map AC → Tasks: Each acceptance criterion becomes one or more tasks
Generate plan: Use the Phase template above, but reference spec sections
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

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

implementation-planning

SKILL.mdskills/implementation-planning/SKILL.md