writing-plans

name	writing-plans
version	1.0.0
description	Use when you have a spec or requirements for a multi-step task, before touching code
dependencies	{"@skill-module-example/subagent-driven-development":"^1.0.0","@skill-module-example/executing-plans":"^1.0.0"}

Writing Plans

Overview

Write comprehensive implementation plans assuming the engineer has zero context for the codebase. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Scope Check

If the spec covers multiple independent subsystems, suggest breaking into separate plans — one per subsystem. Each plan should produce working, testable software on its own.

File Structure

Before defining tasks, map out which files will be created or modified. Design units with clear boundaries and well-defined interfaces. Each file should have one clear responsibility.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes):

• "Write the failing test" - step
• "Run it to make sure it fails" - step
• "Implement the minimal code to make the test pass" - step
• "Run the tests and make sure they pass" - step
• "Commit" - step

Plan Document Header

Every plan MUST start with a header containing: Feature Name, Goal, Architecture summary, Tech Stack.

Task Structure

Each task includes:

• Files: Create, Modify, Test paths
• Steps: With checkbox syntax for tracking
• Code blocks: Complete, runnable code
• Commands: Exact commands with expected output
• Commits: Descriptive commit messages

No Placeholders

Every step must contain the actual content. These are plan failures:

• "TBD", "TODO", "implement later"
• "Add appropriate error handling"
• "Write tests for the above" (without actual test code)
• "Similar to Task N" (repeat the code)
• Steps without code blocks for code steps

Self-Review

After writing the complete plan:

1. Spec coverage: Can you point to a task for each requirement?
2. Placeholder scan: Search for red flags from the "No Placeholders" section
3. Type consistency: Do types, signatures, and names match across tasks?

Execution Handoff

After saving the plan, offer execution choice:

1. Subagent-Driven (recommended) - Fresh subagent per task, review between tasks
2. Inline Execution - Execute tasks in this session using executing-plans