nixos-configs/home/roles/development/skills/micro/planning.md

description

description
How to create effective implementation plans with phased delivery and clear success criteria

Planning

Create implementation plans that enable incremental, verifiable progress.

Core Principles

1. Incremental delivery: Each phase should produce working, testable changes
2. Clear checkpoints: Success criteria that can be verified without ambiguity
3. Buy-in before detail: Confirm understanding and approach before writing specifics
4. Explicit scope: State what we're NOT doing to prevent scope creep

Plan Document Structure

# {Feature} Implementation Plan

## Overview
{1-2 sentences: what we're building and why}

## Current State Analysis
{What exists now, key constraints, file:line references}

## Desired End State
{Specification of outcome and how to verify it}

## What We're NOT Doing
{Explicit out-of-scope items}

## Phase 1: {Descriptive Name}
### Overview
{What this phase accomplishes - should be independently valuable}

### Changes Required
{Specific files and modifications with code snippets}

### Success Criteria
#### Automated Verification
- [ ] Tests pass: `{test command}`
- [ ] Lint passes: `{lint command}`

#### Manual Verification
- [ ] {Human-observable outcome}

## Testing Strategy
{Unit tests, integration tests, manual testing steps}

## References
{Links to research, related files, similar implementations}

Phase Design

Good phases are:

• Self-contained: Completable in one session
• Testable: Has clear pass/fail criteria
• Reversible: Can be rolled back if needed
• Incremental: Builds on previous phases without requiring all phases

Bad phases are:

• "Refactor everything" (too broad)
• "Add helper function" (too granular)
• Phases that only work if ALL phases complete

Success Criteria Guidelines

Automated Verification (agent-runnable):

• Test commands: make test, npm test, nix flake check
• Lint/format: make lint, cargo fmt --check
• Type checking: make typecheck, tsc --noEmit
• Build verification: make build, nix build

Manual Verification (requires human):

• UI/UX functionality and appearance
• Performance under realistic conditions
• Edge cases hard to automate
• Integration with external systems

From Contribution Guidelines (if CONTRIBUTING.md exists):

• Include any testing requirements specified
• Reference the guideline: "Per CONTRIBUTING.md: {requirement}"

Presenting Understanding

Before writing the plan, confirm alignment:

Based on the requirements and my research, I understand we need to [summary].

I've found that:
- [Current implementation detail with file:line]
- [Relevant pattern or constraint]
- [Potential complexity identified]

Questions my research couldn't answer:
- [Specific technical question requiring judgment]

Only ask questions you genuinely cannot answer through code investigation.

Design Options Pattern

When multiple approaches exist:

**Design Options:**
1. [Option A] - [1-sentence description]
   - Pro: [benefit]
   - Con: [drawback]

2. [Option B] - [1-sentence description]
   - Pro: [benefit]
   - Con: [drawback]

Which approach aligns best with [relevant consideration]?

Get buy-in on approach before detailing phases.