# Research composition

- **`deep-research`** — gathers and cross-verifies the evidence; this skill formats and indexes what it produces.
- **`okf-knowledge-format`** — the format standard these artifacts conform to.
- **`living-docs`** — owns the constitution/PRD/ADR/issue artifacts; a research recommendation feeds a `living-docs` decision and then issues.

# Research rules & source discipline

## Rules

1. **Single file, sequentially numbered, immutable.** Each session is one file `docs/research/NNNN-<slug>.md` — never a per-research subfolder. A **sequential number leads the filename** (zero-padded, never reused); the **date lives in the frontmatter `timestamp`** (required), not in the filename. Research is a snapshot — do not silently rewrite past findings. New evidence → a new note that references the old one.
2. **Every claim is sourced.** No factual claim without at least one URL. A claim is "verified" only with ≥2 independent sources; single-source claims are marked low-confidence. (See `deep-research` for the full confidence scale.)
3. **Recommendations are caveated.** A recommendation resting on low-confidence evidence must say so.
4. **Contradictions are surfaced, not hidden.** When sources disagree, record both positions with attribution.
5. **Indexed.** The `docs/research/index.md` pointer must match the note's filename exactly. No orphan research.
6. **Reference, don't inline.** ADRs and PRDs *link* to the research note (bundle-relative); they don't paste the findings. The note is the single home for the evidence.
7. **OKF format.** The note opens with YAML frontmatter carrying `type: Research` (the general roll-up carries `type: Reference`). Sources are listed under a `# References` heading. The `docs/research/index.md` listing carries no frontmatter. Prose is one line per paragraph — never hard-wrap at a fixed column; `living-docs fmt` unwraps it (living-docs ADR 0046).
8. **The note's `# References` is the home.** Every research note ends with a `# References` section (NBR 6023, always the link, excerpts inline where a claim rests on a quote) — the authoritative source list for that session.
9. **The general roll-up stays in sync.** A source added to a note is added to `docs/research/references.md` in the same change. The roll-up is a derived index, not a second home — on divergence the per-note entry wins.

---

## Source discipline

These rules are non-negotiable for every research session:

1. **Source-priority ladder (ordered, mandatory).** Prefer sources top-down, and back every core claim with the highest tier that plausibly exists for its topic: **(1) academic & primary** — peer-reviewed papers, preprints (arXiv/SSRN), official specs/standards, datasets, postmortems, benchmark reproducibles, court/regulatory records; **(2) authoritative secondary** — official vendor docs, standards-body explainers; **(3) general internet** — industry analysis, reputable news, well-sourced blogs; **(4) low-trust** — SEO/marketing/unsourced posts, used only to locate a primary source. A core claim resting only on tier 3+ where academic literature plausibly exists is marked low-confidence and the gap is flagged. (The `deep-research` skill searches the tiers in this order.)
2. **Flag vendor conflict-of-interest explicitly.** Mark every claim that comes from a vendor with `[COI: <vendor>]`. This applies in both directions: a vendor claim that favors the vendor is suspect; a vendor claim that cuts *against* the vendor's interest is a strength — note both. Unflagged vendor claims are disqualifying on review.
3. **Cross-check load-bearing numbers.** Any number a decision rests on must appear in ≥2 independent sources. Single-source numbers are marked low-confidence and must not be used as a basis for a P0 or P1 recommendation.
4. **Label inference vs documented fact.** Conclusions you derive from the evidence are inferences — mark them `[inference]`. Statements traceable to a source document are facts — cite the source. Never present an inference as a sourced fact.
5. **Drop or flag what cannot be corroborated.** A claim with one source and no independent corroboration is either dropped or included with an explicit `[unverified — single source]` marker and low confidence.
6. **Record fetch failures in the method note.** If fetches are blocked (paywalls, rate limits, access restrictions), record it in the report's Method section and adjust confidence ratings accordingly. Do not silently omit blocked sources.

# Research structure & traceable chain

## Structure (OKF-conformant)

**One file per research session — never a per-research subfolder.** Each session is a single OKF `Research` concept at `docs/research/NNNN-<slug>.md` — a **sequential number leads the filename** (zero-padded, never reused, same scheme as ADRs/issues) and the **date lives in the frontmatter `timestamp`** (required), not in the filename. The file carries: question, query angles, findings (each with a confidence level and sources), contradictions, analysis, recommendations, and a trailing `# References` section (OKF §8) — **the home for that session's sources** (full NBR 6023 entries, always the link, key excerpts inline where a claim rests on a quote). See `templates/research-report.md`.

The top-level `docs/research/index.md` (OKF reserved listing) indexes every note with a one-line summary pointing to its file (`templates/research-index.md`). Cross-links are bundle-relative (`/research/NNNN-<slug>.md`).

### The general references roll-up

