AILang/docs/specs/0009-plan-recon-subagent.md

# Plan-recon subagent — Design Spec

**Date:** 2026-05-11
**Status:** Draft — awaiting user spec review
**Authors:** Brummel (orchestrator) + Claude

## Goal

Reduce Boss-context cost in the `planner` skill by moving the
read-heavy file-structure-mapping phase out of the Boss and into a
dedicated read-only subagent. Leave design judgement (task
decomposition, step granularity, cross-task consistency) in the
Boss. Brainstorm remains dialog-driven and gets no dedicated agent;
it can dispatch the same recon agent ad-hoc when needed.

The orchestrator-refactor milestone (`or.1`, 2026-05-11) showed that
splitting the per-task review loop into a sub-context pays back in
Boss-token budget. The same principle applies here, but more
narrowly: only the recon phase is delegated, because that is the
only phase whose output collapses cleanly into a small structured
summary.

## Architecture

Today, both `brainstorm` and `planner` run entirely in the Boss
context. Reading the per-skill SKILL.md files makes the breakdown
explicit:

- `brainstorm` is dialog-driven across nine steps. Steps 1 (project
  context), 6 (write spec), and 7 (self-review) carry Read/Write
  volume; everything else is user Q&A or trivial.
- `planner` is dialog-light but read- and write-heavy. Step 2 (file
  structure mapping) and Step 3 (write tasks) carry the volume.

Of those phases, only one has the right shape for a subagent:

| Phase | Why it does (not) delegate |
|---|---|
| brainstorm Step 1 — project context | Read volume is moderate; what is relevant becomes clear only mid-dialogue. A subagent dispatched once-and-for-all operates on a partial picture and re-reads what the Boss must read anyway to lead Q&A. |
| brainstorm Step 6 — write spec | Spec writing is dialog kondensation. The Boss has the live conversation; handing it to a subagent means handing over the transcript, not saving tokens. |
| planner Step 2 — file structure mapping | Read-heavy (5–15k Boss tokens on a typical milestone), produces a compact structured summary (~500 tokens). High delegation ratio. Decomposition-independent: the Boss can run Steps 3–8 on the recon's output. |
| planner Step 3 — write tasks | Task decomposition IS the design work. Not delegable; the Boss must hold the cross-task picture to keep types, paths, and step granularity consistent. |

This spec ships one new subagent — `ailang-plan-recon` — and one
SKILL.md edit (`planner` Step 2). Nothing about `brainstorm` ships.

## Components

### `skills/planner/agents/ailang-plan-recon.md` (NEW)

Read-only code-and-doc-recon agent. The agent's job is: take the
parent spec and an iteration scope, walk the codebase, and return a
file-map that names every existing path, line range, function, and
type the iteration will touch, plus any anchors that DO NOT yet
exist but the spec implies.

| Field | Value |
|---|---|
| Tools | `Read, Glob, Grep, Bash` (Bash for read-only inspection — `git log`, `git grep`; never to edit) |
| Dispatched by | `planner` (primary); `brainstorm` ad-hoc when a milestone enters unfamiliar code territory |
| Carrier | `spec_path` (mandatory), `iteration_scope` (mandatory — which sections of the spec this dispatch covers), `focus_hint` (optional — e.g. "trace ctor lookup", "find all `Pattern::Lit` sites") |
| Output | Structured Markdown block, ≤1500 tokens (see "Output format" below) |
| Status protocol | `DONE` / `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED` |

#### Iron Law

```
NO PLAN WRITING. NO TASK DECOMPOSITION. NO STEP TEXT.
NAMES PATHS, LINES, FUNCTIONS, AND ANCHORS — NOT THE FIX.
NO EDITS. NOT TO CODE, NOT TO DOCS.
```

The boundary mirrors `ailang-architect`: the agent diagnoses where
work lands, the controller decides what to do with it.

#### Standing reading list

1. `CLAUDE.md` — orchestrator framing.
2. `docs/DESIGN.md` — invariants the iteration must preserve.
3. `docs/journals/INDEX.md` and the latest entries — what just
   shipped, so the recon doesn't double-count fresh work.
4. `skills/planner/SKILL.md` — the role the recon serves.

The agent does NOT open `docs/plans/`; plan files are the
*output* downstream of recon, not its input.

#### Output format

