writing-plans - SKILL.md Agent Skill

name: writing-plans description: Writes comprehensive, bite-sized implementation plans from specs or requirements. Use when you have a spec or requirements for a multi-step task, before touching code.

Writing Plans

When to use this skill

Write comprehensive implementation plans assuming the engineer has zero context for the codebase and questionable taste. Document everything they need: which files to touch, complete code, test commands with expected output, docs to reference. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

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

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

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

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:

# [Feature Name] Implementation Plan

> **For Claude:** REQUIRED SUB-SKILL: Use 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]

---

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`

**Step 1: Write the failing test**

```python
def test_specific_behavior():
    result = function(input)
    assert result == expected
```

**Step 2: Run test to verify it fails**

Run: `pytest tests/path/test.py::test_name -v` Expected: FAIL with "function not
defined"

**Step 3: Write minimal implementation**

```python
def function(input):
    return expected
```

**Step 4: Run test to verify it passes**

Run: `pytest tests/path/test.py::test_name -v` Expected: PASS

**Step 5: Commit**

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

Rules

Exact file paths always
Complete code in plan (not "add validation")
Exact commands with expected output
DRY, YAGNI, TDD, frequent commits

Execution Handoff

After saving the plan, offer:

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

1. Subagent-Driven (this session) — fresh subagent per task,
   review between tasks, fast iteration

2. Parallel Session (separate) — open new session, batch
   execution with checkpoints

Which approach?

If Subagent-Driven chosen: Use subagent-driven-development skill.

If Parallel Session chosen: Guide them to open new session → use executing-plans skill.