Fanout

Dispatch the same query to multiple subagents in parallel, each processing one chunk from a chunk manifest. Aggregates results with source provenance — every answer is tagged with which chunk it came from.

Triggers

Alternate expressions and non-obvious activations:

"search all chunks" → fanout query across manifest
"run in parallel across the chunks" → fanout with current manifest
"ask each piece this question" → fanout with default parallelism
"parallel grep" → fanout with a pattern as the query

Trigger Patterns Reference

Pattern	Example	Action
Fanout search	"search all chunks for authentication bugs"	Fanout query across manifest
Explicit chunks dir	"fanout across .aiwg/rlm-chunks/auth/"	`--chunks .aiwg/rlm-chunks/auth/`
Limit parallelism	"search chunks, max 2 at a time"	`--max-parallel 2`
Synthesis request	"search all chunks and give me one answer"	`--synthesize`
Model selection	"use haiku to search the chunks"	`--model haiku`
Manifest path	"fanout using manifest.json"	`--chunks manifest.json`

Behavior

When triggered:

Parse arguments — extract query, chunks path (directory or manifest), parallelism limit, model, and synthesis flag.
Load manifest — read manifest.json from the chunks directory, or use the provided manifest path directly. Validate that chunk files exist.
Respect context budget — if AIWG_CONTEXT_WINDOW is set, cap --max-parallel at the budget-appropriate limit per the context-budget rule. Default cap is 4 parallel subagents.
Dispatch subagents — launch up to --max-parallel subagents simultaneously. Each subagent:
- Receives the query and exactly one chunk's content
- Is instructed to answer only from that chunk's content
- Returns a structured result: { chunk_id, answer, confidence, relevant_lines }
Wait for all subagents — collect results as they complete. Track which chunks returned answers vs. "not found in this chunk".
Aggregate with provenance — compile results into a provenance-tagged list. Each entry shows:
- The answer or finding
- The chunk it came from (chunk-0003)
- The source lines within that chunk
- Confidence level (high / medium / low)
Optionally synthesize — if --synthesize is set, pass all results to a synthesis subagent that merges them into a single coherent answer.
Report result — print the aggregated findings with provenance, or the synthesized answer.

Aggregated Result Format

Fanout Query: "Where is the token refresh logic?"
Chunks searched: 8  |  Matches found: 3  |  Model: haiku

Matches:
  [chunk-0002] lines 45-67 — HIGH confidence
    Token refresh is handled in `AuthMiddleware.refreshToken()`.
    The method checks expiry, calls `/auth/refresh`, and updates the
    session cookie on success.

  [chunk-0005] lines 112-118 — MEDIUM confidence
    `refreshToken()` is called from the React hook `useSession`
    when the access token has less than 60 seconds remaining.

  [chunk-0007] lines 203-208 — LOW confidence
    Environment variable REFRESH_INTERVAL_MS controls refresh
    frequency. Default: 300000 (5 minutes).

Chunks with no match: chunk-0001, chunk-0003, chunk-0004, chunk-0006, chunk-0008

Synthesized Result Format (--synthesize)

Fanout Query: "Where is the token refresh logic?"
Synthesis from 3 matching chunks:

Token refresh is implemented in `AuthMiddleware.refreshToken()` (chunk-0002,
lines 45-67). The React layer triggers refresh via the `useSession` hook when
the access token has less than 60 seconds remaining (chunk-0005, lines 112-118).
Refresh interval is configurable via REFRESH_INTERVAL_MS (default: 5 minutes,
chunk-0007, lines 203-208).

Parameters

<query> — Natural language question or task to answer using the chunks (required)
--chunks <dir|manifest.json> — Path to chunks directory or manifest file (default: .aiwg/rlm-chunks/)
--max-parallel N — Max simultaneously active subagents (default: 4, bounded by context budget). Alias --parallel is accepted for one release cycle and emits a deprecation warning; remove it after the next stable release.
--model haiku|sonnet|opus — Model for subagents (default: haiku for cost efficiency)
--synthesize — After collecting results, synthesize into a single answer

Examples

Example 1: Basic fanout search

User: "fanout search across the auth chunks: where is token expiry checked?"

Action: Dispatch query to each chunk in .aiwg/rlm-chunks/auth/, 4 parallel subagents using haiku.

Response:

Fanout Query: "where is token expiry checked?"
Chunks searched: 6  |  Matches found: 2  |  Model: haiku

Matches:
  [chunk-0002] lines 88-95 — HIGH confidence
    Token expiry is checked in `validateToken()` by comparing
    `token.exp` against `Date.now() / 1000`.

  [chunk-0004] lines 31-38 — MEDIUM confidence
    JWT middleware also checks expiry via the `express-jwt`
    `credentialsRequired` option, which rejects expired tokens
    before reaching route handlers.

Chunks with no match: chunk-0001, chunk-0003, chunk-0005, chunk-0006

Example 2: Synthesized answer

User: "search all chunks for how errors are logged, and give me one answer"

Action:

aiwg fanout "how are errors logged?" --chunks .aiwg/rlm-chunks/api/ --synthesize

Response:

Synthesis from 4 matching chunks:

Errors are logged through three mechanisms: (1) the `logger.error()` wrapper
in `src/utils/logger.ts` formats structured JSON logs with request ID and stack
trace (chunk-0001, lines 12-28); (2) unhandled exceptions are caught by the
Express error handler in `src/middleware/error.ts` and forwarded to the logger
(chunk-0003, lines 55-71); (3) async errors in service classes use the
`@LogError` decorator (chunk-0006, lines 9-18).

Example 3: Budget-constrained fanout

User: "parallel search the chunks but only 2 at a time — system is under load"

Action:

aiwg fanout "find all database connection setup" --chunks .aiwg/rlm-chunks/services/ --max-parallel 2

Response: Runs subagents in batches of 2. Reports matches with provenance after all 9 chunks are processed.

Example 4: Expensive query on a large chunk set

User: "fanout across all the migration chunks using sonnet — I need precise SQL analysis"

Action:

aiwg fanout "find any ALTER TABLE statements that drop columns" \
  --chunks .aiwg/rlm-chunks/migrations/ \
  --model sonnet \
  --synthesize

Response: Dispatches sonnet subagents, synthesizes findings with exact line references.

Clarification Prompts

If the user's intent is ambiguous:

"Which chunks directory should I search? (found: .aiwg/rlm-chunks/)"
"Should I synthesize the results into one answer, or list all matches with provenance?"
"How many parallel subagents? Default is 4 (use --max-parallel N to override)."

References

@$AIWG_ROOT/agentic/code/addons/rlm/skills/chunk/SKILL.md — Produce the chunk manifest fanout reads
@$AIWG_ROOT/agentic/code/addons/rlm/skills/rlm-search/SKILL.md — Full pipeline (prep + fanout + synthesize)
@$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/context-budget.md — Parallel budget constraints
@$AIWG_ROOT/agentic/code/addons/aiwg-utils/rules/subagent-scoping.md — Subagent isolation rules
@$AIWG_ROOT/agentic/code/addons/rlm/schemas/rlm-chunk-manifest.yaml — Manifest schema