planning-methodology

# Planning Methodology Skill

This skill provides a systematic methodology for creating implementation plans that are surgical, reversible, and minimize risk while maximizing clarity.

## When Claude Should Use This Skill

Claude will automatically invoke this skill when:
- ResearchPack is ready and implementation planning is needed
- User asks "how should we implement...", "create a plan for..."
- Complex feature requires structured approach
- Need to break down requirements into executable steps
- Transforming research into actionable blueprint

## Core Principles (BRAHMA Constitution)

1. **Simplicity over complexity** (KISS, YAGNI)
2. **Minimal changes only** - Touch fewest files possible
3. **Reversibility mandatory** - Every change must be undoable
4. **Verification at each step** - Clear success criteria

## Planning Methodology Protocol

### Step 1: Codebase Discovery (< 90 seconds)

**Objective**: Understand existing structure before planning changes

**Actions**:

1. **Structure scan** (use Glob tool):
   ```
   Search patterns:
   - Source files: src/**/*.{ext}
   - Config files: *.config.{ext}, .{ext}rc
   - Test files: **/*.test.{ext}, **/*.spec.{ext}
   - Documentation: docs/*.md, README.md
   ```

2. **Pattern recognition** (use Grep + Read):
   - How similar features are currently implemented
   - Naming conventions (file names, function names)
   - Code style (indentation, formatting)
   - Import/export patterns
   - Test patterns and frameworks

3. **Integration point identification**:
   - Where does new code connect to existing code?
   - Configuration files that need updates
   - Entry points (main.ts, index.js, etc.)
   - Dependency injection patterns

4. **Constraint discovery**:
   - Existing dependencies that limit choices
   - Framework conventions that must be followed
   - Security/auth patterns that must be maintained
   - Performance SLAs to meet

**Output**:
```
Codebase Profile:
- Primary language: [TypeScript/Python/Go/etc.]
- Framework: [Next.js/Django/Gin/etc.]
- Structure: [src/ organization pattern]
- Test framework: [Jest/pytest/etc.]
- Key patterns: [Dependency injection / Factory / etc.]
- Integration points: [config.ts, app.ts, etc.]
```

**Anti-stagnation**: Max 90 seconds - if codebase is large, focus on areas relevant to feature only

### Step 2: Minimal Change Analysis (< 60 seconds)

**Objective**: Identify the smallest set of changes that accomplishes the goal

**Questions to answer**:

1. **New vs Modify**:
   - Can we extend existing code (better) or must we modify it?
   - Can new functionality live in new files (preferred)?
   - What's the smallest interface between new and existing code?

2. **Reuse vs Rebuild**:
   - What existing utilities/services can be reused?
   - What patterns can we follow from similar features?
   - What must be built from scratch (minimize this)?

3. **Scope boundaries**:
   - What's the absolute minimum to make feature work?
   - What's "nice to have" that can be deferred?
   - What edge cases must be handled vs can be documented as limitations?

4. **Reversibility**:
   - How easily can each change be undone?
   - Are we modifying core/critical files (higher risk)?
   - Can we use feature flags for gradual rollout?

**Output**:
```
Minimal Change Strategy:
- New files: [N] (primary work here)
- Modified files: [N] (minimal edits)
- Deleted files: 0 (avoid deletions, use deprecation)
- Core files touched: [N] (minimize this)
- Reversibility: [Git revert / Config toggle / Feature flag]
```

**Principles**:
- Prefer extension over modification
- Prefer new files over editing existing
- Prefer configuration over code
- Prefer composition over inheritance

### Step 3: Risk Assessment (< 30 seconds)

**Objective**: Identify what could go wrong and plan mitigations

**Categories of risk**:

1. **Breaking changes**:
   - Will this affect existing functionality?
   - Are we modifying shared/core modules?
   - Could this break other features?

2. **Performance risks**:
   - Will this add latency to critical paths?
   - Memory/CPU impact on existing operations?
   - Database query performance degradation?

3. **Security risks**:
   - Does this handle user input (validate & sanitize)?
   - Are credentials/secrets managed properly?
   - Could this introduce injection vulnerabilities?

4. **Integration risks**:
   - Dependencies on external services (what if they're down)?
   - API version mismatches?
   - Race conditions or concurrency issues?

5. **Testing gaps**:
   - What's hard to unit test (integration test instead)?
   - What scenarios might we miss?
   - What's the fallback if tests don't catch an issue?

**For each identified risk**:
```
Risk: [Description]
Probability: [High/Medium/Low]
Impact: [High/Medium/Low]
Mitigation: [How to prevent]
Detection: [How we'll know if it happens]
Contingency: [What we'll do if it happens]
```

**Anti-pattern**: Don't identify risks without mitigations - every risk needs an answer

### Step 4: Implementation Sequence (< 30 seconds)

**Objective**: Order the work for safety and clarity

**Sequencing principles**:

1. **Dependencies first**: Build foundation before dependent features
2. **Tests alongside**: Write tests as you implement (or before - TDD)
3. **Incremental integration**: Connect to existing system gradually
4. **Verification checkpoints**: Each step has clear pass/fail criteria

**Step structure**:
```
Step N: [Action verb] [What]
- Task: [Detailed description]
- Files: [Which files to change]
- Code: [Specific code examples]
- Verification: [How to confirm success]
- Time estimate: [X minutes]
```

**Verification methods**:
- Unit test passes: `npm test path/to/test`
- Build succeeds: `npm run build`
- Manual check: "Navigate to X and confirm Y is visible"
- Integration test: `npm run test:integration`
- Performance check: `npm run benchmark` (if applicable)

**Total time estimate**: Sum of all step estimates + 20% buffer

### Step 5: Rollback Planning (< 20 secon