---
name: better-coding-plan
description: "Plan, design, and spec any non-trivial feature, refactor, or system change before code is written. MUST be used when planning a feature, designing an architecture, evaluating approaches, breaking down complex work, or creating a spec — even if the user does not explicitly say plan. Runs Socratic clarification, 2-3 approach exploration, architecture design, bite-sized task breakdown with TDD steps, and a verification plan; produces a design document plus a dependency-ordered task list for implementation. Writes documents only, never production code. Trigger: /better-coding-plan"
metadata:
  version: "2.12.0"
  license: Apache-2.0
---

# Better Coding Plan

The skill between "I have an idea" and "I'm writing code." A capable agent
jumps straight to implementation, produces 400 lines that almost work, and
discovers the real requirements three commits later. This skill forces the
design conversation first.

**Primary objective:** produce a design document and a task list precise enough
that `better-coding-workflow` can execute each task without rediscovering the
requirements. The plan is the contract between intent and implementation.

---

## Activation

Begin the first response after loading with exactly this line:
▸ better-coding-plan active — design first, then plan, then build

Emit it once, then proceed. Do not repeat it later.

---

## Core principle

Spec-Driven Development: the specification is the source of truth, not
scaffolding to discard. Requirements change → update the spec. Implementation
drifts → go back to the spec. The primary job in this phase is authoring
precise intent; translating it into code comes after.

---

## Scope assessment (do this first)

Task sizing and routing are owned by `/better-coding-orient` — run it first if
the size is unclear. Quick reference: **trivial** → skip planning entirely
(state "skipping plan — trivial change"); **small** → lightweight inline
sketch, no formal design doc; **medium** → full plan, design doc recommended;
**large** → full plan + constitution check + architecture review, design doc
required. If unsure, default to one level heavier — over-planning costs
minutes, under-planning costs hours of rework.

**Scope check:** if the request covers multiple independent subsystems, split
into separate plans — each must produce working, testable software on its own.

---

## The pipeline

Clarify → Explore approaches → Design → Break down tasks → Define
verification. Each phase's artifact constrains the next; do not skip phases
for medium/large tasks — skipping creates the ambiguity that leads to rework.

---

## Phase 1 — Clarify (Socratic, before any design)

Goal: eliminate ambiguity before it becomes architecture. A wrong assumption
acted on confidently is more expensive than a question.

### Understand the request

