Freeze the moving cross-boundary state a system depends on into one immutable snapshot. The consumer is the agent stages (intent / shape / delegate / builder), not the human's memory — grounding, not narration.
Contract
- INPUT — a system to ground AND the work order (intent) that scopes which external facts matter. Doubly scoped: only the slice of the world this work order touches, never a general map.
- GATE — "Is the snapshot factual and complete — every required fact observed, or an explicit gap?" Agent audits, user locks.
- OUTPUT — a snapshot VALUE, emitted in conversation. Stateless: nothing persisted. Re-run to refresh.
Observed-or-gap, never inference
A fact's VALUE is OBSERVED or it is a GAP. There is no third path.
- Inference builds the source map only — reasoning enumerates WHICH facts this system + intent depends on. It never produces a fact's value.
- A value is observed — a read-only acquisition agent sees it live, or the human retrieves it by hand.
- WRONG: infer a value from a config file, a stale doc, or "it's probably still X" and write it as a fact.
- RIGHT: unreachable fact → an OPEN gap with retrieval instructions, never a fabricated value.
The outcome is a uniformly factual snapshot: every line is something observed, or something named as missing.
The snapshot
Two parts. Facts append; the belief derives.
- OBSERVED facts — each
{ source, claim, where-it-lives, as-of, observed-by }. - OPEN gaps — each
{ required-fact, why-needed, where-to-look, how-to-retrieve }. - Derived view — any map / belief over the facts is a VIEW, marked as derived, never mixed into the observed set. A consuming stage sees a complete factual picture or exactly which facts are still missing.
The work loop
- Scope — from the system + intent, infer the source map: the set of external facts this work order depends on. This is the only place inference runs.
- Acquire — fan out read-only acquisition agents in parallel, one observation per fact, live. The skill spawns and folds; it never does the reads itself.
- Fold — assemble each return into an OBSERVED fact. Anything unobserved becomes an OPEN gap with its retrieval instructions.
- Gap-fill — surface gaps for the human to hand-retrieve; re-fold each return. Re-check. The loop terminates when no gaps remain OR the human stops.
- Gate — run the gate audit (below).
Acquisition is delegation-shaped
The skill is a router: it spawns acquisition agents and folds their returns. It does not read external systems directly — same law as delegate's "router does no work".
- READ-ONLY is a hard guard — acquisition agents observe, never mutate. No write, no POST that changes state, no migration, no toggle. An agent that would mutate an external system is the wrong tool; stop and make it a gap for the human.
- Parallel by default — independent facts go out as parallel agent calls in one message.
- Self-contained prompts — each agent gets the one fact to observe, where it lives, and the read-only constraint.
Decision prompts
<!-- doc-gen FILE src=../prompts.md -->- Auto-gather when the answer is retrievable with certainty: cheap local reads, docs, web research, parallel subagents. Return with decisions, not raw findings. Never ask the user something research already made obvious — that is a named stop condition.
- Only non-obvious judgment calls reach the user. Every such AskUserQuestion: exactly 3 candidate answers + 1 uniform escape hatch — "Gather facts" (research/explore). The hatch is a first-class option, never hidden behind Other.
- Re-entry after a detour: if the detour made the answer obvious, state the decision and proceed; otherwise re-ask the same question with the new evidence inside the prompt.
- Presentation rule: EVERYTHING the user needs to answer lives inside the question UI — question text, descriptions, previews. Never in prose before the tool call (the dialog hides it).
The gate
"Is the snapshot factual and complete?" Agent audits, user locks.
- Factual pass — every OBSERVED fact traces to an observation (an agent return or a human hand-retrieval). Any value reached by inference is a defect: demote it to an OPEN gap or re-acquire it.
- Completeness pass — every fact in the source map is either OBSERVED or an OPEN gap. A required fact that is silently absent is the failure mode; name it as a gap.
- Present verdict-FIRST via AskUserQuestion: PASSES or FAILS, then the observed count and the open gaps — proof both passes ran.
- On FAIL: name exactly which facts are inferred or missing. Never fabricate a value to close a gap.
- The user locks. The lock is theirs, not yours.
Convergence
The gap-fill cycle (observe → surface gaps → human hand-retrieves → re-fold → recheck) is human-gated, not autonomous. It has no metric and no unsupervised run, so it does NOT pass through target. It ends when gaps are closed or the human stops — a snapshot with named open gaps is a valid lock.
Boundaries
- On-demand, not mandatory — any stage invokes freeze when it meets outside-the-repo facts. It is not a pre-intent stage; repo-local work skips it entirely.
- freeze vs over — freeze is world→pipeline grounding: acquire external facts, feed the agent stages. over is output→human handoff. Complements, never folded together.