Investigate

Up to four research agents independently diagnose the task. You (the main agent) read the task, launch them in parallel, cross-check their findings, and report the best steps. You do NOT write any code during this skill.

Works for two kinds of task:

• Fix — a bug or broken behavior. Goal: root cause + minimal clean fix.
• Feature — something to implement. Goal: where it goes, how to build it, and the possible approaches with trade-offs.

Step 0 — Read the task and classify it

Args are a task: an issue link/id, or a plain instruction.

• A task link/id was provided → fetch its content and read title + full description (Linear via its MCP get_issue, GitHub issue/PR via gh, or fetch the URL).
• Plain instruction → use as-is.

Decide whether it's a fix or a feature (fixing broken behavior vs building something new). If unclear, default to feature framing. Restate the task in one line + the type so the user can confirm. If genuinely ambiguous, ask one focused question before spawning agents.

Step 1 — Spawn research agents in parallel (2–4)

Launch the agents in a single message so they run concurrently. At most 4 at once. Pick the count and framing by task type:

• Fix (bug) — agents converge on the SAME goal (the one root cause). Use 2–3, each attacking it from a different angle (e.g. reproduce/trace, read suspect module, check recent changes/git blame) but all aiming at the same answer.
• Feature — agents spread across DIFFERENT aspects. Use up to 4, each owning a distinct slice (e.g. where it lives / existing patterns, data + backend, UI + wiring, approaches + trade-offs).

Scale down (2 is fine) for small/clear tasks; only reach 4 when the task is large or ambiguous. Give each agent the SAME task context, a short name of its own, and the roster — every sibling's name and slice. Each agent reaches its OWN conclusions and never assumes another's findings; what it may share is where things live (Step 1a).

Which model to give them

Research is the whole product here, not a support task, so don't economize on it. The agents run on your own model — the one the user picked for this session. Reading unfamiliar code and telling a real root cause from a merely plausible one is exactly where a weaker model produces confident nonsense, and Step 2 cannot catch it when several agents made the same kind of mistake and now agree.

• Research agents → your model. Pass it as the Agent tool's model parameter.
• Agent Delulu (Step 1.5) → your model as well. It exists to catch hallucination, so it cannot be weaker than what it is auditing.
• Running on Fable → give them Opus instead.

This is guidance, not a rule. If the user asks for something else, do that — a small, well-scoped task they want done cheaply is a fair reason to go lower. When it is your call and you are unsure, go up a tier, not down.

In BOTH modes each agent must: locate the relevant code and libraries, give exact file paths + line numbers, and NOT edit anything — investigate and report only.

If FIX, each agent must:

1. Identify the ROOT CAUSE — exact files + line numbers, and the mechanism.
2. Propose a CLEAN, MINIMAL fix — smallest diff that fully solves it.
3. List alternatives with trade-offs, and flag risks / side effects.

If FEATURE, each agent must:

1. Find WHERE it should live — the files, modules, and patterns to extend; how similar things are already done in this codebase.
2. Lay out HOW to build it — concrete steps, the components/functions/APIs to touch or add.
3. Give the POSSIBLE APPROACHES — 2+ options with trade-offs (effort, risk, fit with existing patterns), and a recommendation.
4. Flag constraints, dependencies, and edge cases.

Emphasize in both: minimal footprint, clean solution, follow existing codebase conventions.

Step 1a — Let the agents share the map, never the verdict

Agents work in parallel, so they re-walk the same code. Sharing what they found saves that waste. Sharing what they concluded destroys the point of running several — Step 2 treats agreement as high-confidence, and that only holds if they got there apart. An agent that adopted a sibling's root cause is not a second opinion, it is an echo.

The line is fixed:

• Shareable — a clue. Where to look: a path and line number, which function owns a behaviour, where a pattern already exists, what a config key controls, a dead end ("nothing relevant under x/"). A clue is allowed to be vague — "retry is wired somewhere under transport/, I didn't open it" is a useful thing to say. Say so when it is a hunch rather than something you confirmed.
• Never shared — an answer. Root cause, recommended fix, which approach wins, risk calls — anything carrying a judgement. Those stay inside each agent until Step 2.

The receiver confirms. Always. That is what makes a vague clue safe to pass around: the cost of a wrong one is a single wasted look. Never cite a sibling as evidence, and never let anything you have not opened yourself reach your report — repeating an unverified clue as a finding is a fabrication, and it is the one failure this whole mechanism must not cause.

Use all of this sparingly. It exists to stop two agents hunting for the same file, nothing more. A normal investigation writes a handful of map lines and reads the map once or twice. If it is turning into running commentary, it has stopped being research.

The shared map file

Before spawning, create a scratch file OUTSIDE the repo (the session scratchpad if there is one, otherwise mktemp -d) and give every agent its absolute path. Tell each agent:

