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: