Research Dossier

---
name: research-dossier
description: Protocol for the AIDD research sweep — deriving decision segments, multi-directional searching, source discipline, and writing options.json plus dossier.md. Load during the AIDD research phase or when building gate options.
---

# The research sweep

The brief is in. Now find everything the project could be built from, and hand the user a real choice.

## 1. Derive the segments

A segment is **one decision this project actually has to make**, where a reasonable person could choose differently and the difference matters. Derive them from the brief. Do not paste a generic checklist — a static site generator and a hospital scheduler share almost no segments.

Draw from this catalogue as it applies:

**Foundation** — runtime and language · application framework · architecture shape (monolith / service / local-first / CLI) · package and build tooling

**Data** — storage engine · schema strategy · sync and offline model · external data sources and their licences · caching

**Interface** — UI framework or TUI · component and styling system · design language and typography · state management · accessibility floor

**Intelligence** (where relevant) — model provider · prompt vs fine-tune vs retrieval · eval strategy · cost ceiling

**Delivery** — hosting · CI · release cadence · migrations · observability

**Constraints** — auth model · licence compatibility · privacy and data residency · budget · the single hardest technical risk

**Prior art** — existing projects that already solve most of this, and whether to fork, port, wrap, or ignore them. Always search for this. Adopting a proven implementation usually beats writing a new one, and if you rejected that path the user deserves to see why.

Aim for 4–10 segments. Below 4 you probably folded real decisions into assumptions; above 10 the gate becomes a chore and people click through it.

### On an existing codebase

Read `.aidd/00-context/codebase.md` first — dispatch `aidd-surveyor` if it is not there. Then sort every candidate segment:

- **Closed** — the codebase committed to it and changing it would be its own project. Emit as `"locked": true` with a `lockedReason` citing the file that proves it, and exactly one option: the thing actually in place. It still needs honest pros *and* cons; a locked segment is where you tell the user the truth about what they are living with.
- **Open** — nothing in the code decides it. Research it as hard as you would greenfield.

Then filter every open option against the locked constraints. An option requiring Python 3.12 in a repo pinned to 3.11 is not an option — it goes in `rejected` with the constraint it violates. The one exception is an option good enough that changing the constraint is worth discussing; include it, and price the change in its `cons`.

Two failure modes, equally bad:

- Locking something that was actually open — you removed the user's choice without telling them.
- Leaving something open that is obviously closed — you produced a gate asking a 41k-line Django app whether it would like to be Rails, and taught the user the gate is not worth reading.

When it is genuinely borderline, leave it open with a strong recommendation and say what switching would cost.

## 2. Search in more than one direction

Per segment, sweep from every angle available to you:

| Direction | What it gives you |
| --- | --- |
| Official docs (Context7 or the docs site) | What it claims to do, current API, version reality |
| GitHub repo search | Maintenance, release cadence, issue shape, licence |
| GitHub **code** search | How people actually wire it up, which is often not what the docs show |
| Package registry | Download trend, dependency weight, deprecation notices |
| Critical write-ups | Migration-away posts, post-mortems, benchmarks that disagree |
| Prior art repos | Something that already does 80% of this segment |

**Stopping rule:** stop when two consecutive fresh searches surface nothing you have not already seen. Then write down what you searched for and did not find — that sentence is the difference between "there is no good option" and "I stopped early".

## 3. Source discipline

- Cite only pages you opened. A failed fetch is not a source.
- Prefer primary (docs, repo, spec, the licence file itself) over secondary (blog summarising docs).
- Date matters. A 2019 benchmark of a library that rewrote its core in 2024 is misinformation with a URL.
- Licences: read the actual `LICENSE`, not the badge. This is the single most common thing to get wrong, and the most expensive.
- Every option needs at least one source. Options with three or more sources — including one critical — are the ones the user can actually trust.

## 4. Write the options

Per segment, 3–5 options. Include the boring incumbent. Include the genuinely different one if it exists. Never pad to hit a number.

Per option:
- **Pros**: specific to *this* project. "Fast" is noise; "renders 10k rows without virtualisation, which is the whole screen you described" is a pro.
- **Cons**: the real cost this project will pay. If you cannot name one, read more. An option with no cons is an advertisement.
- **Sources**: real, opened, ideally including one critic.
- `recommended: true` on at most one per segment, only where evidence supports it. No recommendation is honest and often correct.

Then write the file and validate it:

```bash
node "${CLAUDE_PLUGIN_ROOT}/scripts/aidd.mjs" validate
```

The schema requires pros, cons, and a source URL on every option. That is deliberate: it makes a lazy gate impossible to ship.

## 5. Theme it from the domain

`options.json` carries a `theme` block: palette, display and body fonts, an optional font stylesheet URL, a hero texture, and an inline `heroSvg`. Derive it from the subject matter, not from taste. See the `decision-gate` skill.

## 6. Write the dossier

`dossier.md` is the receipt the gate page is too small to be:

```markdown
# Research dossier — <project>

## Method
What was searched, from which directions, and where the sweep stopped.

## Segment: <title>
### Considered
<every candidate, one line each>
### Made the gate
<why these>
### Rejected
<name — reason — url>   ← the answer to "why isn't X in here"
### Unresolved
<what could not be determined>

## Cross-cutting findings
Licence conflicts, version incompatibilities, anything that constrains
combinations across segments — the user cannot see these from the tabs.

## The hardest trade-off
Name it plainly. This is the one the gate exists for.
```

## Anti-patterns

- Gate options that are all the same choice wearing different hats.
- Cons written as fake weaknesses ("so powerful it takes time to learn").
- A segment with one option — that is a decision you already made for the user. Find an alternative or move it to the dossier as a stated assumption.
- Citing a homepage as evidence for a technical claim.
- Recommending the most-starred option by reflex. Stars measure attention, not fit.