reliquary/.claude/skills/research-tree/SKILL.md

---
name: research-tree
description: Orchestrate multi-topic research as a dependency tree of parallel phases — not a flat fan-out of independent agents. Use this skill whenever the user asks for "research", "deep research", "investigate", "survey", or "look into" a topic that has multiple sub-topics, or when a question is broad enough that a single agent would either skim or take forever. Trigger especially when the user says things like "research X and Y and Z", "find out everything about…", "do a deep dive on…", or when prior research has surfaced new questions that need follow-up. Composes with the `workpad` skill for file placement and runs alongside `superpowers` and similar orchestration helpers.
---

# Research Tree

Most non-trivial research questions decompose into many sub-topics, and those sub-topics are *not* independent — later questions get sharper once earlier ones are answered. Running every sub-topic in parallel as peer agents wastes work and produces shallow, redundant findings. Running them strictly in series wastes wall-clock time. The right shape is a **tree of phases**: within a phase, agents run in parallel; between phases, later agents inherit the earlier reports.

This skill describes how to plan and run that tree. It does not describe how to write the contents of an individual research report — that's up to the agent doing the writing, plus whatever conventions the project has.

## When to use this skill

Use it when **two or more** of these are true:

- The topic has multiple sub-questions that a single agent couldn't realistically cover in depth.
- Some sub-questions clearly *depend on* the answer to other sub-questions (e.g. "evaluate library X" depends on "what are our requirements").
- The user wants something they can read and refer back to, not just a chat answer.

For a single focused question, just answer it. Don't reach for the tree.

## The shape of a research tree

```
Phase 1 (parallel)        Phase 2 (parallel)        Phase 3 (parallel)        Summary
─ topic A ─────┐          ─ topic D (knows A,B) ─┐  ─ topic F (knows D,E) ─┐  ─ index.md
─ topic B ─────┼──────►   ─ topic E (knows B,C) ─┼──► …                   ─┼──► (linking all)
─ topic C ─────┘          ─ …                    ┘                         ┘
```

- **Within a phase:** agents run in parallel. They do not share intermediate findings with each other — by definition the phase is composed of topics that are mutually independent at that point in the tree.
- **Between phases:** when an agent in phase N+1 starts, hand it the *full text* of the reports it depends on from earlier phases — not just summaries, and not all reports indiscriminately. Pass *its* ancestors in the tree, transitively.
- **Specificity flows downward.** Broad framing topics live near the root; narrow, technical, "given X, exactly how does Y behave" topics live near the leaves.

## Planning the tree

Before spawning a single agent, plan the tree explicitly. Write the plan down — usually in the workpad as a brainstorm or design note — so you and the user can sanity-check it.

1. **List every sub-topic** you can think of, even ones that feel redundant. Easier to delete than to discover later.
2. **For each sub-topic, ask: "what would I need to know first?"** Draw an arrow from each prerequisite topic to the dependent topic. This produces a dependency graph, not yet a tree.
3. **Break cycles.** If A needs B and B needs A, you have a cycle. Resolve it by inserting a new, smaller intermediate topic that both can build on (e.g. "shared definitions and ground truth for X"), or by deciding which direction is the dominant dependency and demoting the other to a follow-up question for phase N+2.
4. **Group into phases by depth.** Topics with no prerequisites are phase 1. Topics whose prerequisites are all in phase 1 are phase 2. And so on. A topic that depends on items from phases 1 and 3 is itself a phase 4 topic — always one past its deepest prerequisite.
5. **Sanity-check phase widths.** A phase with one topic is fine but suspicious — can it merge with the next phase? A phase with fifteen topics is a sign you haven't decomposed dependencies enough. Aim for 2–6 per phase typically.
6. **Confirm the plan with the user** before launching. The plan itself is the most important artifact — a wrong tree wastes the most expensive resource (agent time on the wrong questions).

## Running the phases

Use the workpad's `research/` folder, almost always inside a dated subfolder for the whole tree:

```
research/
  2026-05-05-14-auth-provider-evaluation/
    phase-1-requirements.md
    phase-1-current-state.md
    phase-1-constraints.md
    phase-2-candidate-comparison.md
    phase-2-migration-paths.md
    phase-3-cost-modeling.md
    index.md          ← written last, read first
```

Filenames should be slugged by topic; the `phase-N-` prefix is optional but helps when listing the directory.

For each phase:

1. **Spawn agents in parallel** for that phase's topics. Each agent receives:
   - Its own narrow research brief.
   - The full text of every ancestor report it depends on (transitively up the tree). Don't summarize on the way in — let the downstream agent skim or quote as it sees fit.
   - The path to write its report into.
2. **Wait for the phase to complete** before starting the next. Don't try to overlap phases — the dependency is what makes the tree worth doing.
3. **Quickly read each report yourself** before dispatching the next phase. If a phase produced something surprising or contradictory, the dependency graph for the *next* phase may need updating.

## When findings contradict each other

If two reports in the same phase reach incompatible conclusions, or a phase-N report contradicts something assumed in phase-N-1, do not paper over it in the summary.

- Spawn a **verification / reconciliation agent** as an extra step. Give it both conflicting reports and ask it to identify the actual disagreement, what evidence each side rests on, and what would resolve it.
- The verification agent writes a **review paper** that lives next to the others (`review-<topic>.md`).
- Update the relevant prior reports if they got something wrong, or note the open question explicitly in the summary.

This is also the move when the summary is *hard to write* — that's usually a signal that contradictions are present and have been silently smoothed over.

## The summary / index document

The summary is written **last** and is the **first** thing a reader should open. Conventions:

- Filename: `index.md` (or `00-summary.md` if you want it to sort first).
- Linked from every other report in the tree (or at least from the directory's README).
- Structure: a one-paragraph TL;DR, the question that started the tree, the high-level answer, then a short section per phase linking out to the full reports.
- Do not paste the contents of the other reports into the summary. Link to them. The summary's job is navigation and synthesis, not duplication.

If the summary turned out hard to write, that's a signal — see the contradictions section above.

## What this skill does *not* govern

- The internal structure of an individual research report — that's the agent's call, plus project conventions.
- Whether the workpad itself exists / where it lives — defer to the `workpad` skill.
- Picking which model to use for which agent — out of scope here.