From 2df5009bef95947c7e6e9d3d784bd2199cf68a60 Mon Sep 17 00:00:00 2001 From: Brummel Date: Tue, 2 Jun 2026 13:10:08 +0200 Subject: [PATCH] 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) --- boss/SKILL.md | 77 ++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 55 insertions(+), 22 deletions(-) diff --git a/boss/SKILL.md b/boss/SKILL.md index d73449f..ded18fd 100644 --- a/boss/SKILL.md +++ b/boss/SKILL.md @@ -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