docs(boss): treat brainstorm and tdd as co-equal entry paths
Step 3 framed `tdd` as a conditional add-on ("if the profile enables
the tdd phase, dispatch tdd") while `brainstorm` read as the default
spine. The orchestrator inherited that tilt and routed feature work to
`brainstorm` by reflex.
Replace it with an explicit Entry-path reflection run before every
feature dispatch: the two are co-equal, the choice is made per item by
the design line, and the one-line verdict is recorded in the loop. The
autonomy asymmetry (tdd proceeds, a fresh brainstorm cycle bounces
back) is reframed as a context-budget consequence, not a ranking, with
a guard against hardening it into an "im Zweifel brainstorm" reflex.
The one principled tilt now lives inside the test: genuine doubt that
one assertion can pin the behaviour is itself the design-fork signal.
Add two rationalisation rows and a red flag naming the default-to-
brainstorm bias.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
+55
-22
@@ -98,29 +98,59 @@ brainstorm → planner → implement → audit → fieldtest
|
||||
docwriter (post-stability)
|
||||
```
|
||||
|
||||
Match the chosen item to the right entry skill. If a cycle is
|
||||
new and no spec exists: **bounce back first** (per §"Direction
|
||||
freedom" trigger 4 — new cycles never start autonomously); only
|
||||
after the user green-lights the cycle (and the session shape)
|
||||
does `brainstorm` get dispatched. If a spec exists but no plan:
|
||||
`planner`. If a plan exists: `implement`. If a cycle is closing:
|
||||
`audit`. If the iteration is a bug-fix: `debug`. Read each
|
||||
skill's `SKILL.md` trigger section if unsure.
|
||||
Match the chosen item to the right entry skill. If a spec exists
|
||||
but no plan: `planner`. If a plan exists: `implement`. If a cycle
|
||||
is closing: `audit`. If the iteration is a bug-fix: `debug`. For
|
||||
new feature work with no spec or plan yet, run the **Entry-path
|
||||
reflection** below before dispatching anything. Read each skill's
|
||||
`SKILL.md` trigger section if unsure.
|
||||
|
||||
If the project profile enables the `tdd` phase and the picked
|
||||
item is a **test-specifiable feature issue** — its body pins one
|
||||
observable behaviour and the existing-cycle/new-cycle question
|
||||
does not apply (it is a backlog issue, not a top-level work
|
||||
container needing a fresh spec) — dispatch `tdd` autonomously,
|
||||
the same way a bug issue is dispatched to `debug`. `tdd` is its
|
||||
sibling: it authors a RED executable-spec and hands the GREEN
|
||||
side to `implement` mini-mode. This is **not** a new-cycle
|
||||
bounce-back (the test is the spec; no `brainstorm` is dispatched
|
||||
to begin). The bounce-back fires only reactively: if `tdd`
|
||||
reports the behaviour is not test-specifiable (a genuine design
|
||||
fork), that escalation routes to `brainstorm` and — being a new
|
||||
cycle that needs a fresh spec — is a bounce-back to the user per
|
||||
§"Direction freedom" trigger 4.
|
||||
**Entry-path reflection (feature work).** When the profile enables
|
||||
the `tdd` phase, `brainstorm` and `tdd` are two **co-equal** entry
|
||||
paths for new feature work — neither is the default, and the choice
|
||||
is made by reflection every time, not by habit. Before dispatching
|
||||
either, decide which fits the item in hand and record the one-line
|
||||
verdict ("test-specifiable → `tdd`" / "design fork → `brainstorm`")
|
||||
in the loop. The discriminator is the **design line**, not a
|
||||
preference:
|
||||
|
||||
- The item's desired behaviour can be pinned by one honest minimal
|
||||
assertion — "calling X with Y returns Z", a backlog `feature`
|
||||
issue whose body fixes one observable behaviour — then it is
|
||||
**test-specifiable** and `tdd` owns it. Dispatch `tdd`
|
||||
autonomously, the same way a bug issue is dispatched to `debug`:
|
||||
it authors a RED executable-spec and hands the GREEN side to
|
||||
`implement` mini-mode. This is **not** a new-cycle bounce-back —
|
||||
the test is the spec; no `brainstorm` runs to begin.
|
||||
- Writing that one assertion would force a choice between two or
|
||||
three plausible behaviours with real trade-offs — a genuine design
|
||||
fork — then the work needs a prose spec the user approves, and
|
||||
`brainstorm` owns it. Starting a new cycle through `brainstorm` is
|
||||
itself a bounce-back per §"Direction freedom" trigger 4: green-light
|
||||
the cycle (and the session shape) with the user first; only then
|
||||
does `brainstorm` get dispatched.
|
||||
|
||||
The asymmetry in autonomy — a `tdd` dispatch proceeds, a fresh
|
||||
`brainstorm` cycle bounces back — is **not** a ranking of the two
|
||||
skills. It is a consequence of context budget: a fresh `brainstorm`
|
||||
is high-context work the orchestrator cannot compact on its own (see
|
||||
trigger 4), whereas a test-specifiable item is bounded. Do not let
|
||||
that asymmetry harden into a reflex of routing borderline items to
|
||||
`brainstorm` "to be safe" — that is the exact bias this reflection
|
||||
exists to break; apply the design-line test honestly each time. The
|
||||
one principled tilt is two-sided and lives *inside* the test, not
|
||||
above it: genuine doubt about whether one assertion can pin the
|
||||
behaviour *is itself* the design-fork signal, so it resolves to
|
||||
`brainstorm` — not because `brainstorm` is preferred, but because
|
||||
unresolved ambiguity is a fork by definition. A `tdd` bounce-back
|
||||
also fires reactively: if `tdd` later reports the behaviour was not
|
||||
test-specifiable after all, that escalation routes to `brainstorm`
|
||||
and — being a new cycle that needs a fresh spec — is a bounce-back
|
||||
to the user per the same trigger 4.
|
||||
|
||||
If the profile does **not** enable the `tdd` phase, `brainstorm` is
|
||||
the only design entry path and the reflection collapses to it; a new
|
||||
feature cycle with no spec always bounces back first.
|
||||
|
||||
If the working tree is mid-flight (uncommitted changes left over
|
||||
from a previous session): inspect first, then resume the right
|
||||
@@ -293,6 +323,8 @@ actionable ask, not a wrap-up summary.
|
||||
| "Notify can name the iteration code — user will figure out what it means" | No. The notify text is for the user-as-reader who did not watch the orchestrator work. Iteration codes, crate names, function identifiers, type names — all internal, all banned. |
|
||||
| "The previous cycle closed cleanly and the next backlog item is obvious — just dispatch `brainstorm` and keep going" | No. Starting a new cycle is itself a bounce-back. A fresh `brainstorm` is high-context work, and the orchestrator cannot compact its own context — only the user can decide whether the next cycle wants a fresh session or a continuation of this one. The "obviousness" of the candidate is irrelevant; the *cross-cycle hop* is the checkpoint, not the topic choice. |
|
||||
| "It's the same broad area as the cycle I just closed, that's not really a new cycle" | If there is no spec file for it yet and it would route through `brainstorm` to get one, it IS a new cycle for this rule's purposes. The rule keys on "needs a fresh spec", not on subjective continuity. |
|
||||
| "Feature work, so route it to `brainstorm` — that's the safe default" | `brainstorm` and `tdd` are co-equal entry paths on a tdd-enabled profile; neither is the default. Routing a test-specifiable item to `brainstorm` "to be safe" is the exact bias to break — run the Entry-path reflection and pick by the design line. The only tilt toward `brainstorm` is when one honest assertion genuinely cannot pin the behaviour, and that is a design fork, not a default. |
|
||||
| "`tdd` is opt-in / profile-gated, so it's the secondary skill" | Profile-gating is about whether the path is *available*, not about rank. Once enabled, the choice between the two is decided by fit per item, reflected on each time — not by treating `brainstorm` as primary and `tdd` as the exception. |
|
||||
|
||||
## Red Flags — STOP
|
||||
|
||||
@@ -302,6 +334,7 @@ actionable ask, not a wrap-up summary.
|
||||
- About to send a notify that names a crate, an iteration code, or an agent.
|
||||
- About to bounce back at every iteration boundary "just to be safe" — that's reactive deference, not direction freedom.
|
||||
- About to dispatch `brainstorm` on a backlog issue that does not yet have a spec file, without first bouncing back to the user. New cycles never start autonomously.
|
||||
- About to route feature work to `brainstorm` without running the Entry-path reflection — defaulting to it because it "feels safer" than `tdd`, rather than applying the design-line test. On a tdd-enabled profile the two are co-equal; the choice is reflected on each time.
|
||||
|
||||
## Cross-references
|
||||
|
||||
|
||||
Reference in New Issue
Block a user