planning-and-task-breakdown

Files (1)

• SKILL.md

SKILL.md (first lines)

# Planning and Task Breakdown

Create implementation-ready plans for `/addy-auto`. A good plan is not just a strategy document: it is an autonomous work order. Each task must be small, vertical, independently verifiable, and specific enough that an agent can implement it without follow-up questions unless a listed stop condition is hit.

Plan read-only:

1. Read spec and relevant code.
2. Discover and read relevant Architecture Decision Records (ADRs): ADRs explicitly linked from the spec first, then bounded ADR directories such as `docs/adr/`, `docs/adrs/`, `decisions/`, or `docs/decisions/` when filenames/titles/summaries match the spec. If a relevant ADR is not linked from the spec, still carry it into the plan under required context. Do not reinterpret or override ADR decisions; add a stop condition when implementation would require a superseding ADR or human architecture decision.
3. Slice vertical user-visible increments.
4. Decide plan packaging before writing files:
   - Use one plan file for small/simple work: 1–5 tasks, 1–2 vertical slices, one main subsystem, low risk.
   - Use an index plan plus multiple slice plan files for larger/riskier work: 6+ tasks, 3+ slices, multiple subsystems, migrations, public API or auth/security changes, risky refactors, staged rollout, or checkpoints that should be reviewed independently.
   - If the choice is unclear or user preference matters, call `ask_user_question` with choices for single file, split by slice, or agent decides before writing files.
5. Add plan-level required context listing the spec, relevant ADR paths, and steering files such as `AGENTS.md`, `CLAUDE.md`, or service-local guidance.
6. Add acceptance criteria, verification, proof requirements, dependencies, and stop conditions for each task. For ADR-constrained tasks, include the ADR path/ID in the task title or context, summarize the ADR constraints to preserve, and include explicit `must not` acceptance checks from those ADRs. When an ADR is central to the work, put the ADR ID in the task title so downstream issues preserve the steering context.
7. Add per-task status checkboxes for `[ ] Implemented`, `[ ] Verified`, and `[ ] Reviewed` so later workflow steps can keep the plan in sync with reality.
8. Mark dependencies and risky checkpoints.
9. Keep plan concise and executable.

If `/addy-auto` later finds a safe, unambiguous missing-context gap in the plan, it may update the plan to link an existing ADR or required steering file and then continue. If the gap requires new architecture decisions, conflicting ADR interpretation, or a superseding ADR, stop for human input instead of auto-recovering by guessing.

For every implementation task, use this shape:

````md
## Task N: Short imperative task name

- [ ] Implemented
- [ ] Verified
- [ ] Reviewed

Depends on:

- ...

### Objective

- ...

### Context / files

Required context:

- Spec: `docs/specs/YYYY-MM-DD-feature.md`
- ADRs:
  - `docs/adr/NNNN-decision.md`
- Steering files:
  - `AGENTS.md` / `CLAUDE.md` / service-local guidance if relevant

Must preserve ADR constraints:

- ...

- Likely files:
  - `path/to/file.ts`
- Relevant symbols:
  - `symbolName`
- If these are wrong, first locate the equivalent existing files before editing.

### Implementation steps

1. ...
2. ...

### Acceptance criteria

- ...
- Must not violate listed ADR constraints; if implementation requires changing an ADR decision, stop and request a superseding ADR instead.

### Verification

Run:

```sh
...
```

Expected proof:

- ...

### Stop conditions

- Stop if ...
````

For behavior-changing tasks, include at least one regression-oriented verification step that would fail before implementation and pass after implementation.

If exact files, symbols, test commands, or implementation surfaces are unknown, do not guess. Add a discovery-only task first. Before marking that task implemented, require the agent to persist findings into the plan or an explicitly linked durable artifact, and require dependent tasks to reference that persisted section or artifact so fresh `/addy-auto` sessions can resume without hidden context.

```md
## Task 1: Map existing implementation surface

- [ ] Implemented
- [ ] Verified
- [ ] Reviewed

### Objective

- Locate current entrypoints, tests, fixtures, and related utilities.
- Persist findings into this plan under `### Discovery findings`, or into a linked durable artifact named here.
- Do not change source behavior.

### Verification

Run the smallest safe discovery commands or code navigation steps needed.

Expected proof:

- Record exact files, symbols, and commands found for later tasks.
- Update dependent tasks so they reference the persisted findings section or artifact.

### Stop conditions

- Stop if no existing implementation surface can be found.
```

End every plan, or the final slice in a split plan, with a non-task completion audit section. Do not give the audit section `Implemented`, `Verified`, or `Reviewed` lifecycle checkboxes, because `/addy-auto` treats those as normal implementation tasks.

```md

From teknologist/pi-addy-workflow, MIT.

More from teknologist/pi-addy-workflow