tachyon-beep/implementation-planning

Implementation Planning

Overview

Write comprehensive implementation plans assuming the engineer is skilled but unfamiliar with the codebase and project conventions. Document everything they need: which files to touch for each task, complete code examples, testing commands, documentation to reference, and verification steps. Break work into atomic, committable units following DRY, YAGNI, and TDD principles.

Announce at start: "I'm using the implementation-planning skill to create the implementation plan."

Context: Plans should be created in a dedicated worktree for isolation.

Save plans to: docs/plans/YYYY-MM-DD-<feature-name>.md

When to Use

Use implementation-planning when:

• Multi-step implementation (3+ distinct tasks)
• Complex integration requiring file-level navigation guidance
• Handoff to another developer or future execution session
• TDD cycle needs documentation for consistency across tasks
• Clear requirements exist and architecture approach is defined

Don't use for:

• Single-file changes (just implement directly)
• Well-established patterns with existing guides (reference those instead)
• Exploratory prototyping (plans constrain necessary experimentation)
• Unclear requirements (use brainstorming first)

Atomic Task Granularity

Each step is one atomic action:

• Focused on single outcome
• Independently testable
• Committable as logical unit
• Has clear Definition of Done

Examples of atomic steps:

• "Write the failing test" - one step
• "Run it to verify failure" - one step
• "Implement minimal code to make test pass" - one step
• "Run tests and verify they pass" - one step
• "Commit changes" - one step

NOT atomic:

• "Write and run tests" - two steps combined
• "Implement feature with error handling" - multiple concerns
• "Update code and documentation" - separate commits

Plan Document Header

Every plan MUST start with this header:

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

**Goal:** [One sentence describing what this builds]

**Architecture:** [2-3 sentences about approach]

**Tech Stack:** [Key technologies/libraries]

**Prerequisites:**
- [Any setup needed before starting]
- [Dependencies that must be installed]

---

Task Structure

Each task follows this template:

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145` (lines if known)
- Test: `tests/exact/path/to/test.py`
- Docs: `docs/path/to/reference.md` (if relevant)

**Step 1: Write the failing test**

```python
def test_specific_behavior():
    # Arrange
    input_data = create_test_input()

    # Act
    result = function(input_data)

    # Assert
    assert result == expected_output

Why this test: [Explain what behavior this verifies]

Step 2: Run test to verify it fails

Run: pytest tests/path/test.py::test_specific_behavior -v

Expected output:

FAILED - NameError: name 'function' is not defined

Step 3: Write minimal implementation

def function(input_data):
    """Brief docstring explaining purpose."""
    # Minimal code to make test pass
    return expected_output

Why minimal: [Explain what's deliberately omitted for now]

Step 4: Run test to verify it passes

Run: pytest tests/path/test.py::test_specific_behavior -v

Expected output:

PASSED

Step 5: Commit

git add tests/path/test.py src/path/file.py
git commit -m "feat: add specific feature

- Implements [specific behavior]
- Tests verify [specific condition]

Co-Authored-By: Claude Sonnet 4.5 <[email protected]>"

Definition of Done:

• [ ] Test written and fails for right reason
• [ ] Implementation makes test pass
• [ ] No other tests broken
• [ ] Code committed with clear message

## Quality Standards

**Every task MUST include:**

1. **Exact file paths** - No "update the config file" without path
2. **Complete code** - No "add validation logic" without showing the code
3. **Exact commands** - Full command with flags, not "run tests"
4. **Expected output** - What success/failure looks like
5. **Definition of Done** - Checklist for task completion

**Code examples must be:**
- Complete and runnable
- Include necessary imports
- Show actual logic, not pseudocode
- Have minimal comments (code should be self-explanatory)

## Cross-Skill References

**Reference skills using requirement markers, NOT @ syntax:**

```markdown
# ✅ GOOD: Explicit requirement marker
**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development

**BACKGROUND:** Understanding superpowers:systematic-debugging helps with troubleshooting

# ❌ BAD: @ syntax force-loads and burns context
@skills/test-driven-development/SKILL.md

Common Mistakes

| Mistake | Impact | Fix | |---------|--------|-----| | Vague tasks ("add validation") | Engineer doesn't know what to implement | Include complete validation code in plan | | Missing file paths | Time wasted searching codebase | Exact path for every file touched | | "Run tests" without specifics | Wrong tests run, or none at all | Exact command with file::function and expected output | | Generic commit messages | Hard to review, poor history | Follow conventional commits with context | | Skipping test failure verification | False confidence (test might not work) | Always verify RED before implementing GREEN | | Combining multiple actions in one step | Unclear what to commit, harder to debug | Each step = one atomic action | | Assuming context knowledge | Engineer unfamiliar with codebase stuck | Document which files define types, where utilities live | | Incomplete code examples | "Figure it out" wastes time | Complete, runnable code in plan |

Red Flags - STOP and Revise Plan

These thoughts mean incomplete plan:

| Excuse | Reality | |--------|---------| | "They'll figure out the details" | Details ARE the plan. Document them. | | "File path is obvious from context" | Not obvious to someone unfamiliar. State it explicitly. | | "Standard validation, doesn't need code" | What's standard to you is unclear to others. Show the code. | | "Test command is straightforward" | Exact command eliminates ambiguity. Specify it. | | "This step is quick, combine with next" | Atomic steps = atomic commits. Keep separate. |

If you catch yourself using these rationalizations, STOP and add the missing details.

Execution Handoff

After saving the plan, offer execution choice:

"Plan complete and saved to docs/plans/<filename>.md. Two execution options:

1. Subagent-Driven (this session) - I dispatch fresh subagent per task with code review between tasks for fast iteration

2. Parallel Session (separate) - Open new session with executing-plans for batch execution with checkpoints

Which approach?"

If Subagent-Driven chosen:

• REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development
• Stay in this session
• Fresh subagent per task + code review after each

If Parallel Session chosen:

• Guide them to open new session in the worktree
• REQUIRED SUB-SKILL: New session uses superpowers:executing-plans
• Batch execution with review checkpoints

Principles Summary

DRY (Don't Repeat Yourself):

• Extract common utilities rather than duplicating code
• Reference existing patterns instead of reinventing

YAGNI (You Aren't Gonna Need It):

• Implement only what's specified in requirements
• Don't add "nice to have" features preemptively

TDD (Test-Driven Development):

• Always test first, implementation second
• Watch test fail before writing production code
• Keep implementation minimal to pass test

Frequent Commits:

• Each atomic step = one commit
• Clear, conventional commit messages
• Commits tell the story of implementation