```markdown
## Files

### Create
- `<path>` — <one-line responsibility>

### Modify
- `<path>:<line range>` — <one-line site description>
  - relevant function: `<fn name>` at `<path>:<line>`
  - cross-reference: `<other path>:<line>` (lockstep partner)

### Anchors not yet present
- `<path>` — <what the spec implies must be added but does not exist today>

## Cross-references

Any lockstep-invariant pairs (e.g. `Pattern::Lit::*` typecheck ↔
pre-desugar walker) that the iteration is likely to touch. Walk
the pairs listed in `ailang-architect`'s reading list as a starting
point.

## Open questions

Things the spec implies but the code state cannot answer alone —
flag for Boss judgement, do not invent an answer.

## Status

`DONE` | `DONE_WITH_CONCERNS` | `NEEDS_CONTEXT` | `BLOCKED` (with one-line reason)
```

#### Common Rationalisations

| Excuse | Reality |
|---|---|
| "While I'm here, let me sketch what the task would look like" | That is plan writing. Stop at the file-map; the Boss decomposes. |
| "I'll just suggest the fix in the cross-references" | A suggestion biases the Boss's design space. Name the site, not the fix. |
| "The spec is ambiguous on this point, I'll pick the obvious reading" | `NEEDS_CONTEXT` with a one-line carrier-clarification request. The Boss decides. |
| "Code search returns nothing for X, so X isn't in scope" | List X under "Anchors not yet present" with a one-line note. Absence is signal. |

#### Red Flags — STOP

- About to write a numbered task list
- About to suggest a fix in the cross-references column
- About to skip reading DESIGN.md because "I know that part"
- About to return a file-map without line ranges
- About to invent a line number you did not verify

### `skills/planner/SKILL.md` (MODIFIED)

Step 2 is replaced. The new Step 2 reads:

> ### Step 2 — Map file structure
>
> Dispatch `ailang-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 Boss may add or amend entries that recon missed.
>
> 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.

The rest of the SKILL.md (Steps 1, 3–6, Iron Law, Handoff Contract,
Common Rationalisations) is unchanged in scope, but the "No private
agents" line in Cross-references is replaced with a one-line
reference to the new agent.

### `skills/brainstorm/SKILL.md` (MODIFIED, one paragraph)

A note in the "Cross-references" section: although `brainstorm`
itself has no private agents, the Boss may ad-hoc dispatch
`ailang-plan-recon` during Step 1 (project context) when the
milestone enters code territory the Boss has not recently read.
This is opt-in, not part of the standard process, and is documented
under "Cross-references" rather than as a step.

### `skills/README.md` (MODIFIED)

One new row in the agent roster:

```
| ailang-plan-recon | planner/agents/ | planner (primary); brainstorm (ad-hoc) |
```

The "Agents do not call other agents — one named exception" line
remains: ad-hoc dispatch from `brainstorm` is the Boss dispatching
the agent, not an agent calling another agent.

### `.claude/agents/planner` (NEW symlink)

```
.claude/agents/planner -> skills/planner/agents
```

Mirrors the existing `.claude/agents/{implement,audit,fieldtest,debug}`
pattern. Required so `subagent_type: ailang-plan-recon` resolves
during dispatch.

## Data flow

```
planner Step 1: Boss reads spec
                      |
                      v
planner Step 2: Boss dispatches ailang-plan-recon
                with { spec_path, iteration_scope, focus_hint? }
                      |
                      v (file-map, <=1500 tokens)
planner Step 2: Boss lifts file-map into plan's
                "Files this plan creates or modifies"
                section, augments if needed
                      |
                      v
planner Steps 3-8: unchanged (task writing, header,
                   self-review, commit, handoff)
