Implementation Planner Skill Skill

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":

Backend Email Service Implementation
Database Schema for Email History
Queue Integration with Hangfire
Frontend Notification Settings UI
Testing and Validation
Deployment
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:

Clear Action: What to do (verb-first: "Implement", "Create", "Add", "Test")
Context: Where or what (file paths, component names)
Acceptance Criteria: How to know it's done
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:

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

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

Include an overall progress tracker:

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

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

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)
Comparer code vs documentation: For each related document, compare what the doc says vs what the code actually does
Mettre à jour les docs obsolètes: Edit documents where the code has diverged from documentation
Créer les docs manquants: Generate new FEAT/ADR/DB/ARCH/API/DEV documents for code that has no documentation
Archiver les docs obsolètes: Move to 10-Archives/ any documents that describe features/code that no longer exists
Mettre à jour les index MOC: Add links to new documents in relevant MOC files (MOC-Principal and domain-specific MOCs)
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:

Overview: Feature description and scope
Progress Tracker: High-level phase completion status
Phases: Detailed breakdown with steps
Validation Criteria: Success criteria for each phase
Dependencies: External dependencies (libraries, services)
Notes: Important considerations or risks

Identifying Parallelizable Work

Patterns for Parallel Work

1. Independent Modules

## 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 (Track B)
File upload (Track C)

All three can run in parallel if they don't share dependencies

Dependency Matrix

For complex features with many dependencies, create a dependency matrix:

See references/dependency-matrix.md for detailed guidance.

Simple Example:

| Step | Depends On     | Can Run in Parallel With |
|------|----------------|--------------------------|
| A    | None           | B, C                     |
| B    | None           | A, C                     |
| C    | None           | A, B                     |
| D    | A, B, C        | None                     |

Level of Detail Guidelines

What to Include

✅ File Paths: Where to create/modify files

- [ ] Create `src/services/EmailService.ts`
- [ ] Modify `src/api/controllers/SubmissionsController.cs`

✅ Key Interfaces/APIs: What contracts to define

- [ ] Define IEmailService interface with SendEmail and QueueEmail methods

✅ Configuration Changes: What settings to add

- [ ] Add Microsoft Graph credentials to appsettings.json

✅ Dependencies to Install: What packages to add

- [ ] Install Microsoft.Graph NuGet package

✅ Test Requirements: What tests to write

- [ ] Write unit tests for EmailService
- [ ] Write E2E test for email notification flow

What NOT to Include

❌ Exact Code: Leave implementation details to developer

Bad: "Add line 42: const result = await emailService.send()"
Good: "Implement sendEmail method in EmailService"

❌ Obvious Steps: Don't micro-manage

Bad: "Open Visual Studio, Click File > New > Class"
Good: "Create EmailService class"

❌ Implementation Choices: Trust developer judgment

Bad: "Use a for loop to iterate through recipients"
Good: "Send emails to all recipients from form.recipients"

Updating the Plan

The plan is a living document. As implementation progresses:

Mark Steps Complete: Check off completed steps
```
- [x] Create EmailService class
```

Update Progress Percentages:

- [x] Phase 1: Backend (100%)
- [ ] Phase 2: Frontend (60%)

Add Discovered Steps: If new tasks are found

- [ ] Fix CORS configuration (discovered during testing)

Note Blockers: Document issues blocking progress

## Blockers
- Azure AD credentials not yet provisioned (blocking Phase 2)

Adjust Estimates: Update if reality differs from plan

Example Plan: Email Notifications Feature

# Implementation Plan: Email Notifications

## Overview
Add email notifications sent via Microsoft Graph when forms are submitted.

## Progress Tracker
- [x] Phase 1: Backend Email Service (100%)
- [ ] Phase 2: Queue Integration (50%)
- [ ] Phase 3: Frontend Settings (0%)
- [ ] Phase 4: Testing (0%)
- [ ] Phase 5: Documentation Update (0%)

---

## Phase 1: Backend Email Service

### Goals
Implement EmailService using Microsoft Graph API to send emails.

### Steps

- [x] Install Microsoft.Graph NuGet package
- [x] Create `src/Services/EmailService.cs` with IEmailService interface
- [x] Implement SendEmail method using Graph API
- [x] Add Microsoft Graph configuration to appsettings.json
- [x] Write unit tests for EmailService

**Dependencies**: None (can start immediately)

### Validation Criteria
- [x] Email successfully sent in development environment
- [x] Unit tests pass
- [x] Configuration properly loaded from appsettings

---

## Phase 2: Queue Integration

### Goals
Use Hangfire to queue emails for reliability.

### Steps

