feat(pipeline): consolidate cycle recon, add fieldtest probe tier, enforce assumption economy
Implements the three efficiency findings from the #310 pipeline measurement (refs #35): ~691k subagent tokens / ~3.5 h for a deliberately small cycle, with recon duplication as the single biggest obligatory per-cycle cost. 1. Cycle recon (pipeline.md § Cycle recon; specify, planner, brainstorm, boss, plan-recon): recon fan-out is budgeted per cycle, not per phase. One full plan-recon dispatch — normally specify Step 1, in a new pre-spec sources/recon_scope carrier form — serves both the spec's concrete code shapes and the plan's file-map. planner Step 2 becomes reuse-first (freshness / quotability / coverage conditions) with narrowly-bounded delta dispatches (new Delta dispatch contract in plan-recon.md); broad Explore-type grounding sweeps are banned in every mode. Field evidence: 151k (Explore) + 99k (plan-recon) with ~40 % overlap in one bounded cycle. 2. Fieldtest probe tier (fieldtest, fieldtester, pipeline.md, agent-template.md § model rule 2): a cycle whose user-visible delta is a single narrow axis dispatches the per-cycle fieldtest at tier: probe — 1-2 examples on exactly that axis, ~200-word report, explicit model:sonnet dispatch override (no dispatch-level effort override exists; frontmatter effort applies). Probe is a tier, not a skip; the milestone fieldtest always runs full tier on the frontmatter model, keeping the milestone-close gate's >=2-example floor unconditional. 3. Assumption economy (specify Step 3 + self-review item 6): grounding-check cost scales with the spec's assumption count, so specs state current-behaviour claims only where the change relies on them (the gate's own falsity test), demote context-only mentions to ledger citations, and keep iteration scope tight — fewer restatements, never fewer reliances. The gate itself is unchanged. Design reviewed pre-implementation (opus plan review); diff adversarially verified by a 3-lens review workflow (consistency, operability, cross-reference), confirmed findings folded in. refs #35
This commit is contained in:
+58
-4
@@ -113,6 +113,26 @@ Before producing anything, establish what the sources actually say:
|
||||
walk to the contracts the work touches. Note any `status:
|
||||
aspirational` source: its code is a target, not verified fact.
|
||||
|
||||
**Grounding fan-out — the cycle recon.** When the work enters code
|
||||
territory the orchestrator has not recently read, dispatch
|
||||
`../planner/agents/plan-recon.md` **once**, in its pre-spec form —
|
||||
carrier fields (`sources`, `recon_scope`, optional `focus_hint`)
|
||||
defined authoritatively under its **Pre-spec dispatch (cycle
|
||||
recon)** heading. When the sources already settle the change shape
|
||||
(a signature change, a variant add / remove, a symbol removal, a
|
||||
content-pin perturbation), name it in `recon_scope`: that arms the
|
||||
compile-driven enumeration inside the cycle recon and saves
|
||||
`planner` a mandatory delta later. The returned file-map grounds
|
||||
Step 2's criterion evidence and Step 3's `## Concrete code
|
||||
shapes`, and is reused downstream by `planner` — budget, reuse
|
||||
conditions, and delta triggers are defined once in
|
||||
`../docs/pipeline.md` § Cycle recon. A `brainstorm`-fired dispatch
|
||||
that meets that section's coverage condition IS the cycle recon —
|
||||
do not dispatch again. Do NOT ground a spec with a broad
|
||||
Explore-type sweep (§ Cycle recon's ban; field evidence on issue
|
||||
#35: a 151k-token Explore sweep here, ~40 % duplicated by the
|
||||
later plan-recon).
|
||||
|
||||
### Step 1.5 — Precondition gate (bounce-back)
|
||||
|
||||
Enumerate the **load-bearing design decisions** the spec must encode
|
||||
@@ -312,6 +332,24 @@ follows as an explicitly secondary subsection, never first. Prose may
|
||||
*explain* code, never *replace* it. Exact bytes / line-numbers remain
|
||||
the planner's job — the spec owns the *shape*, shown.
|
||||
|
||||
**Assumption economy — fewer restatements, never fewer reliances.**
|
||||
Every assertion the spec makes about *current* codebase behaviour is
|
||||
a load-bearing-assumption candidate the Step-5 `grounding-check`
|
||||
must extract and ratify — the gate's cost scales with the count, and
|
||||
it BLOCKs an over-broad spec outright (`agents/grounding-check.md`).
|
||||
So: state a current-behaviour claim only where the change actually
|
||||
relies on it (the gate's test: its falsity would make the change
|
||||
fail or cost additional work), and render context-only mentions of
|
||||
existing mechanisms as a design-ledger contract citation instead of
|
||||
restating their behaviour. This trims *restatements*, never *reliances*: a
|
||||
mechanism the change builds on remains an assumption — explicit, or
|
||||
the implicit form the gate extracts anyway — and writing it as a
|
||||
bare citation does not exempt it; hiding a reliance is exactly the
|
||||
failure the gate exists to catch. The same economy applies to scope:
|
||||
a tightly-cut iteration makes fewer claims than a sprawling one
|
||||
(field evidence on issue #35: gate cost tracks the spec's assumption
|
||||
count near-linearly).
|
||||
|
||||
### Step 4 — Self-review
|
||||
|
||||
Inline checklist (not a subagent dispatch):
|
||||
@@ -328,6 +366,16 @@ Inline checklist (not a subagent dispatch):
|
||||
carry before → after code for every load-bearing change (plus the
|
||||
worked user-facing example for a surface cycle)? A load-bearing
|
||||
change described only in prose is a self-review failure to fix.
|
||||
6. **Assumption economy:** scan every claim about current codebase
|
||||
behaviour. The gate's own criterion decides which stay: a claim
|
||||
is a *reliance* iff its being false would make the proposed
|
||||
change fail or require additional work
|
||||
(`agents/grounding-check.md` § What "load-bearing assumption"
|
||||
means). Non-reliances are gate cost with no return — delete
|
||||
them, or demote them to a citation that carries no behaviour
|
||||
claim. Never demote a reliance: a bare citation does not ratify
|
||||
it, and the gate BLOCKs on it unratified (Step 3's
|
||||
restatements-vs-reliances line).
|
||||
|
||||
Fix issues inline.
|
||||
|
||||
@@ -497,6 +545,7 @@ is narrow by design: only the user's-call forks bounce, not every fork.
|
||||
|-----------|---------|
|
||||
| user / issue (design settled) → `specify` | the sources: issue body, in-context design discussion, design docs |
|
||||
| `brainstorm` → `specify` | ratified design narrative (approaches chosen, constraints, sections approved) — in-context; brainstorm writes no spec file |
|
||||
| `specify` → `plan-recon` (Step 1, the cycle recon — skipped when a brainstorm-fired dispatch meets the coverage condition) | `sources` + `recon_scope` + optional `focus_hint`; defined authoritatively under **Pre-spec dispatch (cycle recon)** in `../planner/agents/plan-recon.md` |
|
||||
| `specify` → `grounding-check` (Step 5) | `spec_path` (absolute) + `iteration_scope` |
|
||||
| `specify` → `spec-skeptic` bias-breaker (Step 1.5, optional, orchestrator's call) | `spec_path` (absolute) + `iteration_scope` + one `lens` + `seeding_issue` (or `none`); dispatched ad hoc for a fork the orchestrator is deciding, never as a gate |
|
||||
| `specify` → reference issue (Step 1.5) | a derived-decision comment (rationale) or user-decision comment (provenance); a freshly created seeding issue if the cycle had none |
|
||||
@@ -515,6 +564,7 @@ is narrow by design: only the user's-call forks bounce, not every fork.
|
||||
| "The shape is clear from the prose, I don't need to paste the code" | If it's clear, pasting it is free; if pasting it is hard, it wasn't clear. The acceptance criterion is unjudgeable without the worked code. |
|
||||
| "Just polishing a wording after PASS, no need to re-dispatch" | The grounding-check report attests to specific bytes. A polish edit changes the bytes; the attestation no longer covers them. Re-dispatch is cheap. |
|
||||
| "It's in a model doc / the design ledger, so it's canonical" | A `models` / RFC / proposal doc holds aspirational code — a target, not verified fact. Flag code lifted from a `status: aspirational` source as such; it is not ratified contract. |
|
||||
| "Fewer assumptions = a cheaper grounding-check, so I'll phrase the reliances as vague citations" | Economy cuts *restatements*, not *reliances*. A mechanism the change builds on stays a claim — vague phrasing merely converts it to the implicit form the gate extracts anyway, or worse, hides a false premise until a downstream iteration BLOCKs on it. Trim what the change does not rest on; never what it does. |
|
||||
| "In `/boss` this spec looks solid — I'll sign and move on" | Your sense that it looks solid is not the signature. Under `/boss` the signature is the Step-5 `grounding-check` `PASS` — an independent agent's verdict, not your confidence. Run the grounding-check; a no-override `BLOCK` routes to the human, never auto-signed over. |
|
||||
| "A grounding `BLOCK` looks like a false alarm — I'll sign over it" | With no human in the loop there is no override. A no-override grounding `BLOCK` is the one objective denial of an autonomous sign; it routes to the human sign-off pause. The whole point of trusting grounding-PASS as the signature is that you also honour its `BLOCK`. |
|
||||
|
||||
@@ -543,6 +593,9 @@ is narrow by design: only the user's-call forks bounce, not every fork.
|
||||
- Jumping straight from spec to `implement` (must go via `planner`)
|
||||
- Running an interview here (that is `brainstorm`'s job — if the work
|
||||
needs one, bounce)
|
||||
- Grounding the spec with a broad Explore-type sweep — or a second
|
||||
full recon dispatch when a cycle recon already exists
|
||||
(`../docs/pipeline.md` § Cycle recon)
|
||||
|
||||
## Cross-references
|
||||
|
||||
@@ -566,9 +619,10 @@ is narrow by design: only the user's-call forks bounce, not every fork.
|
||||
unanimous five-lens auto-sign panel is retired (baseline tag
|
||||
`pre-autosign-rework`); the autonomous signature is now the Step-5
|
||||
`grounding-check` `PASS`.
|
||||
- **Ad-hoc dispatch.** The orchestrator MAY also ad-hoc dispatch
|
||||
`../planner/agents/plan-recon.md` during Step 1 when the work enters
|
||||
code territory not recently read; discretionary, not part of the
|
||||
standard process.
|
||||
- **Cycle recon (Step 1).** `../planner/agents/plan-recon.md` in its
|
||||
pre-spec form is the cycle's ONE full recon dispatch when the work
|
||||
enters code territory not recently read; its report also serves
|
||||
`planner` downstream. Budget, reuse conditions, and delta triggers:
|
||||
`../docs/pipeline.md` § Cycle recon.
|
||||
- **Project feature-acceptance criterion:** declared in the project's
|
||||
`CLAUDE.md`. Applied prospectively in Step 2.
|
||||
|
||||
Reference in New Issue
Block a user