```

For ad-hoc dispatch from `brainstorm`, the Boss reads the file-map
into the Q&A flow but never writes a plan; the file-map informs
the design dialog and is discarded at hand-off to `planner`.

## Error handling

The agent's BLOCKED conditions:

| Condition | Carrier-level resolution |
|---|---|
| `spec_path` does not resolve | Boss fixes the path and re-dispatches. |
| `iteration_scope` is ambiguous (names a section the spec doesn't have) | Boss reframes the carrier with a precise section reference. |
| Code search returns zero candidates for a feature the spec describes | Recon returns `DONE_WITH_CONCERNS` with the absence flagged under "Anchors not yet present". Boss decides: (a) spec gap → bounce to `brainstorm`, or (b) feature is genuinely new and the spec is correct. |
| Required reading list is unreadable (DESIGN.md missing) | Recon returns `infra_blocked`. Boss fixes the working directory. |

The Boss never papers over a `BLOCKED`/`NEEDS_CONTEXT` recon by
hand-coding the file-map. That collapses the discipline.

## Testing strategy

This is a skill-system change, not a language change, so testing is
the verification-ladder pattern used by the `or.1` orchestrator-agent
spec: the first dispatches in real use are the test.

1. **First planner dispatch.** A next-iter planner run (e.g. one of
   the P2 roadmap items) is executed with the new agent in place.
   Confirm: the file-map produced by recon names every path the
   final plan ends up creating or modifying.
2. **Token-budget delta.** End-of-session Boss-context size compared
   informally against the previous planner sessions (`ct.1`, `ct.4`,
   `or.1`). Goal: visible reduction, not a precise number.
3. **Plan-quality preservation.** The plan that comes out of the
   first dispatch passes `implement` spec-review on Task 1 without
   raising a `non_compliant` on missing paths or stale line numbers.
4. **BLOCKED handling exercise.** When a recon dispatch organically
   blocks (spec gap, ambiguous scope), the Boss handles it via
   carrier-clarification rather than papering over.
5. **Ad-hoc brainstorm dispatch.** First brainstorm session in
   unfamiliar territory after this lands tries the ad-hoc dispatch;
   confirm the agent works untouched in that context.

Steps 1–3 should land within the next 2–3 planner runs. Steps 4–5
get checked off when those conditions arise organically.

## Acceptance criteria

- `skills/planner/agents/ailang-plan-recon.md` exists with the
  template specified in **Components**.
- `skills/planner/SKILL.md` Step 2 dispatches the new agent.
- `skills/brainstorm/SKILL.md` Cross-references section names the
  ad-hoc dispatch option.
- `skills/README.md` agent roster lists the new agent.
- `.claude/agents/planner` symlink exists.
- A real planner dispatch using the agent has run, and the
  verification-ladder steps 1–3 are recorded in the iter journal.

## Out of scope

- **Brainstorm subagents.** Rationale: dialog-driven, recon is
  interwoven with Q&A. Revisit only if the ad-hoc dispatch pattern
  proves insufficient.
- **Plan-writer subagent.** Rationale: task decomposition is the
  design work; delegating it would defeat the point of the planner
  skill. The Boss writes tasks.
- **Plan-reviewer subagent.** Rationale: today's inline self-review
  (Step 5 of `planner`) works. The implement-side spec-reviewer is
  the downstream gate. Adding a third reviewer would be
  defensive-programming for a problem we don't have. Revisit if a
  shipped plan ever passes self-review but fails implement
  spec-review on Task 1 paths.
- **Recon-writeup subagent for `brainstorm` Step 6.** Rationale:
  Step 6 is dialog kondensation; the Boss has the live transcript.

## Rationale: why brainstorm doesn't get its own dedicated agent

Three substantive reasons, in order of weight:

1. **Recon and dialogue are interwoven.** brainstorm Step 1 names
   the project state in advance, but Step 2's Q&A reshapes which
   parts of that state matter. A subagent dispatched at Step 1
   reads the surface; the Boss then has to re-read the parts the
   user's answers focused on. Net: more total reads, not fewer.

2. **The Boss must hold the project state to lead Q&A.** Even if a
   subagent pre-digested DESIGN.md, the Boss cannot ask informed
   follow-up questions without holding the same context. Delegation
   here doubles the read budget rather than replacing it.

3. **Spec writing is dialog kondensation.** Step 6 produces the
   spec from the live dialogue. A subagent would need the full
   transcript handed to it — the very token volume we are trying
   to keep out of the Boss context. The Boss is the natural
   condenser because the Boss is the dialogue partner.

The asymmetry with `planner`: the planner has a phase where the
input (spec) is fixed and the output (file-map) is small and
structured. `brainstorm` has no such phase. The recon agent's
shape fits the former and not the latter.

## Naming + home

The agent lives at `skills/planner/agents/ailang-plan-recon.md`
because `planner` is the primary dispatcher. Ad-hoc dispatch from
`brainstorm` is the Boss's call, not a skill→agent transition; it
does NOT violate the "no orphan agents" rule, since `planner` is the
formal owner.

The name `ailang-plan-recon` is preferred over `ailang-code-recon`
because:
- It anchors the agent to its primary skill, matching the rest of
  the roster (`ailang-implementer`, `ailang-architect`, etc.).
- It signals "for a planner dispatch" — which informs the carrier
  format and the output shape.
- "code-recon" would suggest a general-purpose code-reading utility
  that other agents might call; that direction is explicitly out of
  scope (see "Agents do not call other agents" in `skills/README.md`).