shynlee04/hivemind-plugin/delegation-intelligence

Delegation Intelligence

⚠️ PRIORITY: SEQUENTIAL IS SAFER

Default to SEQUENTIAL delegation unless ALL of these conditions are met:

1. ✅ Tasks have ZERO file overlap (different directories)
2. ✅ Tasks have ZERO state dependency (no shared variables)
3. ✅ Tasks have ZERO output dependency (no task needs another's result)
4. ✅ Failure of one task does NOT block others

When in doubt → SEQUENTIAL

Integration with Context-First Gatekeeping

Before ANY delegation, load and apply:

skill("context-first-gatekeeping")

This ensures:

• Hierarchy chain is unbroken
• Planning is retrieved from memory
• Domain boundaries are respected

Result Awaiting (MANDATORY for Sequential)

When using sequential delegation, you MUST:

1. AWAIT the result before proceeding
2. PROCESS the outcome (success/partial/failure)
3. RETUNE the plan based on actual results
4. REROUTE if domain boundaries crossed
5. EXPORT intelligence via export_cycle

// CORRECT - Sequential with result awaiting
const result = await task({ ... })
if (result.outcome === "success") {
  export_cycle({ outcome: "success", findings: result.findings })
  // Proceed to next task
} else if (result.outcome === "partial") {
  // RETUNE: Adjust based on partial progress
  save_mem({ shelf: "partial", content: result.findings })
  // Decide: continue or reroute?
} else {
  // STOP - Do not proceed
  save_anchor({ key: "failure", value: JSON.stringify(result) })
  // Escalate to user
}

Core principle: Every subagent cycle exports intelligence. Parallel when independent. Sequential when dependent. Never ignore a return.

When to Use

• About to dispatch 2+ tasks
• Deciding whether to do work yourself or delegate
• Subagent just returned a result
• Managing a batch of parallel subagents
• Planning implementation order for multiple changes

Decision: Parallel vs Sequential

⚠️ DEFAULT: SEQUENTIAL — Parallel requires explicit justification

digraph delegation {
    "N tasks to do" [shape=doublecircle];
    "All 4 parallel conditions met?" [shape=diamond];
    "Sequential (default)" [shape=box, style=bold, penwidth=2];
    "Parallel subagents" [shape=box];
    "Research first, then decide" [shape=box];
    "Enough info to start?" [shape=diamond];
 
    "N tasks to do" -> "Enough info to start?";
    "Enough info to start?" -> "Research first, then decide" [label="no"];
    "Research first, then decide" -> "N tasks to do" [label="findings saved"];
    "Enough info to start?" -> "All 4 parallel conditions met?" [label="yes"];
    "All 4 parallel conditions met?" -> "Sequential (default)" [label="no (default)"];
    "All 4 parallel conditions met?" -> "Parallel subagents" [label="yes (rare)"];
}

The 4 Parallel Conditions (ALL must be true)

If ANY condition fails → SEQUENTIAL

⚠️ EXPLICIT DELEGATION MANDATORY

Every task delegation MUST include ALL of these:

BAD: "Fix the auth bug" GOOD:

Task: Fix JWT token refresh bug in src/auth.ts line 45
Scope: Only auth.ts. Do NOT touch token.ts or session.ts
Return: { outcome: "success|partial|failure", findings: "...", files_changed: [...] }
Success: npm test -- auth.test.ts shows 0 failures
Acceptance: All 5 JWT tests pass
Constraints: No refactoring, max 10 lines changed
Evidence: Capture error message, root cause, fix rationale

Common Patterns

Parallel-safe (dispatch simultaneously):

• Writing tests for different modules
• Researching independent topics
• Reading/analyzing separate files
• Creating independent utility functions

Must be sequential (wait between each):

• Schema change → tools that use schema → tests that verify tools
• Foundation module → modules that import it
• Config change → hooks that read config
• Any chain where file B imports from file A

Hybrid (batch by dependency layer):

Layer 1 (parallel): schema.ts + types.ts + config.ts
  ↓ wait, verify all pass
Layer 2 (parallel): tool-a.ts + tool-b.ts (both import from layer 1)
  ↓ wait, verify all pass
Layer 3 (parallel): test-a.ts + test-b.ts
  ↓ wait, verify all pass
Layer 4 (sequential): integration test → full ecosystem check

After EVERY Subagent Returns — Mandatory

// Parse the return. Was it truly successful?
// Then call export_cycle. NO EXCEPTIONS.
export_cycle({
  outcome: "success" | "partial" | "failure",
  findings: "What was learned or decided (1-3 sentences)"
})

What `export_cycle` does internally (zero cooperation needed):

1. Updates hierarchy tree — action node → complete/blocked
2. Saves findings to mems brain — shelf cycle-intel, tagged with timestamp
3. Links to timestamp chain — grep-able across all artifacts forever
4. Clears failure flag if present — stops the system prompt warning

What the hook auto-captures (even without `export_cycle`):

• Last message from subagent (first 500 chars) → brain.cycle_log[]
• Failure signal detection → brain.metrics.pending_failure_ack
• Turn count of the cycle → tracked automatically

`export_cycle` adds RICHER intelligence on top of auto-capture:

• Your interpretation of the outcome (not just raw text)
• Structured findings saved as mems (survive compaction + sessions)
• Hierarchy tree updated (shows decision trail visually)

Reward — What Good Delegation Gets You

After 5 cycles with proper export:

# See the full decision trail
node bin/hivemind-tools.cjs state hierarchy
# t_30141102026 — Build auth system [ACTIVE]
#   └── tc_45141102026 — JWT middleware [ACTIVE]
#       ├── a_00151102026 — Token validator [COMPLETE]
#       │   └── cycle: success — "jose library, 12 tests"
#       ├── a_15151102026 — Refresh logic [BLOCKED]
#       │   └── cycle: partial — "rotation works, Redis fails"
#       └── a_30151102026 — Integration [ACTIVE] ← cursor
 
# Recall ALL intelligence from subagent work
recall_mems({ shelf: "cycle-intel" })
 
# Trace everything linked to a specific cycle
node bin/hivemind-tools.cjs session trace 15151102026
# Shows: hierarchy node + mem + session log — full chain

Without export: After compaction, all subagent intelligence is gone. You have a vague "it was done" but no decisions, no failures, no rationale.

Consequence — What Bad Delegation Costs

Subagent Prompt Engineering

When dispatching, include:

1. Specific task — what to do (not "figure out what to do")
2. File context — which files to read/modify (don't make subagent discover)
3. Verification — how to confirm success (test command, expected output)
4. Return format — what to report back (outcome + findings + files changed)

BAD:  "Fix the auth system"
GOOD: "In src/auth/middleware.ts, the JWT validation on line 45 throws
       on expired tokens instead of refreshing. Fix the validation to
       call refreshToken() first. Verify: npm test -- auth.test.ts
       should show 0 failures. Report: outcome + which lines changed."

Red Flags