Planning Implementation

Planning Implementation

Break a validated spec or clear task into ordered implementation work, acceptance criteria, dependencies, and verification checkpoints.

For coding-related work, load engineering-principles before this skill. Plans should preserve its defaults for boundaries, validation, tests, tooling, and simple implementation.

Planning Pipeline

This skill is part of a scalable planning pipeline. Each step is optional depending on work size.

engineering-principles (for coding-related work)
  -> idea-sharpening   (if the idea is vague)
  -> brainstorming     (if spec or design is needed)
  -> planning-implementation  (you are here)
       -> high-level-testing-strategy       (if proof strategy is unclear)
       -> when-and-how-to-run-parallel-agents (if work may fan out)
       -> incremental-implementation        (soft next execution loop)
       -> executing-plans-with-subagents    (if delegating bounded tasks)
       -> verification-before-completion    (before completion claims)

• Tiny (typo, single-file fix): skip all and code directly.
• Small (obvious small change in known codebase): quick inline plan, then code.
• Moderate (medium-sized feature in several files): brainstorming, then this skill.
• Big (vague idea and/or big/multi-feature): full pipeline.

Planning commonly recommends implementation workflow next, but the transition is a soft handoff. Stop after planning when the human or orchestrator needs to review, defer, split, or delegate the work.

When to Use

• You have a spec or clear requirements that need breaking into concrete steps
• A task feels too large or vague to start
• Work needs to be parallelized across multiple sessions
• The implementation order isn't obvious
• You need to communicate scope to a human or another agent

When to skip: Single-file changes with obvious scope, or when the spec already contains well-defined tasks with acceptance criteria.

The Planning Process

Step 1: Read-Only Exploration

Before writing any plan, operate in read-only mode:

• Read the spec, relevant docs and relevant codebase sections
• Identify existing patterns and conventions
• Map dependencies between components
• Map likely files and responsibilities before writing tasks
• Note risks and unknowns

Do not write implementation code during planning. The output is a plan or task list, not implementation.

When mapping files, prefer clear responsibilities and existing conventions. Files that change together should usually live together; split by responsibility, not by technical layer alone. If an existing file is unwieldy and the planned change touches it, include a targeted split in the plan, but avoid unrelated restructuring.

Step 2: Map the Dependency Graph

Identify what depends on what:

Database schema
    │
    ├── API models/types
    │       │
    │       ├── API endpoints
    │       │       │
    │       │       └── Frontend API client
    │       │               │
    │       │               └── UI components
    │       │
    │       └── Validation logic
    │
    └── Seed data / migrations

Implementation order follows the dependency graph bottom-up: build foundations first.

Step 3: Slice Vertically

Instead of building all the database, then all the API, then all the UI — build one complete feature path at a time.

Bad (horizontal slicing):

Task 1: Build entire database schema
Task 2: Build all API endpoints
Task 3: Build all UI components
Task 4: Connect everything

Good (vertical slicing):

Task 1: User can create an account (schema + API + UI for registration)
Task 2: User can log in (auth schema + API + UI for login)
Task 3: User can create a todo (todo schema + API + UI for creation)
Task 4: User can view todo list (query + API + UI for list view)

Each vertical slice delivers working, testable functionality.

Step 4: Size Tasks

Use this sizing guide:

Aim for S and M tasks. If a task is L or larger, break it into smaller tasks.

When to break a task down further:

• It would take more than one focused session of agent work
• You cannot describe acceptance criteria in 3 or fewer bullet points
• It touches two or more independent subsystems
• The task title contains "and" (sign of multiple tasks)

Step 5: Write the Plan

Each task follows this structure:

## Task [N]: [Short descriptive title]

**Description:** One paragraph explaining what this task accomplishes.

**Acceptance criteria:**
- [ ] [Specific, testable condition]
- [ ] [Specific, testable condition]

**Verification:**
- [ ] Tests pass: `pytest tests/feature/test_file.py -v`
- [ ] Manual check: [what to verify]

**Dependencies:** [Task numbers this depends on, or None]

**Estimated size:** [XS/S/M/L]

**Files likely touched:**
- `src/path/to/file.py`
- `tests/path/to/test_file.py`

No Placeholders

Every task must contain actionable content. These are plan failures:

