Decompose a plan the gate accepts
Cut one parent record, an epic or a feature, into children that each do something a consumer can see. The plan gate refuses an incomplete child before any build starts.
Rules
- Slice vertically. Each child changes something a consumer can see, so verify has something to check. A schema-only or tests-only child is a horizontal cut.
- Give every child a runnable demonstration in backticks, on one line.
- Scope the file that produces the value, not the file that shows it, and name the child's own file, never a directory glob. Scoping shows how to find the producer.
- Flatten, never nest. A child that needs children was cut wrong.
Steps
Find the producer of each value the work changes, as scoping shows.
Write
plan.toml:[[children]] title = "Refuse a flag with no expiry" acceptance = ["When basicly flag add runs without --expires, the command shall exit 2 and name the flag."] scope = ["src/basicly/flags.py", "tests/test_flags.py", "changelog.d/PARENT-ID.1.added.md"] depends_on = [] demonstration = "`basicly flag add beta --owner me` exits 2 and prints the missing --expires"Preview it with
--dry-run. A line that reads`PATH`: collapses the groupingmeans more than one child writes that path. Give the path to one child, or list it undersharedwhen each child only appends to it. Then run without--dry-run:basicly decompose PARENT-ID --plan plan.toml --dry-run basicly decompose PARENT-ID --plan plan.toml
The plan fields
| Field | Refused when | Notes |
|---|---|---|
title |
absent | Sibling titles are the names depends_on uses. |
acceptance |
absent | Write each criterion in EARS form (trigger, state, condition, optional feature, ubiquitous), so a check can be derived from it. |
scope |
absent | Two children that write one path serialize. |
depends_on |
absent, or cyclic | An empty list is a declaration; an absent key is not. A cycle is refused with its members before any record is created. |
demonstration |
absent, no backticked runnable span, or spread over several lines | A command, a request or a test through the consumer surface. |
shared |
optional | Paths from scope that each child only appends its own entry to, such as a lockfile. |
type |
empty, or not a string | Optional. An absent type makes the child a task. |
budget_tokens |
present but invalid | Optional. Omit it when the user sets no limit. |
integrity |
present but invalid | Optional. |
Spending limits and historical integrity fields are optional.