dispatch-agent

Epistemic Agent Dispatch

Spawn subagents that inherit relevant knowledge from Cortex.

Without this skill, subagents arrive blank — they repeat mistakes, miss known dead-ends, and lack domain context. With it, they inherit findings, dead-ends, anti-patterns, and governance rules from the parent's epistemic state.

---

How to Use

Before spawning an Agent tool call, run this skill to enrich the prompt.

/dispatch-agent "Refactor handle_foo to reduce complexity"

Or invoke automatically when you're about to dispatch an agent for non-trivial work.

---

Step 1: Query Cortex for Inherited Context

Use the task description to query Cortex for relevant epistemic artifacts:

mcp__cortex__investigate({
  "query": "<task description>",
  "limit": 10
})

If Cortex is unavailable, fall back to local Empirica CLI:

empirica project-search --task "<task description>" --global --output json

Step 2: Categorize Results

From the Cortex/search results, extract and categorize:

Filtering Rules

• Dead-ends: Include ALL that match (similarity > 0.5). These are the highest-value inheritance — preventing a subagent from wasting time on known failures.
• Findings: Include top 5 by relevance. Too many overwhelm the context.
• Decisions: Include only those affecting the specific files/domain.
• Anti-patterns: Extract from dead-ends and mistakes. Format as "DO NOT: ..."

Step 3: Build the Dispatch Schema

Construct the enriched agent prompt with this structure:

## Inherited Epistemic Context

Your parent agent has relevant knowledge for this task. Study this before starting.

### Dead-Ends (DO NOT repeat these)
{{for each dead-end}}
- **Approach:** {{approach}}
  **Why it failed:** {{why_failed}}
{{end}}

### Relevant Findings
{{for each finding}}
- {{finding}} (impact: {{impact}})
{{end}}

### Architectural Decisions in Effect
{{for each decision}}
- **Choice:** {{choice}}
  **Rationale:** {{rationale}}
{{end}}

### Anti-Patterns (AVOID these)
{{for each anti-pattern}}
- DO NOT: {{pattern}}
{{end}}

### Governance
- Run tests after EACH file modification (not after batching)
- Verify extracted helpers receive all needed variables as parameters
- Commit only after tests pass

---

## Your Task

{{original task description}}

Step 4: Dispatch with the Agent Tool

Use the Agent tool with the enriched prompt:

Agent({
  "description": "{{short 3-5 word description}}",
  "prompt": "{{enriched prompt from Step 3}}",
  "subagent_type": "general-purpose",
  "run_in_background": true  // or false if you need results immediately
})

Step 5: Review Before Launch

Before executing the Agent tool call, present the dispatch payload to the user:

Dispatching agent: {{description}} Inherited context: {{N}} dead-ends, {{N}} findings, {{N}} decisions Governance: {{key rules}}

Proceed?

On high-autonomy tasks, skip the review. On sensitive tasks, wait for confirmation.

---

Example: Code Refactoring Dispatch

Task: "Refactor handle_session_commands to reduce C901 complexity"

Cortex query returns:

• Dead-end: "CLI handler Tier C agent created parameterless helpers — scope bugs in 20+ files"
• Finding: "Pattern: extract sequential stages into helpers, pass all variables as parameters"
• Decision: "Helpers in SAME file, defined BEFORE the function they serve"

Enriched prompt:

## Inherited Epistemic Context

### Dead-Ends (DO NOT repeat these)
- **Approach:** Batch refactoring 35 functions across 12 files with automated extraction
  **Why it failed:** Created parameterless helpers referencing outer-scope variables. 20+ files broken.

### Relevant Findings
- Extract sequential stages into helper functions, main becomes orchestrator (impact: 0.8)
- Each helper must receive ALL referenced variables as parameters (impact: 0.7)

### Anti-Patterns (AVOID these)
- DO NOT extract helpers without passing variables they reference as parameters
- DO NOT batch more than 3-4 files per agent — verify each with tests
- DO NOT create recursive helper chains (_helper_helper_helper)

### Governance
- Run `python3 -m pytest tests/ -x -q --tb=short` after EACH file
- Target CC < 15 for main functions
- No behavior changes — pure structural refactoring

---

## Your Task

Refactor all C901 violations in empirica/cli/command_handlers/session_commands.py.
For each function over CC 15, extract the biggest conditional block into a helper.
Helpers go in the same file, defined before the function they serve.

---

Cortex Unavailable Fallback

If Cortex MCP is not connected, use local Empirica search:

# Search for relevant dead-ends
empirica project-search --task "<description>" --global --output json 2>/dev/null

# Get recent dead-ends directly
empirica deadend-log --list --output json 2>/dev/null | head -20

# Get recent findings
empirica finding-log --list --output json 2>/dev/null | head -20

Format the results the same way as the Cortex path.

---

Why This Matters

Without inherited context, subagents:

• Repeat known dead-ends (wasting time and tokens)
• Violate established patterns (creating inconsistency)
• Miss anti-patterns (introducing bugs the parent already learned to avoid)
• Lack governance (no test discipline, no verification)

With inherited context, subagents:

• Skip known failures immediately
• Follow established patterns
• Avoid known pitfalls
• Verify their work before claiming completion

The quality difference is measurable — the same C901 refactoring task succeeded cleanly with context-aware agents (core/data batch) and failed destructively without it (CLI handler batch). Same task, same pattern, different outcome. The variable was inherited knowledge.