• Before an expensive search, grep the map once — a sibling may already have the anchor. Don't poll it, and don't consult it for anything you could find yourself in seconds.
• After finding an anchor that was hard to find, append one line, tagged confirmed if you opened it or hunch if you did not. Append only, never rewrite, so parallel writes cannot clobber each other:

echo "path/to/file.ts:120 — retry/backoff lives here — confirmed — <your-name>" >> "$MAP"
echo "transport/ — retry probably wired in here, not opened — hunch — <your-name>" >> "$MAP"

• Locations only, one line each, no conclusions. Don't log every file you opened — only anchors worth another agent's time. A hunch line is welcome; an unmarked guess is not.

The map is a lookup index, not a report. One grep, and it can save a whole search.

Asking a sibling directly (you are the switchboard)

Subagents have no agent-listing or messaging tools, so they cannot reach each other — every request goes through YOU. Give each agent the roster and this protocol, for when it needs something a sibling owns and the map does not cover:

1. The asking agent ends its turn with only:

   NEED: <sibling name> — <one specific question>

2. You relay it with SendMessage, asking for five lines maximum of where to look. A rough steer is fine and it may say "not sure"; it marks anything it did not verify. No opinions, no conclusions.
3. You send the answer back to the asker, which resumes with its context intact.

Bounds, because this costs a full round trip and stalls the asker while it waits:

• Expect zero of these in a normal investigation. It is an escape hatch for an agent stuck on ground a sibling has plainly already walked — not a way to ask around.
• One hop, no chains. An agent answering a NEED never raises one of its own.
• Only when the search is genuinely expensive and a sibling has plainly already done it. A grep the asker could run itself is cheaper than the relay.
• Ask for a lead, not a finding. "Which file holds X" is fair, and a vague answer to it is fine. "What did you conclude about X" is not.
• The asker verifies what comes back before using it, exactly as with the map.
• If the owner already finished, answer from its report — locations only — or tell the asker to search for itself.

Step 1.5 — Agent Delulu (fact-check, only when needed)

Only trigger when the research agents are genuinely undecisive and look like they're hallucinating — e.g. they contradict each other on the core answer, cite file paths / line numbers / APIs that don't line up, or give confident claims with no solid evidence. If the agents broadly agree and their findings hold up, SKIP this step and go straight to Step 2.

When triggered, spawn ONE general-purpose agent named Agent Delulu. Give it every other agent's full report and this job:

1. Fact-check EVERY claim against the actual codebase — open the cited files, verify the file:line references, the mechanism, and any named functions/APIs really exist and do what was claimed.
2. Label each agent's findings: right / wrong / partially right — with the evidence.
3. Return the corrected picture: what actually holds and what to discard.

Agent Delulu reports back to YOU (the main agent), not the user. Fold its verdict into Step 2 — weight confirmed findings, drop debunked ones.

Step 2 — Synthesize and report

After both agents return:

1. Cross-check — where the two agree, treat as high-confidence. Where they differ, call it out and say which is more likely / better and why.
2. Report — pick the matching template.

Fix:

## <task>

### Root cause
<mechanism, with file:line>

### Recommended fix (minimal)
<smallest clean fix, with file:line and concrete change>

### Alternatives considered
- <option> — <why not / when to prefer>

### Risks / side effects
- <anything to watch>

### Decisions for you
- <choices the user should make>

Feature:

## <task>

### Where it goes
<files / modules / existing patterns to extend, with file:line>

### Recommended approach
<the approach to take and why, with the concrete steps>

### Other approaches
- <option> — <trade-offs / when to prefer>

### Constraints & edge cases
- <dependencies, gotchas>

### Decisions for you
- <choices the user should make>

Keep bullets to one line. Lead with the conclusion, not the search process.

Step 3 — Ask before implementing

After the report, ask whether to implement the recommendation, pick another approach, or adjust scope. Wait for the user before making any code changes.

Rules

• Never modify code during this skill — investigation only.
• 2 agents minimum, 4 maximum at once. Fix → converge on one goal; feature → diverse aspects.
• Agents run on your own model, Agent Delulu included — Opus if you are Fable. Guidance, not a rule — the user's choice overrides it.
• Agents share clues, never answers — and sparingly. A clue may be vague and may be a hunch, as long as it is marked; root cause, approach and recommendations never cross. The receiver confirms every clue itself — nothing reaches a report on a sibling's word.
• Subagents cannot message each other. You relay every NEED: request. One hop, no chains, a lead not a finding, and expect almost none.
• Agent Delulu (fact-checker) only when agents are undecisive / look like they're hallucinating.
• Prefer the smallest footprint that fully solves the task. Follow existing codebase conventions.
• Report only high-confidence conclusions. State disagreements plainly instead of papering over them.
• Always give exact file paths and line numbers.