Research-output quality template

This file is the quality bar an auto-research agent (or a human processing a raw dump) should hit when turning a raw dump into a committed research note.

It is not the research-note template itself — that lives at templates/research-note.md and captures the required structure. This file captures the required depth.

Exemplars to match

The four research notes committed on 2026-04-17 and 2026-04-20 are the reference points. An output of this quality level should be structurally and stylistically indistinguishable from them.

Database analysis — the archetypal opinionated tech-stack comparison. 2,800+ words, candidate matrix, per-candidate deep-dive, fit analysis, explicit recommendation, alternatives, 35+ cited URLs, standalone HTML companion with inline SVG system diagram.
Shared project memory — landscape survey with a ranked shortlist and a concrete rollout plan.
Agentic coding and PR review — product-landscape comparison with numbers and a one-week wire-in plan.
Multica and Claude Managed Agents — includes an end-to-end day-in-the-life system diagram and a cost envelope.

Required sections

Mirror templates/research-note.md exactly. For every research note:

# Research — <topic> title
**Date** / **Author** / **Status** / **Prompted by** frontmatter
## Question — one-paragraph framing
## TL;DR — with a bold recommendation sentence. The reader should be able to stop here and still know what to do.
## Approach — one paragraph on how the research was done (agents? web search? interviews?).
## Findings — H3 subsections per topic area. Each should close with a crisp conclusion.
At least one comparison matrix — markdown table. Traffic-light pills where semantic (green locked, amber working, red needs input).
At least one ranked shortlist or decision path — numbered layer-stack or pipeline.
## Recommendation for 361 — opinionated. Don’t hedge.
## Alternatives considered — what was rejected and the revisit triggers.
## Sources — 20+ cited URLs minimum. Grouped by theme.
## See also — links to sibling research, ADRs, prototypes, daily log.
## Linked from — back-pointer to the originating daily log, meeting, or ADR.

Required HTML companion

Every research MD ships with a standalone HTML at the same slug. The HTML must:

Use only the :root tokens and named components from BRANDING.md. No Tailwind, no Bootstrap, no shadcn.
Include the .geo-bg grid background. It’s the single strongest brand cue.
Use .eyebrow, .tldr, .pipeline, .layer-stack, .mini-table, .card-row, .bullets, .sources as the component vocabulary.
Include at least one inline SVG diagram for system shape, flow, or relationship. No external image deps.
Fade-up entrance animations (.animate-up .delay-1 … delay-8) on the main sections.
Mobile-responsive via the single @media (max-width: 760px) block in the reference HTMLs.
Footer pointing at the MD companion and sibling notes.

Voice and tone

Sentence case in body. UPPERCASE reserved for labels (.eyebrow, card .k, table headers).
Direct, opinionated. “Use X.” not “Teams may wish to consider adopting X where appropriate.”
No “seamless / sleek / powerful” decorative adjectives. The calm visual system earns the tone; prose shouldn’t undercut it.
Link everything. A claim without a citation is a claim the reader can’t check — downgrade it to “speculation” or cite it.

Required research rigour

Cite at least 20 URLs. Group by theme at the end. Inline-cite where claims are made; don’t just dump at the bottom.
Name the vendor / project / tool. If a GitHub repo exists, link it. If pricing is public, quote the number. If a feature is beta, say so.
Price in USD (unless NZD is specifically called for), preferring ap-southeast-2 Sydney pricing where applicable.
Declare confidence: “Confirmed via …”, “Strongly suggested by …”, or “No public info — speculation” for each material claim.
Cross-check against prior committed research. If the dump’s topic overlaps with a committed note, read that note first; don’t contradict earlier decisions without explicit rationale.
Reference the clickable UI prototype (~/Desktop/oxflow/prototypes/oxflow-ui/) if the research touches data shapes or user-visible flows.

Word-count targets

Section	Target
TL;DR	80–160 words
Question	60–120 words
Approach	60–120 words
Findings	1,200–2,800 words across all subsections
Recommendation	200–500 words
Alternatives	150–400 words
Sources	20+ URLs, grouped
Total MD	2,000–4,000 words

HTML companion: same content, reshaped for scannability. Keep headings short. Use components, not prose, where a component can carry the idea.

Cross-linking obligations

When the new note lands, also:

Append a ## See also entry in the originating raw-dump file marking it Status: processed → <new note>.
Add See also entries in any existing research note whose topic materially overlaps.
Resolve any _tbd placeholders in the relevant daily log with concrete links.
Update status/daily/YYYY-MM-DD.md for today with a one-line mention of the new note.

Privacy / red lines

Never commit anything from a dump that contains secrets, NDA-covered material, or client-confidential pricing. Scrub before research if needed.
If the dump came from a session transcript, follow the shared project memory note’s scrubbing rules.
If in doubt, leave the dump in raw-dumps/ and flag it for a human.

When to route to ADR instead of research

If a dump encodes a decision (e.g. “we are switching from X to Y”, “we agreed to use Z”), the output belongs in decisions/NNNN-<slug>.md as an MADR ADR, not in research/. When unsure, write the research note and reference it from a short ADR.

oxFlow Wiki

Explorer