implementation-planner

What this skill does

# Implementation Planner Skill

## Purpose

Transform feature research findings into comprehensive, actionable implementation plans with clear steps, dependencies, checkboxes for tracking progress, and identification of parallelizable tasks. The plan format enables systematic implementation by one or multiple developers while maintaining clear visibility of progress.

## When to Use This Skill

Use this skill when:

- Feature research is complete and findings are documented
- Ready to break down a feature into implementable steps
- Need to coordinate implementation across multiple developers
- Want to track progress systematically with checkboxes
- Need to identify task dependencies and parallel work opportunities
- Creating a roadmap for phased implementation
- Planning complex features with multiple integration points

## Plan Structure Philosophy

A good implementation plan is:

- **Detailed Enough**: Each step is clear and actionable
- **Not Over-Detailed**: Avoids micro-management, trusts developer judgment
- **Dependency-Aware**: Clearly marks which steps depend on others
- **Parallelizable**: Identifies tasks that can run concurrently
- **Track able**: Uses checkboxes to show progress
- **Testable**: Each step includes validation criteria
- **Phased**: Breaks large features into logical stages
- **Documentation-Aware**: Always includes a final documentation phase to synchronize the project's Obsidian vault (`[DOC]-*`) with implementation changes

## Creating an Implementation Plan

### Step 1: Review Research Findings

Before creating the plan, thoroughly review:
- Feature requirements and constraints
- Design decisions and rationale
- Integration points identified
- Technical considerations
- Dependencies (external and internal)
- POC results and recommendations

**Input:** `findings.md` or `research-notes.md` from `feature-research` skill

### Step 2: Identify Major Phases

Break the feature into logical phases. Each phase should:
- Deliver incrementally testable functionality
- Have clear boundaries and deliverables
- Be independently testable (backend → frontend → E2E)

**Example Phases for "Email Notifications Feature":**
1. Backend Email Service Implementation
2. Database Schema for Email History
3. Queue Integration with Hangfire
4. Frontend Notification Settings UI
5. Testing and Validation
6. Deployment
7. Documentation Update

### Step 3: Break Phases into Steps

For each phase, create specific, actionable steps.

**Step Granularity Guidelines:**
- ✅ **Right Size**: "Implement EmailService with Microsoft Graph" (2-4 hours)
- ❌ **Too Large**: "Implement entire backend" (days)
- ❌ **Too Small**: "Add using statement for Microsoft.Graph" (minutes)

**Each Step Should Include:**
1. **Clear Action**: What to do (verb-first: "Implement", "Create", "Add", "Test")
2. **Context**: Where or what (file paths, component names)
3. **Acceptance Criteria**: How to know it's done
4. **Dependencies**: What must be completed first (if any)

### Step 4: Mark Dependencies

Identify dependencies between steps:

- **Sequential Dependencies**: Step B cannot start until Step A is complete
- **Parallel-Safe**: Steps that can run simultaneously

**Notation:**
```markdown
## Phase 1: Backend Implementation

- [ ] Step 1: Create User entity (no dependencies)
- [ ] Step 2: Create Form entity (no dependencies)
- [ ] Step 3: Add User-Form relationship (depends on Step 1 & 2)
  - **Depends on**: Step 1, Step 2

**Note**: Steps 1 and 2 can be done in parallel
```

### Step 5: Add Progress Tracking

Use checkboxes for every step:

```markdown
- [x] Completed step (marked as done)
- [ ] Pending step (not started)
```

Include an overall progress tracker:

```markdown
## Progress Overview

- [x] Phase 1: Backend Implementation (100%)
- [ ] Phase 2: Frontend Integration (0%)
- [ ] Phase 3: Testing (0%)
```

### Step 6: Add Validation Criteria

For each step or phase, add clear success criteria:

```markdown
## Phase 1: Backend Implementation

### Validation Criteria
- [ ] Backend compiles without errors
- [ ] All unit tests pass
- [ ] API endpoints return expected responses
- [ ] Database migrations apply successfully
```

