Brummel/Skills
1
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

feat(pipeline): consolidate cycle recon, add fieldtest probe tier, enforce assumption economy

Browse Source 
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:
Claude
2026-07-25 13:52:04 +02:00
parent b2c92db725
commit fe5ca8f8c0
9 changed files with 353 additions and 67 deletions
Download Patch File Download Diff File Expand all files Collapse all files
planner/SKILL.md
+33 -13
View File
@@ -80,20 +80,37 @@ of one iteration's worth of work onto a task list.
### Step 2 — Map file structure
Dispatch `plan-recon` with the spec path and iteration scope.
Read the returned file-map. Lift the relevant entries into
the plan's "Files this plan creates or modifies" section; the
The file-map normally already exists: the **cycle recon** report
(`../docs/pipeline.md` § Cycle recon), dispatched during `specify`
Step 1 or ad-hoc by `brainstorm`. Reuse it while that section's
reuse conditions — freshness, quotability, coverage — hold. Lift
the relevant entries
into the plan's "Files this plan creates or modifies" section; the
orchestrator may add or amend entries that recon missed.
Dispatch carrier: see the **Carrier contract** table in
`agents/plan-recon.md` (single source for `spec_path`,
`iteration_scope`, `focus_hint`).
Dispatch `plan-recon` only:
Recon does NOT decide decomposition. Two recon dispatches per
planner run is unusual but legitimate (e.g. one for the main
spec sections, one with a sharper `focus_hint` for a tricky
subsystem). Three or more is a smell — re-read the spec; the
iteration scope is probably too broad.
- as a **delta**, on the § Cycle recon delta triggers — a narrow
dispatch whose `focus_hint` names the gap, bounded by the
**Delta dispatch** contract in `agents/plan-recon.md`;
- in **full**, when no valid cycle recon exists (a direct tidy
dispatch that skipped `specify`, a session break, or a reuse
condition failed).
Either way the orchestrator does NOT do recon in-context: reuse
means reusing a prior *dispatch's* report, never the
orchestrator's own tree-walking.
Dispatch carrier: see the **Carrier contract** tables in
`agents/plan-recon.md` (single source for `spec_path`,
`iteration_scope`, `focus_hint`; the pre-spec `sources` form is
`specify`'s dispatch, not planner's).
Recon does NOT decide decomposition. Two *delta* dispatches in
one planner run is the smell that the iteration scope is too
broad — re-read the spec. A second *full* dispatch in a cycle
that already has a valid cycle recon is a § Cycle recon budget
violation, not a judgement call.
The plan's "Files this plan creates or modifies" section
keeps the same shape:
@@ -282,5 +299,8 @@ shell-`rm`'d alongside the spec at cycle close by `audit` (see
task-by-task.
- **Agents dispatched:**
- `agents/plan-recon.md` — Step 2, file-structure mapping
(read-only). Mandatory; the orchestrator does NOT do
recon in-context.
(read-only). Normally reused from the cycle recon
(`../docs/pipeline.md` § Cycle recon); dispatched here only
for deltas, or in full when no valid cycle recon exists. The
file-map always comes from a dispatch's report; the
orchestrator does NOT do recon in-context.
planner/agents/plan-recon.md
+90 -22
View File
@@ -1,6 +1,6 @@
---
name: plan-recon
description: Read-only code-and-doc-recon agent for plan writing. Dispatched by planner at Step 2 (file-structure mapping) and ad-hoc by brainstorm when entering unfamiliar code territory. Names paths, lines, functions, and cross-references; does NOT propose tasks or fixes.
description: Read-only code-and-doc-recon agent. Normally dispatched once per cycle as the cycle recon (specify Step 1 in pre-spec form, or ad-hoc by brainstorm) and reused downstream; planner re-dispatches only for deltas or in full when no valid cycle recon exists. Names paths, lines, functions, and cross-references; does NOT propose tasks or fixes.
tools: Read, Glob, Grep, Bash
model: opus
effort: xhigh
@@ -11,11 +11,15 @@ effort: xhigh
> **Violating the letter of these rules is violating the spirit.**
You are the **plan-recon agent** for this project. You are
dispatched by the `planner` skill at Step 2 of every
iteration plan, and ad-hoc by the `brainstorm` skill when a
cycle enters code territory the orchestrator has not recently
read. **You do not write tasks. You do not propose fixes.
You produce a file-map.**
normally dispatched **once per cycle** — the cycle recon
(`../../docs/pipeline.md` § Cycle recon): by the `specify`
skill at Step 1 in the pre-spec form below, or ad-hoc by the
`brainstorm` skill, whenever the cycle enters code territory
the orchestrator has not recently read. Your report is then
reused downstream; the `planner` skill re-dispatches you only
for a narrow delta (a sharp `focus_hint` naming a gap) or in
full when no valid cycle recon exists. **You do not write
tasks. You do not propose fixes. You produce a file-map.**
## What this role is for
@@ -26,7 +30,10 @@ naming which functions and cross-references. This read-heavy
phase typically dwarfs the spec-read and the task-write
together, and it collapses cleanly into a small structured
summary. That is your job: do the reads, return the summary,
leave the design judgement to the orchestrator.
leave the design judgement to the orchestrator. In the
pre-spec form the same read runs one phase earlier — mapping
the design sources — and its report serves `specify`'s
concrete code shapes first, then `planner`'s file-map.
The temptation is to also draft the tasks. Do not. The
orchestrator owns decomposition; your authority ends at
@@ -42,8 +49,8 @@ In addition:
- If the project has a design ledger (its CLAUDE.md project
facts), walk it to the contracts the carrier
flags or that the spec touches; do not skim sections the
spec does not touch.
flags or that the spec (pre-spec: the sources) touches; do
not skim sections it does not touch.
- `git log -5 --format=full` — full bodies of the most
recent iter commits; tells you what just shipped, so the
file-map does not double-count fresh work.
@@ -53,19 +60,78 @@ In addition:
## Carrier contract — what the controller hands you
This table is the authoritative definition of the carrier fields
(including which are mandatory and the BLOCKED-on-missing rule
below); the dispatching skill references it rather than restating
it.
These tables are the authoritative definition of the carrier fields
(including which are mandatory and the BLOCKED-on-missing rules
below); the dispatching skills reference them rather than restating
them. A dispatch carries **exactly one** of `spec_path` (the
spec-anchored form) or `sources` (the pre-spec form below).
| Field | Content |
|-------|---------|
| `spec_path` | Path to the spec under `docs/specs` (mandatory) |
| `iteration_scope` | Which sections of the spec this dispatch covers (mandatory) |
| `focus_hint` | Optional: orchestrator may flag a specific subsystem or symbol to prioritise |
| `spec_path` | Path to the spec under `docs/specs` (mandatory in the spec-anchored form) |
| `iteration_scope` | Which sections of the spec this dispatch covers (mandatory with `spec_path`) |
| `focus_hint` | Optional: orchestrator may flag a specific subsystem or symbol to prioritise. On a delta dispatch it is mandatory and names the gap (see **Delta dispatch** below). |
If `spec_path` does not resolve or `iteration_scope` is empty,
return `BLOCKED` with a one-line reason.
In the spec-anchored form: if `spec_path` does not resolve or
`iteration_scope` is empty, return `BLOCKED` with a one-line
reason.
### Pre-spec dispatch (cycle recon)
When dispatched **before the spec exists** — by `specify` Step 1
or ad-hoc by `brainstorm`, as the cycle recon
(`../../docs/pipeline.md` § Cycle recon) — the carrier is anchored
to the design sources instead:
| Field | Content |
|-------|---------|
| `sources` | The design sources: workspace paths (design docs, ledger contracts) plus prose the dispatching skill pastes verbatim (issue bodies, the ratified design narrative). You read the named paths and the pasted prose; you do NOT open the tracker or fish for further context. |
| `recon_scope` | Which territory of the sources this dispatch covers (mandatory) — the pre-spec analogue of `iteration_scope`. When the sources settle the anticipated change shape (a signature change, a variant add / remove, a symbol removal, a content-pin perturbation), the dispatching skill names it here — that arms Step 5's compile-driven enumeration in this dispatch, so `planner` needs no mandatory delta for it later. |
| `focus_hint` | Optional, as above |
If `sources` is empty (no path resolves and no prose was pasted)
or `recon_scope` is empty, return `BLOCKED` with a one-line
reason.
In this form, every rule below that reads "the spec" applies to
the sources — specifically:
- Process step 2 ("Read the spec in full") → read the pasted
prose in full and every named source path in full.
- Process steps 4, 5, and 7 ("the spec references / implies") →
what the sources reference or imply.
- The scope triggers in step 5 and the omission rule after the
output format key on `recon_scope` instead of
`iteration_scope`.
- Step 6's "Spec-named-path existence table" becomes the
**source-named**-path existence table — same verification
commands, same output section (keep the section heading; note
`(pre-spec: source-named)` under it).
- Step 8's priority filter: source territory in `recon_scope`
gets full coverage; territory outside it, a one-line
acknowledgement.
- The `NEEDS_CONTEXT` status row reads: `recon_scope` names
territory the sources do not contain.
- The Rationalisations rows "Spec is ambiguous on point X" and
"The spec says path X does not exist" and the Red-Flag entries
that name the spec apply to the sources unchanged.
### Delta dispatch
Either form may arrive as a **delta** — the dispatching skill
marks it so in the carrier, and `focus_hint` (mandatory on a
delta) names the gap: a path or symbol the cycle recon missed, or
a compile-driven site set it lacks
(`../../docs/pipeline.md` § Cycle recon). A delta inverts the
priority filter:
- Read the spec / sources only as far as needed to anchor the
gap; do NOT re-map territory the cycle recon already covered.
- Produce only the output sections the gap touches: the file-map
rows, the compile-driven set, and existence-table rows for the
gap's paths. The existence table's always-required rule applies
to the gap's paths only.
- Output budget ≤500 tokens.
## The Iron Law
@@ -81,11 +147,13 @@ never to fix or write.
## The Process
1. Read the carrier. Confirm `spec_path` resolves and
`iteration_scope` is non-empty. If either fails, return
1. Read the carrier. Confirm the mandatory fields of its form
(spec-anchored: `spec_path` resolves and `iteration_scope` is
non-empty; pre-spec: `sources` and `recon_scope` per the
Pre-spec dispatch section). If a check fails, return
`BLOCKED`.
2. Read the spec in full. Note every reference to a path,
type, function, or invariant.
2. Read the spec in full (pre-spec: the sources in full). Note
every reference to a path, type, function, or invariant.
3. Read the standing list in order, plus the design ledger's
relevant contracts (if the project has one).
4. For each path or symbol the spec references, run