| name | caspar-research |
| description | Research a codebase to answer a question — fan out read-only agents (finder/analyst/patterns, web-research for 3rd-party), then synthesize evidence-backed findings into a saved research doc with file:line citations. Use when the user asks "how does X work", "where does Y live", "investigate/research Z before planning", or wants a written research artifact. Do NOT use to write code, plan a feature (use caspar-plan), or for a one-off lookup that needs no saved doc. |
| user-invocable | true |
research
Codebase research: spawn parallel read-only agents, synthesize their findings into one evidence-based document. Live code is the source of truth.
Inputs
- Research question / topic (from
$ARGUMENTS). If absent, send an immediate reply asking for it and stop.
- Any files the user names (tickets, docs, JSON).
Working set
OUT_DIR = user-specified target_dir, else docs/tasks/{branch}/ (git rev-parse --abbrev-ref HEAD, fallback unknown). Read branch/commit/repo via tool at write time, never inline earlier.- Agents (read-only, run in parallel):
@finder (where code lives), @analyst (how it works), @patterns (similar implementations), @web-research (3rd-party docs — instruct it to return LINKS). Context7 MCP only if the user explicitly asks for library docs.
Method / guardrails
- Immediate reply first — acknowledge the topic (or ask for it) with NO tool calls in the opening turn.
- Read named files fully in main context (no limit/offset) before decomposing.
- Decompose the question into areas; track with TodoWrite. Strategy: locate → analyze promising hits → fan out parallel reads. Tell each agent what to find, not how to search.
- Wait for ALL agents before synthesizing. Compress each return to a 1–2K summary; do not write per-agent scratch files.
- Synthesize: prefer live-code findings as source of truth; connect findings across components; cite concrete
path:line; answer the user's actual question with evidence.
Outputs + DONE
Write one doc to {OUT_DIR}/research/{topic}_{MMDDYY}.md. DONE when:
- YAML frontmatter:
date (ISO+tz), git_commit, branch, repository, topic, tags, status: complete, last_updated (YYYY-MM-DD), last_updated_by. Multi-word keys snake_case.
- Sections, in order: 1 Title
# Research: {topic} · 2 Metadata header · 3 Research Question · 4 Summary · 5 Detailed Findings (by area, with file:line) · 6 Code References · 7 Architecture Insights · 8 Related Research · 9 Open Questions.
- Every claim is backed by a
path:line reference; live code prioritized over docs.
- Permalinks: if on main/master OR the commit is pushed, replace local refs with
https://github.com/{owner}/{repo}/blob/{commit}/{file}#L{line} (gh repo view --json owner,name); else keep local refs.
- A concise findings summary (with key file refs) is presented to the user.
Handoff
- Follow-ups update the SAME doc: bump
last_updated/last_updated_by, add last_updated_note, append ## Follow-up Research {timestamp}, spawn agents as needed.
- Close with a one-line Next Steps pointer (e.g.
caspar-plan to formalize, or further research).
Escalate-If
- The question is too broad/ambiguous to scope agents → ask one clarifying question before fanning out.
- Findings contradict each other or the live code can't be reached → surface the conflict in Open Questions rather than guessing.