• "TBD", "TODO", "implement later", "fill in details"
• "Add appropriate error handling" (without specifying what)
• "Write tests for the above" (without specifying test cases)
• "Similar to Task N" (repeat the detail — the engineer may read tasks out of order)
• Steps that describe what to do without showing specifics

Use exact file paths. Every path should be precise and actionable.

Arrange Tasks With Checkpoints

Order tasks so that:

1. Dependencies are satisfied (build foundation first)
2. Each task leaves the system in a working state
3. Verification checkpoints occur after every 2-3 tasks
4. High-risk tasks are early (fail fast)

## Checkpoint: After Tasks 1-3
- [ ] All tests pass
- [ ] Application builds without errors
- [ ] Core user flow works end-to-end
- [ ] Review with human before proceeding

Plan Document Template

# Implementation Plan: [Feature Name]

## Overview
[One paragraph summary of what we're building]

## Architecture Decisions
- [Key decision 1 and rationale]
- [Key decision 2 and rationale]

## Task List

### Phase 1: Foundation
- [ ] Task 1: ...
- [ ] Task 2: ...

### Checkpoint: Foundation
- [ ] Tests pass, builds clean

### Phase 2: Core Features
- [ ] Task 3: ...
- [ ] Task 4: ...

### Checkpoint: Core Features
- [ ] End-to-end flow works

### Phase 3: Polish
- [ ] Task 5: ...

### Checkpoint: Complete
- [ ] All acceptance criteria met
- [ ] Ready for review

## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| [Risk] | [High/Med/Low] | [Strategy] |

## Open Questions
- [Question needing human input]

For moderate or larger work, save the plan to docs/implementation-plans/YYYY-MM-DD-<feature>.md. For small work, an inline task list is enough. Plans are working artifacts; persist them when they will help coordination, handoff, or later review.

Parallelization

When multiple agents or sessions are available:

• Safe to parallelize: Independent feature slices, tests for already-implemented features, documentation
• Must be sequential: Database migrations, shared state changes, dependency chains
• Needs coordination: Features that share an API contract — define the contract first, then parallelize

Common Rationalizations

Red Flags

• Starting implementation without a written task list for multi-step work
• Tasks that say "implement the feature" without acceptance criteria
• No verification steps in the plan
• All tasks are XL-sized
• No checkpoints between tasks
• Dependency order isn't considered

Related Skills

Review

After writing the plan, review it before proceeding. How you review depends on scope. doubt-early can be part of the review process with same or separate subagent.

Plan scope (few tasks, straightforward dependencies, well-understood domain): Run a quick self-review:

• Are there any "TBD", "TODO", or placeholder steps?
• Does every task have acceptance criteria and a verification step?
• Are tasks ordered by dependency (build foundation first)?
• Do tasks have exact file paths, not vague locations?
• Does the plan cover all requirements in the spec?

Complex or large plan (many tasks, cross-component, risky dependencies): Dispatch a fresh subagent to review the plan document independently before proceeding:

You are a plan document reviewer. Verify this plan is complete and ready for implementation.

**Plan to review:** [PLAN_FILE_PATH]
**Spec for reference:** [SPEC_FILE_PATH]

## What to Check
| Category | What to Look For |
|----------|------------------|
| Completeness | TODOs, placeholders, incomplete tasks, missing steps |
| Spec Alignment | Plan covers spec requirements, no major scope creep |
| Task Decomposition | Tasks have clear boundaries, steps are actionable |
| Buildability | Could an engineer follow this plan without getting stuck? |

## Calibration
Only flag issues that would cause real problems during implementation.
Minor wording, stylistic preferences, and "nice to have" suggestions are not issues.
Approve unless there are serious gaps — missing requirements from the spec,
contradictory steps, placeholder content, or tasks so vague they can't be acted on.

## Output Format
**Status:** Approved | Issues Found
**Issues (if any):** [Task X, Step Y]: [specific issue] - [why it matters for implementation]
**Recommendations:** [advisory suggestions]

Fix any issues found. Iterate if the review exposed meaningful problems.

Verification

Before starting implementation:

• Every task has acceptance criteria
• Every task has a verification step
• Task dependencies are identified and ordered correctly
• No task touches more than ~5 files
• Checkpoints exist between major phases
• For moderate/large or ambiguous work, the human has reviewed and approved the plan