`docs/research/references.md` is a **cross-research bibliography roll-up** (`type: Reference`): the alphabetical union of every source cited across all notes, one NBR 6023 entry per source (always the link), each annotated with the note(s) that cite it (bundle-relative links). It is a **derived navigation index** — the answer to "where have we cited this before?" — **not a second home for the citation data**: on any divergence the per-note `# References` entry wins. Grown append-style — a note that adds a source not already listed adds it here in the same change. See `templates/research-general-references.md`.

---

## Research → decision → issue: the traceable chain

Every accepted recommendation must be traceable forward to a work item and backward to its evidence:

1. **Research → decision:** an accepted recommendation that changes architecture or a design that is expensive to reverse becomes an ADR (authored via `living-docs`). Ask the user before decisions that change constitution-level positions.
2. **Decision → issue:** each ADR spawns one or more issues through the `living-docs` issue workflow. The issue links the ADR; the ADR links the research artifact.
3. **Chain completeness:** an orphan recommendation (not yet an ADR) is incomplete; an ADR without issues is unplanned; an issue without an ADR or research reference is ungrounded. All three gaps are valid review findings.

---

## Relationship to decisions

Research informs ADRs and BDRs. The typical flow:

1. A decision is unclear → run `deep-research` → artifacts land in `docs/research/`.
2. The decision is made → write an ADR via `living-docs`, whose Context links the research artifact.
3. Later, the research is reference material, not a requirement — it explains *why the decision looked right at the time*, even if a future ADR supersedes it.

---

## Anti-patterns

- Treating research as a living opinion doc that gets edited as views change. That destroys the audit trail. Each session is a dated snapshot; evolution is expressed as a *new* session, not an edit.
- Breaking the traceable chain by accepting a recommendation without writing its ADR, or writing a ADR without spawning issues, or opening issues without linking their source decisions.

---
type: Reference
title: "Research — general references roll-up"
description: Cross-research bibliography. Derived index of every source cited under docs/research/; each note's own # References is the authoritative home.
status: Live            # append-grown alongside the research notes it indexes
tags: [references, bibliography, roll-up, index]
timestamp: <ISO 8601 datetime>
---

# References (general roll-up)

<!-- Lives at docs/research/references.md. A DERIVED navigation index, not a second home
     for the citation data: the authoritative source list for any note is that note's own
     trailing `# References`. On divergence, the per-note entry wins.
     Append-grown: a note that cites a source not already listed adds it here in the SAME
     change (research-artifacts rule 9). Format per
     skills/living-docs/rules/citation-conventions.md (ABNT NBR 6023, always the link).
     Alphabetical by first element. Each entry trails with `— cited in:` + bundle-relative
     links to the session(s) that use it. -->

SURNAME, First name. **Title**: subtitle. City: Publisher, year. Available at: <URL>. Accessed on: YYYY-MM-DD.
— cited in: [date-slug](/research/date-slug.md)

<!-- OKF reserved index.md (§6) for docs/research/ — a directory listing, NO frontmatter.
     One pointer line per research note. Append new lines; never overwrite existing ones.
     Each note is a single, immutable file named NNNN-<slug>.md (sequential number leads;
     the date lives in the note's frontmatter `timestamp`; no per-research subfolder). -->

# Research

* [NNNN — <slug>](NNNN-<slug>.md) - <one-line summary of the finding> (date in the note's frontmatter `timestamp`)

---
type: Research
title: <Research question, short>
description: <One sentence — what was investigated and the headline finding.>
status: complete            # complete | blocked (some fetches failed — see Method)
tags: []
timestamp: <ISO 8601 datetime>
---

# <Research question>

<!-- The OKF concept for one research session. Lives as a SINGLE file at
     docs/research/NNNN-<slug>.md — never a per-research subfolder. Findings are
     immutable once dated; the date may sit in the filename and always in `timestamp`. -->

## Method

<Query angles explored. Record any blocked fetches (paywalls, rate limits) here and
downgrade confidence accordingly — never silently omit a blocked source.>

## Findings

<Each finding with a confidence level and inline source markers. Mark inferences
`[inference]`, vendor claims `[COI: <vendor>]`, single-source claims
`[unverified — single source]`. A claim is "verified" only with ≥2 independent sources.>

## Contradictions

<When sources disagree, record both positions with attribution.>

## Analysis

<Synthesis across findings.>

## Recommendations

<Each recommendation, caveated by the confidence of the evidence under it. A
recommendation resting on low-confidence evidence must say so.>

# References

<!-- OKF §8. The home for this session's sources: full NBR 6023 entries (always the link),
     key excerpts inline where a claim rests on a quote. Add any new source to the general
     roll-up docs/research/references.md in the same change (research-artifacts rule 9).
     Format per skills/living-docs/rules/citation-conventions.md. -->
SURNAME, First name. **Title**. Year. Available at: <URL>. Accessed on: YYYY-MM-DD.