dev-writing-plans

Files (1)

• SKILL.md

SKILL.md (first lines)

# dev-writing-plans: Spec -> Implementation Plan

Takes a spec (from `dev-brainstorming` or provided directly) and produces a granular, ordered implementation plan that `dev-quick-build` or `dev-auto-build` can run - hardened by a review-swarm-until-consensus loop so the plan is sound before a line of code is written.

> **Credit.** The task-template shape, the "Task Right-Sizing" rubric, and the file-structure-before-decomposition step in this skill are structurally derived from Jesse Vincent's [superpowers](https://github.com/obra/superpowers) `superpowers:writing-plans` skill (MIT licensed). See [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md) for the full notice.

## When to Use

- After `dev-brainstorming` produces a spec.
- The user has a clear idea of what to build and needs a step-by-step plan.
- Before any non-trivial implementation (3+ files, new service, cross-project work).

## Inputs

One of:
1. **Spec file** - a spec from `dev-brainstorming` (e.g. `docs/plans/YYYY-MM-DD-<topic>-spec.md`).
2. **Inline description** - the user describes what to build.
3. **Existing code** - the user points to code to refactor/extend.
4. **Locked design artefact** - for a UI/visual feature, an interactive Claude Artifact mockup the user iterated on and locked during `dev-brainstorming`. Treat its URL as the design record: open it alongside any prose spec, and carry the URL into the plan and into any task whose Approach implements it.

If no spec exists and the work is architectural, offer to run `dev-brainstorming` first.

## Workflow

### Step 1: Understand the full picture

1. **Read the spec** completely, if one exists.
2. **Survey the codebase** - existing patterns and conventions, files to modify vs create, test patterns in use, the CI/CD + deploy process, related code that might be affected.
3. **Check dependencies** - prerequisites, other PRs in flight, blocked tickets in your issue tracker.
4. **Identify the critical path** - the minimum sequence that gets something working end to end.

### Step 2: File structure (define BEFORE decomposing)

Lay out the concrete file/module structure the plan will build, mapped to the spec's architecture. This turns an abstract design into named files and catches structural problems before they become task churn.

- **List every file** the plan touches, marked create / modify, with a one-line purpose each.
- **Reuse check on every "create".** For each file/module marked *create*, add a `Reuses: <existing component + path>` (valid only if you actually grepped the codebase and it fits) or `New: <one line on why nothing existing fits>`. A reuse claim from memory is not evidence - grep it. This is where a duplicate helper/component gets caught, before it is built.
- **Place new modules** deliberately: which directory, following the project's existing layout and naming. Do not invent a new structure where the project has a pattern.
- **Name the boundaries** - which unit owns which responsibility, and the interfaces between them. If a file would grow too large or take on two jobs, split it here, in the plan, not mid-build.
- **New cloud resources: exact name and location.** List each new cloud resource the plan creates with its exact name and its region or location, checked against your project's naming conventions (co-locate with what it talks to, measured live). Names of many cloud resources cannot be changed later. `dev-auto-build` signs these off from the plan before its build loop, so a missing location here becomes a question there.
- **Note shared/edited surfaces** - config, schema, routing, types - so their tasks can be ordered first and flagged for risk.
- **Find every producer and consumer of a changed artefact.** When the plan changes something that is fetched, staged, cached, reported or put in a prompt (a file, a token, a path, a payload key), grep the repo for every place that writes or reads it - installers, cron wrappers, second code paths (a resume or wake prompt beside the spawn prompt), list and report tools, test fixtures - and put each one in the file list. Do not stop at the first module that obviously changes. A short read-only survey at planning time usually finds the second prompt, installer or cache key that the obvious change would have missed.

Record this as a "File Structure" section in the plan.

### Step 3: Decompose into right-sized tasks

Break the work into tasks, ordered by dependency, grouped by layer not feature (foundations - data model, API - before features on top). Make verification (tests, smoke checks, integration) explicit tasks, not afterthoughts.

**Plan the simplest thing that meets the spec.** The spec is the scope ceiling, not a launchpad: pick the fewest tasks and files that deliver it, and YAGNI anything the spec did not ask for - no speculative abstractions, no "we might also want" features, no hardening for a case the spec excludes. A plan is easier to overbuild than code, because adding a task costs a line here and a build session later. If a genuinely useful idea is out of scope, it goes in the plan's Non-goals section, not its Task List.

**Task right-sizing** - the rubric every task must pass:

- **One testable result.** After the task, you can verify it works. If you cannot state its verification in one line, it is not one task.
- **One focused session** (~30 minutes of AI work). Bigger = split it.
- **A coherent file set** - the files from Step 2 that change together for one reason.
- **Too big** ("build the API", "add auth") is a project, not a task - decompose it.
- **Too small** (a one-line config change) does not get its own task - fold it into the neighbour it serves.

For each task:

```markdown
### Task {N}: {Title}
**Goal**: {what this achieves - one sentence}
**Files**: {create/modify, from the Step 2 structure}
**Depends on**: {task numbers, or "None"}
**Approach**:
- {step-by-step; specific patterns to follow; reference existing code}
**Verification**:
- {how to confirm it's done: exact test commands, curl calls, or checks}
**Estimated effort**: {S/M/L}
```

### Step 4: Risks and checkpoints

1. **Checkpoint tasks** after every 3-5 tasks or at a milestone - an explicit task that pauses and verifies everything still works together.
2. **Risk flags** (`**Risk**:` field) on any task that touches shared infrastructure, changes a schema or an API contract, or affects other projects - what could go wrong and how to mitigate it.
3. **Rollback notes** for destructive or hard-to-reverse tasks.

### Step 5: Write the plan document

Create `docs/plans/YYYY-MM-DD-<descriptive-name>-plan.md`. **Confirm today's date from the environment first** (the `currentDate` context line, or `date +%F`); never infer it or copy a date from an example; use ISO `YYYY-MM-DD`. (This date discipline does not travel to subagents - restate it in any delegating prompt.) For child projects, use the same path relative to the child root. Create `docs/plans/` if needed.

```markdown
# {Project/Feature Name} - Implementation Plan

**Date**: {ISO YYYY-MM-DD, confirmed from the environment}
**Spec**: {link to the spec file if one exists}
**Design reference**: {locked design artefact URL, if one exists - reference it, don't re-describe it, in any task that implements it}
**Target project**: {directory/repo}
**Estimated total effort**: {S/M/L/XL}
**Tasks**: {count}  |  **Checkpoints**: {count}

## Prerequisites
- {what must be true before starting}

## File Structure
- {create/modify file list from Step 2, with one-line purposes}

## Non-goals / Out of scope
- {what this plan explicitly does NOT do - carried from the spec's Out of Scope, plus anything reviewers or scouting raised that is deliberately deferred. This is the fence the build holds to: an item here is a Follow-up, never a task that quietly reappears.}

## Task List
### Task 1: {Title}
...
### Checkpoint A: {verify milestone}
...

## Execution Notes
- {git strategy: branch name, commit cadence}
- {deploy strategy: how and when}
- {coordination: who/what to notify}

## Definition of Done
- {all task verifications pass; integration tests pass; deployed if applicable; manual checks}
```

### Step 6: Review-swarm-until-consensus loop (the gate)

From itgenius-au/skills-library, MIT.

More from itgenius-au/skills-library