- [x] Install Hangfire.AspNetCore NuGet package
- [ ] Configure Hangfire in Program.cs
- [ ] Create QueueEmailJob background job
- [ ] Modify SubmissionsController to enqueue emails after submission
- [ ] Test email queuing and processing

**Dependencies**: Phase 1 must be complete
**Parallel Work**: Frontend Settings (Phase 3) can start now if API is defined

### Validation Criteria
- [ ] Emails enqueued successfully
- [ ] Hangfire dashboard shows queued jobs
- [ ] Emails processed from queue
- [ ] Failed emails retry automatically

---

## Phase 3: Frontend Settings

### Goals
Allow admins to configure email recipients in form settings.

### Steps

- [ ] Add recipients field to FormSettings interface
- [ ] Create MultiEmailInput component for recipient management
- [ ] Integrate MultiEmailInput in FormBuilder
- [ ] Update form creation/edit to save recipients
- [ ] Add email validation for recipients

**Dependencies**: API contract from Phase 2
**Parallel Work**: Can run in parallel with Phase 2 implementation

### Validation Criteria
- [ ] Recipients can be added/removed in form builder
- [ ] Invalid emails are rejected
- [ ] Recipients saved to database correctly

---

## Phase 4: Testing

### Goals
Comprehensive testing of email notification flow.

### Steps

- [ ] Write E2E test: Submit form → Email sent
- [ ] Write E2E test: Email delivery failure handling
- [ ] Manual testing with real Microsoft Graph account
- [ ] Performance testing: 100 emails queued simultaneously

**Dependencies**: All previous phases must be complete

### Validation Criteria
- [ ] All E2E tests pass
- [ ] Manual test emails received
- [ ] No performance degradation with high email volume
- [ ] Hangfire dashboard shows successful processing

---

## Phase 5: Documentation Update

### Goals
Synchroniser le vault Obsidian `[DOC]-*` avec tous les changements d'implémentation.

### Steps

- [ ] Scanner le vault `[DOC]-*` pour les docs liés (FEAT, ADR, DB, API, DEV)
- [ ] Comparer documentation existante vs code réel
- [ ] Mettre à jour FEAT-XXX pour la feature email notifications
- [ ] Créer ADR-XXX si des décisions d'architecture ont été prises (choix Microsoft Graph, Hangfire)
- [ ] Créer/mettre à jour API-XXX pour les nouveaux endpoints
- [ ] Mettre à jour les MOC concernés

**Dependencies**: All previous phases must be complete

### Validation Criteria
- [ ] Documentation reflète le code réel
- [ ] Tous les nouveaux documents ont un frontmatter valide
- [ ] Contenu en FRANÇAIS
- [ ] Wikilinks Obsidian corrects

---

## Dependencies

### External
- Microsoft.Graph NuGet package
- Hangfire.AspNetCore NuGet package
- Microsoft Graph API credentials (Azure AD app)

### Internal
- SubmissionsController (modify for email triggering)
- Form entity (add recipients field)

## Notes

- Microsoft Graph requires Azure AD app registration (credentials needed)
- Hangfire requires database storage (use existing PostgreSQL)
- Consider rate limiting for Microsoft Graph API (30 requests/second)

---

**Plan Version**: 1.0
**Last Updated**: [Date]

Tips for Creating Effective Plans

Start with Research: Always base plans on thorough research
Think in Phases: Logical groupings make complex features manageable
Be Specific: "Create EmailService" is better than "Add emails"
Mark Dependencies: Clearly identify what blocks what
Enable Parallelism: Identify independent work streams
Add Validation: Every phase should have clear success criteria
Keep it Living: Update the plan as you learn
Trust Developers: Don't micro-manage implementation details
Use Checkboxes: Visual progress tracking is motivating
Validate Structure: Run validate_plan.py to ensure quality

Common Planning Mistakes

1. Too Granular

Mistake: "Line 42: Add const email = req.body.email" Fix: "Implement email extraction from request body"

2. Missing Dependencies

Mistake: Not marking that Step 5 requires Step 2 to be done first Fix: Explicitly list dependencies for each step

3. No Parallelization

Mistake: Making everything sequential when tasks could be parallel Fix: Identify independent work tracks

4. Vague Steps

Mistake: "Make it work" Fix: "Implement EmailService.SendEmail with Graph API"

5. No Validation Criteria

Mistake: Steps without success criteria Fix: Add "Validation Criteria" section for each phase

Bundled Resources

scripts/validate_plan.py - Validates plan structure and completeness
references/plan-template.md - Complete implementation plan template
references/dependency-matrix.md - Guide for identifying and documenting dependencies

Agent Skills: Implementation Planner Skill

Install this agent skill to your local

Skill Files