PromptWorks/writing-plans/SKILL.md

name

description

writing-plans

Turn a spec or set of requirements into a written, bite-sized implementation plan BEFORE touching code - scope check, file structure, right-sized tasks with no placeholders, global constraints, and a self-review pass, ending in a handoff for execution. Use for any multi-step or multi-file task. Triggers: plan this out, write a plan, how would you approach this, break this down, what is the implementation plan, roadmap this.

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

Assume they are a skilled developer who knows almost nothing about the toolset or problem domain, and doesn't know good test design well.

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

Save plans to: docs/implementationplans/YYYY-MM-DD-<feature-name>.md (unless the repo already uses a different convention, or the user has a different preference — an existing convention in the repo wins).

Scope Check

If the spec covers multiple independent subsystems, it should have been broken into sub-project specs during brainstorming. If not, suggest splitting into separate plans — one per subsystem, each producing working, testable software on its own.

File Structure

Before defining tasks, map out which files will be created/modified and what each is responsible for.

• Design units with clear boundaries and well-defined interfaces; one clear responsibility per file.
• Prefer smaller, focused files — you reason best about code you can hold in context at once.
• Files that change together should live together. Split by responsibility, not technical layer.
• In existing codebases, follow established patterns; don't unilaterally restructure, but if a file you're modifying has grown unwieldy, including a split in the plan is reasonable.

Task Right-Sizing

A task is the smallest unit that carries its own test cycle and is worth a fresh reviewer's gate. Fold setup/config/scaffolding/docs into the task whose deliverable needs them; split only where a reviewer could meaningfully reject one task while approving its neighbor. Each task ends with an independently testable deliverable.

Bite-Sized Task Granularity

Each step is one action (2-5 minutes): "Write the failing test" / "Run it to confirm it fails" / "Implement minimal code to pass" / "Run tests to confirm pass" / "Commit".

Plan Document Header

Every plan MUST start with:

# [Feature Name] Implementation Plan

> **For agentic workers:** Use the subagent-driven-development skill (recommended) or the executing-plans skill to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** [One sentence]
**Architecture:** [2-3 sentences about approach]
**Tech Stack:** [Key technologies/libraries]

## Global Constraints
[Project-wide requirements — version floors, dependency limits, naming/copy rules, platform requirements — one line each, exact values from the spec. Every task's requirements implicitly include this section.]
---

Task Structure

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.py`
- Modify: `exact/path/to/existing.py:123-145`
- Test: `tests/exact/path/to/test.py`

**Interfaces:**
- Consumes: [what this task uses from earlier tasks — exact signatures]
- Produces: [exact function names, parameter/return types later tasks rely on]

- [ ] Step 1: Write the failing test (show the actual test code)
- [ ] Step 2: Run test to verify it fails (exact command + expected failure output)
- [ ] Step 3: Write minimal implementation (show the actual code)
- [ ] Step 4: Run test to verify it passes (exact command + expected output)
- [ ] Step 5: Commit (exact git commands + message)

No Placeholders

Never write: "TBD"/"TODO"/"implement later", "add appropriate error handling", "write tests for the above" (without actual code), "similar to Task N" (repeat the code instead), steps describing what without how, or references to undefined types/functions.

Remember

Exact file paths always. Complete code in every step. Exact commands with expected output. DRY, YAGNI, TDD, frequent commits.

Self-Review (after writing the complete plan)

1. Spec coverage: does every spec requirement map to a task? List gaps.
2. Placeholder scan: search for the red flags above, fix them.
3. Type consistency: do types/signatures/names match across tasks? (e.g. clearLayers() in Task 3 vs clearFullLayers() in Task 7 is a bug.) Fix issues inline, no need to re-review.

Execution Handoff

After saving the plan, offer:

"Plan complete and saved to docs/implementationplans/<filename>.md. Two execution options: 1. Subagent-Driven (recommended) — I dispatch a fresh subagent per task, review between tasks, fast iteration. 2. Inline Execution — Execute tasks in this session using executing-plans, batch execution with checkpoints. Which approach?"

If Subagent-Driven: use the subagent-driven-development skill. If Inline: use the executing-plans skill.