### Step 7: Add Documentation Phase

Every plan **MUST** include a final documentation phase after testing/validation. This phase ensures the project's Obsidian vault (`[DOC]-*`) stays synchronized with the implemented code.

**Prerequisites:** The project must have a `[DOC]-*` Obsidian vault directory at its root. If none exists, note it in the plan and skip this phase.

**The Documentation Phase follows the 3-step process: Identifier → Comparer → Décider**

**Standard Documentation Phase Steps:**

1. **Identifier les docs existants**: Scan the `[DOC]-*` vault for ALL documents related to the implemented feature (FEAT, ADR, DB, ARCH, API, DEV, MOC, SPEC files)
2. **Comparer code vs documentation**: For each related document, compare what the doc says vs what the code actually does
3. **Mettre à jour les docs obsolètes**: Edit documents where the code has diverged from documentation
4. **Créer les docs manquants**: Generate new FEAT/ADR/DB/ARCH/API/DEV documents for code that has no documentation
5. **Archiver les docs obsolètes**: Move to `10-Archives/` any documents that describe features/code that no longer exists
6. **Mettre à jour les index MOC**: Add links to new documents in relevant MOC files (MOC-Principal and domain-specific MOCs)
7. **Valider la complétude**: Verify every significant code change is reflected in documentation

**Documentation Types to Consider:**

| Type | Prefix | Folder | Triggered By |
|------|--------|--------|--------------|
| Feature | `FEAT-XXX` | `04-Features/` | New or modified features |
| Decision Record | `ADR-XXX` | `06-ADR/` | Architecture decisions made during implementation |
| Database | `DB-XXX` | `02-Database/` | Database schema changes |
| Architecture | `ARCH-XXX` | `03-Architecture/` | Architecture/structure changes |
| API | `API-XXX` | `05-API/` | New or modified API endpoints |
| Dev Note | `DEV-XXX` | `08-Dev/` | Setup changes, notable problem resolutions, workarounds |
| Map of Content | `MOC-XXX` | `00-MOC/` | Index updates for new documents |

**Key Rules:**
- ALL documentation content must be in **FRENCH**
- Follow templates from `[DOC]-*/_Templates/TPL-*.md`
- Use proper naming conventions (3-digit numbering: FEAT-001, ADR-002)
- Include proper YAML frontmatter (title, type, status, created, updated, tags)
- Use Obsidian wikilinks `[[Document-Name]]` for cross-references
- **Code = Source de Vérité. Documentation = Reflet du Code.**

### Step 8: Validate Plan

Use `scripts/validate_plan.py` to check:
- All sections are present
- Checkboxes are properly formatted
- Dependencies are clearly marked
- Acceptance criteria exist for each phase

## Plan Template Structure

See `references/plan-template.md` for a complete template based on `backend/docs/Plan.md` style.

**Key Sections:**
1. **Overview**: Feature description and scope
2. **Progress Tracker**: High-level phase completion status
3. **Phases**: Detailed breakdown with steps
4. **Validation Criteria**: Success criteria for each phase
5. **Dependencies**: External dependencies (libraries, services)
6. **Notes**: Important considerations or risks

## Identifying Parallelizable Work

### Patterns for Parallel Work

**1. Independent Modules**
```markdown
## Phase 2: Implementation

**Parallel Track A: Backend**
- [ ] Create API endpoints
- [ ] Add validation logic
- [ ] Write unit tests

**Parallel Track B: Frontend**
- [ ] Create UI components
- [ ] Add form validation
- [ ] Write component tests

**Note**: Tracks A and B can run simultaneously if API contract is defined
```

**2. Different Layers**
- Database schema changes (Track A)
- Business logic implementation (Track B, depends on Track A)
- UI implementation (Track C, can start if API contract is defined)

**3. Different Features**
- User authentication (Track A)
- Form builder (Trac