PATTERN Cited by 1 source

Phase-gated investigation progression¶

Intent¶

Gate a long-running agent loop's behaviour on explicit named phases (e.g. discovery → trace → conclude) rather than encoding the multi-step methodology in a single prompt. Each phase has its own:

Behaviour (who gets queried, how, with what question).
Model-parameter envelope (tier, token budget, tool surface).
Output schema for the phase's primary artifact.

Phase transitions are decided by a distinguished meta-phase invocation — a separate model call whose whole job is "given the investigation so far, what phase should we be in next?"

Canonicalised by Slack's Security Engineering team in their Streamlining security investigations with agents post (Source: sources/2025-12-01-slack-streamlining-security-investigations-with-agents).

Slack's three phases + meta-phase (Spear)¶

Phase	Behaviour	Director's task
Discovery	Broadcast one question to all Experts	Exhaust data-source coverage
Director Decision (meta-phase)	No Experts queried; Director decides phase transition	Advance or remain
Trace	Direct question to one specific Expert; may vary model parameters per phase	Focus on most-productive Experts
Conclude	Produce final report	Wrap up

Slack verbatim:

"Investigations begin in the discovery phase. After each round of investigation the Director decides whether to remain in the current phase or to progress to a new phase."

"Director Decision: A 'meta-phase' in which the Director decides whether to advance to the next investigation phase or continue in the current one. The task's prompt includes advice on when to advance to each phase."

"We also have the flexibility to vary the model invocation parameters by phase, allowing us to use a different model or enhanced token budget."

(Source: sources/2025-12-01-slack-streamlining-security-investigations-with-agents)

Loop shape¶

┌───────── Round k ───────────────────────────────────────────┐
│  Director forms question (phase-appropriate)                │
│                 │                                            │
│                 ▼                                            │
│          Phase-specific execution                            │
│           ┌──────────────────┐                               │
│   Disc.:  │ broadcast to all │                               │
│   Trace:  │ ask one expert   │                               │
│           └──────────────────┘                               │
│                 │                                            │
│                 ▼                                            │
│          Findings → Critic → condensed timeline              │
│                 │                                            │
│                 ▼                                            │
│     ┌────────────────────────────────┐                       │
│     │ Director-Decision meta-phase:  │                       │
│     │ advance phase? stay? conclude? │                       │
│     └────────────────────────────────┘                       │
│                 │                                            │
│      if same phase ─► next round                             │
│      if advance    ─► set phase, next round                  │
│      if conclude   ─► produce report, end                    │
└──────────────────────────────────────────────────────────────┘

Mechanism¶

1. Phase as application state¶

Phase is stored in the investigation's durable state, not in the prompt. At round start, the orchestrator reads the phase, selects the phase-specific prompt and parameters, and dispatches.

2. Meta-phase as separate invocation¶

Transition logic is its own model call, not a bullet in another task's prompt. Inputs: condensed timeline, journal, current phase. Output: { phase: "…", rationale: "…" } (schema-constrained).

Why this matters: encoding "decide whether to continue or advance" as an afterthought in the Director's question- generation prompt reintroduces the prompt-is-control failure mode. Separating the meta-phase call keeps control explicit and debuggable.

3. Phase-specific model parameters¶

Each phase has its own envelope:

discovery: {
  model: "cheap_fast",
  token_budget: "medium",
  question_broadcast: true
}

trace: {
  model: "bigger",             # Slack: "use a different model"
  token_budget: "higher",      # Slack: "enhanced token budget"
  question_broadcast: false
}

conclude: {
  model: "top_tier",
  token_budget: "largest",
  output_schema: ReportSchema
}

The knobs let the system spend more on focused phases and less on exhaustive ones, or vice versa.

4. Phase transitions in the event stream¶

Every phase transition is an event (persisted + visible in the Dashboard — see patterns/hub-worker-dashboard-agent-service). Operators can filter investigation history by phase, compute per-phase duration distributions, and correlate phase length with outcome quality.

Why gate on phases¶

Decouples control-flow from prompts. See concepts/prompt-is-not-control. Phases put structure where prompt narrative used to live.
Makes termination decidable. A meta-phase explicitly answers "are we done?" instead of letting the agent decide mid-generation.
Enables per-phase tuning. Model tier, token budget, tool surface, output schema all become phase knobs.
Supports replay + debugging. Phase transitions are first-class events; reviewing a bad investigation starts with "what phase did we get stuck in?"
Makes the investigation legible to humans. An on-call engineer supervising via the Dashboard can glance at the current phase and know what kind of progress to expect.

When to reach for it¶

Long-running agent loops (multi-round, minutes-to-hours).
Distinct stages in the task shape — exploration vs focus vs wrap-up, or triage vs root-cause vs remediation.
Stages have different cost/quality profiles — different model tier or token budget needed.
Termination is decision-dependent — you need an explicit "should we conclude?" check, not a fixed round-count.

When not to reach for it¶

Task is single-stage. No meaningful phases → no gain from pretending there are.
Task is very short. Overhead of meta-phase invocations per round dominates when rounds are cheap.
Stages lack distinct model-parameter needs. If every phase would use the same model + budget + tools, the phase distinction has only naming value.

Composes with¶

patterns/director-expert-critic-investigation-loop — the Director is the natural owner of phase-progression decisions.
patterns/one-model-invocation-per-task — the meta- phase itself is a canonical per-task invocation.
patterns/hub-worker-dashboard-agent-service — phase transitions are first-class events in the Hub's event stream.
concepts/knowledge-pyramid-model-tiering — phase parameters are the knob for tier-aware cost management.

Contrasts¶

vs. patterns/state-machine-as-query-lifecycle-manager (Oxla query lifecycle) — Oxla's pattern is a fully deterministic state machine for a single query's lifecycle; phase-gated investigation is a semi-formal state machine where the transition function is an LLM meta-phase invocation advised by prompt text. Same structural intent, different rigour.
vs. workflow engines (Temporal) — a workflow engine pre-declares the DAG; phase-gated investigation lets the Director choose transitions at runtime. Closer to a workflow engine than a freeform agent loop, but not identical.
vs. ReAct — ReAct mixes planning and execution in one loop; phase-gating separates "decide what phase to be in" from "execute within the phase."

Tradeoffs¶

Meta-phase invocation cost — one extra model call per round. Small if the meta-phase uses a cheap model on a condensed input.
Phase count is a design choice — Slack uses three + one meta-phase; the right number is task-dependent.
Mis-timed transitions still happen — the meta-phase is an LLM, not a formal verifier. Premature conclude or infinite discovery remain failure modes; mitigate with bounded round counts + operator review.
Phase bleed-over — work that naturally spans phases (e.g. a finding discovered in discovery that should drive trace questions) requires explicit state handoff via the Director's journal, not prompt narrative.

Seen in¶

systems/slack-spear — canonical first wiki instance. Three phases (discovery, trace, conclude) + one meta-phase (Director Decision). Per-phase model parameters + token budgets explicitly disclosed. Phase advancement is the Director's explicit responsibility. (Source: sources/2025-12-01-slack-streamlining-security-investigations-with-agents)