davidlee Research
The pre-design research round produces a persisted evidence artefact —
research.md — that later stages cite instead of re-deriving. Two read-only
threads (governance applicability; code map) plus cross-thread synthesis,
assembled by the orchestrating agent into one document.
The artefact lives at .doctrine/slice/NNN/research/ — directly in the slice
folder, gitignored in place. Runtime tier: disposable working evidence;
durable findings are harvested at slice close.
The verb: doctrine slice research <id> — run it when the round starts
(it mints the research folder and stamps the staleness baseline,
baseline.toml), and again whenever you consume the artefact, to check
freshness. It is advisory, never a gate:
drift output is a prompt to refresh, and the command always succeeds. Flags
and mechanics: the CLI's help.
The artefact — research.md
Mandated skeleton; refresh rounds revise sections in place, extra sections are free-form:
- Header — producers (who/what ran each thread), baseline pointer.
- Verification legend — the ✓ discipline below.
- Thread 1 — governance applicability — binding constraints; checked-not-applicable with stated reasons; revision candidates.
- Thread 2 — code map — hotspots (files likely to change), cited facts, naming precedents.
- Cross-thread findings — where the threads intersect or conflict; often the highest-value section.
- Design-input deltas — what this research changes about the intended design.
Alongside it: raw/<thread>.md (verbatim thread output) and baseline.toml
(stamped by the verb).
Citation forms
- Governance claims cite durable entity ids.
- Code claims cite
file:line. - An uncited claim is unverifiable by definition.
Verification discipline
- ✓ = the claim was independently verified by the consuming agent (a grep or read of the cited site). Unmarked = researcher claim: cited, not checked.
- Design and plan may only load-bear ✓ rows, or rows they verify at point of use.
- Verification is asymmetric — verify what you lean on (about one grep per load-bearing claim), not everything.
Running the round
- Spawn the project's research agents, one per thread, read-only; capture
each thread's stdout to
research/raw/<thread>.md— never inline bulk output into the conversation. - What a research agent is (command, model, expectations) is project-defined — see the project governance doc's Research agents section. Doctrine ships no runner.
- Graceful degradation: if the project defines no research agents, run the threads yourself, or skip the round and say so in the artefact header.
- Researchers never write files or memories. The orchestrating agent distills
raw/into the curated artefact — the doc points at raw for bulk.
Prompt duties
Every thread prompt must demand:
- the citation forms above;
- the structured not-applicable form (each dismissed authority named, with a stated reason);
- output already in the artefact's section shape;
- no preamble (cheap models add it; the assembler strips it).
Who invokes this
Single-sourced here; the invoking skills carry only short advisory pointers:
/slice— after scoping, run the round before/design./design— consumes the artefact; Thread 1 stands in for the bulk of the governance sweep; design assertions citeresearch.md./plan— checks the staleness advisory; drafts selectors from the Thread 2 hotspot map./phase-plan— checks the advisory; on drift, refreshes only the affected sections, then re-stamps the baseline.