implementation-planning
/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".
- Author
- forgivesam168 ↗
- Repository
- ai-dev-workflow ↗
- Licence
- Apache-2.0
- Last repository change
- 16.08.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 16.08.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
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".
Triggers from the description
Original author 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".
How it works
- When to Use This Skill
- Prerequisites
- Execution Mode Input
- Spec Cross-Validation
- Step-by-Step Workflow
- Vertical Slice Strategy
- Anti-Pattern: Horizontal Slicing
- Plan Handoff Gate
- Quality Criteria
- Next Step
SKILL.md preview
---
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**:
- 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 均為可機械驗證的陳述式(非意圖性描述)
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · forgivesam168/ai-dev-workflow | 100 | Apache-2.0 |
| magnus919/agent-skills | 100 | MIT |
| raoofaltaher/science-ultrapowers | 100 | MIT |
| neuromechanist/research-skills | 100 | BSD-3-Clause |
| w7Pratham/planning-skills | 100 | MIT |
| cbrock84/headcount | 90 | MIT |
| zeeshanhanif/agentic-sdlc-kit | 90 | Apache-2.0 |
| jagreehal/jagreehal-claude-skills | 90 | MIT |
| anotb/management-consulting-plugin | 85 | MIT |
Identical content appears in 1 other GitHub folders. We show one copy with the highest score.
Database snapshot: 13.11.2026 · package version ffebbef2d213 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100spec-driven-implementation
Execute spec-driven implementation — auto-detects Quick (plan.md) or Full (tasks.md) mode and runs step-by-step with verification. Use when implementing a planned feature or running TDD tasks. - 100writing-plans
Use when you have a spec, design doc, or requirements and need a detailed implementation plan before coding. Triggers: 'write a plan', 'create implementation plan', 'plan this out', 'break this down into steps', 'convert design to tasks', 'implementation order'. Also invoked by… - 100plan-work
Break down an issue or task into concrete implementation steps with file locations, code changes, and acceptance criteria. Use when the user asks to "plan the implementation", "break down this task", "create an implementation plan", or needs a structured plan before coding. - 100spec
Use when an implementation request is vague, high-ambiguity, or needs requirements, design, and executable tasks before plan-pr-batch or pr-batch. - 84execute-plan
Execute implementation plans step-by-step. Use when user says "execute the plan", "implement the plan we created", "start building based on the plan", "go ahead and implement it", "proceed with the implementation", "execute as a stack", "create a PR stack while implementing",… - 100create-plan
Create detailed implementation plans through interactive research and iteration. This skill should be used when creating new implementation plans, designing feature specifications, planning technical work, or when the user asks to plan an implementation. Triggers on requests…