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:

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

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:

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 - Previous stage
• TDD Workflow Skill - Next stage
• 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 可能以下列藉口略過關鍵步驟：

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