Restate the request in one sentence (if you can't, ask). Separate what is
explicitly requested vs. implied vs. assumed; mark each assumption as
"confirmed" or "needs user input."

### Ask clarifying questions

Ask questions that would change the implementation if answered differently:

- **Scope boundaries** — what is explicitly in and out of scope?
- **User stories** — who does what, and why? What is the user's goal?
- **Edge cases** — empty, malformed, or hostile input; failure behaviour?
- **Constraints** — performance, security, compatibility, timeline, budget?
- **Existing context** — does this extend or replace existing code? Read that
  code before asking about it.
- **Non-functional** — scale, availability, accessibility, observability?

**Present questions in a batch**, not one at a time, and **prefer
multiple-choice options** — they are faster to answer and force concrete
alternatives. 3-7 questions is typical; more than 10 suggests the scope is too
large and should be split.

### Check the constitution

If the project has a constitution (a `CLAUDE.md`, `AGENTS.md`, architecture
decision records, or a `constitution.md`), read it before designing. The
constitution governs every downstream decision — technology choices, coding
standards, architectural patterns. If no constitution exists, infer the
project's principles from the existing codebase and state them explicitly.

Worth checking: stack and version constraints, architectural patterns in use
(MVC, DDD, hexagonal…), testing strategy, coding conventions, security
requirements, deployment constraints.

### Iron law

> **Do not proceed to design until the requirements are unambiguous enough to
> design against.** "I'll figure it out during implementation" means: stop
> and ask.

---

## Phase 2 — Explore approaches (before settling)

Goal: prevent premature commitment to the first idea. The first approach is
rarely the best — it's just the most obvious.

### Generate 2-3 approaches

For any non-trivial design decision, present 2-3 approaches:

```
Approach A: [name]
  How:     [2-3 sentences on the mechanism]
  Pros:    [what it does well]
  Cons:    [what it does poorly]
  Cost:    [rough effort estimate]
  Risk:    [what could go wrong]

Approach B: [name]
  (same fields)

Approach C: [name] (optional)
```

### What to compare

Complexity (least code, fewest moving parts), alignment with the existing
architecture and conventions, risk and rollback clarity, YAGNI (exactly what's
needed, no speculative infrastructure), and testability.

### Recommend

State a recommendation with reasoning ("Recommend B: reuses the existing X
pattern; A misses [edge case]; C is over-engineered") — but the human chooses.
For small tasks with only one sensible approach, state it and move on.

---

## Phase 3 — Design (the architecture)

Goal: produce a design document precise enough that another engineer (or a fresh
AI agent with no context) could implement it correctly. For large designs,
present the document in digestible sections and let the user validate each —
not 300 lines in one approval.

### Design document structure

```
# Design: [Feature Name]

## Goal
[One sentence describing what this builds and why]

## Context
[2-3 sentences: what exists today, what changes, and why now]

## Scope
In scope:
  - [what will be built]
Out of scope:
  - [what will NOT be built — be explicit]

## Approach
[Which approach was chosen and why, referencing the exploration]

## Global constraints
[Project-wide rules every task must respect, copied verbatim from the
constitution/spec: versions, dependency limits, naming, conventions]

## Architecture
### Files
[Which files will be created or modified, and what each is responsible for]

### Data flow
[How data moves through the system — from input to output]

### Interfaces
[Public functions, types, API contracts, component props]

### Data model
[Schema changes, new tables, migrations, data structures]

### Dependencies
[New dependencies, with justification. Why this package? Why not stdlib?]

## Non-functional
- Performance: [expectations and constraints]
- Security: [threats and mitigations]
- Accessibility: [if UI — WCAG 2.2 AA floor; defer to better-coding-frontend]
- i18n: [if user-facing text — locales, string externalization, RTL, formats]
- Privacy: [if UI — self-hosted assets, consent, no PII in URLs/logs]
- Observability: [logging, metrics, tracing]

## Risks
[What could go wrong, and the mitigation for each]

## Open questions
[Anything still unresolved — should be empty before implementation starts]
```

### Architecture sketch

Before defining any tasks, map the structure: files touched/created, the
responsibility of each unit, how data flows between them, the public
interfaces, and how correctness will be proven (the Architecture section of
the design doc above). Before adding code, ask:
- Does this belong in an existing module?
- Does this introduce a *new* responsibility (which may deserve its own home)?
- Is there a cleaner boundary?
- Is there already a suitable abstraction to extend?

Avoid: business logic in controllers/UI/API layers, fat services, utility
dumping grounds, and cross-layer leakage.

**Goal:** a new engineer should be able to tell within ~2 minutes where any
piece of logic lives. If they couldn't, the structure is wrong.

### File structure mapping

Map every file that will be created or modified: one clear responsibility per
file, files that change together live together, split by responsibility not by
technical layer, follow established patterns in existing codebases.

### Dependency direction

Dependencies point inward (infrastructure → domain), never the reverse. No
circular imports. Business logic doesn't depend on framework code. This is the
single most common architectural drift — check it now, not during implementation.

### Cross-cutting quality — decide at plan time

Cheap to decide now, expensive to retrofit. The plan states a decision for
each item that applies; the implementation rules themselves live in
`/better-coding-workflow` and `/better-coding-frontend`:

- **Modular design** — the file mapping follows single-responsibility; no
  planned file ends past ~300 lines. If a change would push a file past the
  threshold, the split is a planned task, not a later surprise.
- **Language convention** — identifiers, comments, docstrings, commit messages,
  and README/docs in clear English, unless the constitution says otherwise.
- **i18n** — every user-facing string goes through the i18n layer from the
  first task (semantic keys, plural rules, locale-aware date/number formats)
  — even if launch is single-language. Retrofitting i18n is the classic
  expensive afterthought.
- **UI quality floor** — for UI features: loading/empty/error/partial states,
  keyboard operability, and WCAG 2.2 AA contrast are acceptance criteria in
  the spec, and the states are explicit tasks — not post-launch polish.
- **Privacy/GDPR** — for UI: fonts/assets self-hosted, no third-party requests
  before consent, no PII in URLs, localStorage, or logs.
- **Errors & secrets** — failure paths and secret sources (env/vault) are
  named in the design, not improvised during implementation.

---

## Phase 4 — Break down tasks (the plan)

Goal: produce a dependency-ordered task list where each task is small enough to
implement correctly in one sitting and verifiable on its own.

### Task granularity

Each task takes **2-10 minutes** for a focused agent. A task that needs "and"
to describe it does two things — split it. Decisions belong in the plan, not
deferred to execution.

### Task structure

Every task follows this template:

```
### 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`

**What:**
[One paragraph describing the change in plain language]

**Interfaces:**
[Consumes / produces — exact signatures, so the task survives a fresh context]

**Steps:**
- [ ] Write the failing test (include the test code)
- [ ] Run test to verify it fails (include the command and expected error)
- [ ] Write minimal implementation (include the complete code — no placeholders)
- [ ] Run test to verify it passes (include the command and expected output)
- [ ] Commit (include the git command and message)

**Verification:**
[How to know this task succeeded — the exact command and expected output]

**Rollback:**
[How to undo this task if something goes wrong]
```

### No placeholders

Every step must contain the actual content an engineer needs. These are **plan
failures** — never write them:

- "TBD" or "to be determined"
- "add validation" (what validation? for what input?)
- "handle edge cases" (which cases? how?)
- "implement the UI" (which components? what props?)
- "fill in the logic here"

If a step requires decisions, make them in the plan. The task list is for
execution, not deliberation.

### Dependency ordering

- Order tasks so each task's dependencies are satisfied by prior tasks.
- Mark tasks that can run in parallel (no dependencies on each other).
- Group tasks into phases if the feature has natural milestones.
- The first task should always be the smallest end-to-end vertical slice that
  produces a working, testable result. Build incrementally from there.

### Skill refresh per work package

Long implementation runs drift away from the discipline. The first step of
every phase/work package in the task list is therefore an explicit skill
invocation — **step 0: invoke `/better-coding-workflow`**, plus
`/better-coding-frontend` when the package touches UI. This refreshes the
engineering rules in context before each package starts, not only once at the
beginning of the whole plan. Write it into the task list literally, as the
first line of every phase, e.g.:

```
Phase 2 — core logic
Step 0: invoke /better-coding-workflow   (skills unload — reload before coding)
Task 4: ...
```

### TDD baked in

Every feature task includes a failing test first — not a suggestion, the
structure of the task. If the project doesn't practice TDD, adapt: define the
acceptance criteria and verification command before the implementation step.

### Type consistency

Signatures, property names, and types must match across all tasks: if Task 1
defines `getUser(id: string): User`, Task 3 cannot call `getUser(userId:
number)`. Check this in self-review.

---

## Phase 5 — Verification plan

Goal: define how the result will be proven correct before implementation
begins. "We'll know it when we see it" is not a verification plan.

### Define acceptance criteria

For each requirement in the spec, define:
- **How to verify it** — the exact command, test, or manual check
- **What success looks like** — the expected output or behavior
- **What failure looks like** — the symptoms that indicate the criterion is not
  met

### Verification hierarchy

Use the strongest available verification for each criterion: automated test →
type check / static analysis → build / lint → manual verification (last resort
— state why automated verification is impossible). The full evidence rules live
in `/better-coding-verify`.

### Regression check

What existing functionality could this change break? List the tests that must
still pass. The verification plan includes running the existing suite, not just
the new tests.

---

## Output format

The plan produces two artifacts:

### 1. Design document

Save to `docs/plans/YYYY-MM-DD-<feature-name>.md` (or the project's convention).
This is the spec — the source of truth for what is being built and why.

### 2. Task list

Either embedded in the design doc or as a separate `tasks.md`. This is what
`better-coding-workflow` executes, task by task.

### Presentation to the user

After producing the artifacts, present a summary:

```
Plan ready.

Design: docs/plans/2025-01-15-user-notifications.md
Tasks:  8 tasks in 3 phases

Phase 1 (foundation):    Tasks 1-3 — data model, interface, base tests
Phase 2 (core):          Tasks 4-6 — notification logic, triggers, delivery
Phase 3 (integration):   Tasks 7-8 — UI integration, e2e test
Each phase: step 0 invokes /better-coding-workflow (+ /better-coding-frontend in phase 3)

Key decisions:
- Chose Approach B (event-driven) over A (polling) for lower latency
- New dependency: nodemailer (justified in design doc)

Open questions: none — all resolved during clarification.

Ready to implement? Use /better-coding-workflow to execute the plan.
```

**Wait for approval before proceeding.** The plan is a contract — both parties
agree on what will be built before implementation starts. If the user requests
changes, update the plan and re-present.

---

## Self-review checklist

Before presenting the plan:

```
[ ] Scope assessed and right-sized?
[ ] All clarifying questions asked and answered?
[ ] Constitution/existing conventions checked?
[ ] 2-3 approaches explored (for non-trivial decisions)?
[ ] Design document complete with all sections?
[ ] File structure mapped with responsibilities?
[ ] Dependency direction verified (inward, no cycles)?
[ ] Tasks are bite-sized (2-10 min each)?
[ ] Every task has exact file paths?
[ ] Every task has complete code (no placeholders)?
[ ] Every task has a TDD step (test first)?
[ ] Tasks are dependency-ordered?
[ ] Type/signature consistency checked across tasks?
[ ] Cross-cutting quality decided (modularity, language, i18n, UI floor, privacy)?
[ ] Every phase/package starts with the /better-coding-workflow refresh step?
[ ] Acceptance criteria defined for each requirement?
[ ] Regression risks identified?
[ ] Open questions resolved (none remaining)?
```

If any answer is "no," the plan is not ready. Fix it before presenting.

---

## Handling changes mid-implementation

When requirements change during implementation (discovered by
`better-coding-workflow`):

1. **Stop implementation** — do not patch the code to match the new understanding.
2. **Update the spec/design doc** — record the change and why.
3. **Update the task list** and re-assess scope (larger category? new approach needed?).
4. **Resume implementation** from the updated plan.

The spec is a living document: when reality diverges, update the plan, not
just the code.

---

## Anti-patterns

| Anti-pattern | Why it's harmful |
|---|---|
| Jumping to code on a vague request | The #1 source of rework. Clarify first. |
| Tasks with placeholders ("TBD", "add logic") | Defers decisions to implementation; creates ambiguity. |
| Tasks that are 30+ minutes of work | Too large to implement reliably; context degrades. Split. |
| Skipping the constitution check | Violates project conventions; creates integration friction. |
| Not waiting for approval | The plan is a contract; unilateral changes break trust. |
| Over-planning a trivial change | Process overhead exceeds the work. Right-size. |

---

## Relationship to the other skills

- `/better-coding-orient` — routes here for medium/large tasks; run it first if size is unclear.
- `/better-coding-workflow` — executes this plan task by task after approval.
- `/better-coding-review` — checks the resulting diff against this plan in Stage 1 (spec compliance).
- `/better-coding-audit` — whole-repo health check; its roadmap items become plans here.
- `/better-coding-debug` — takes over when implementation reveals a bug; return here if the bug changes the design.
- `/better-coding-frontend` — pairs with workflow during implementation of UI scope defined here.
- `/better-coding-verify` — closes the chain; the spec produced here is its requirements checklist.

---

## Note on process

This skill makes planning *consistent*, not *perfect*. Plans rarely survive
implementation unchanged — the value is a structured artifact to update when
reality diverges, so divergence stays visible instead of becoming silent drift.