DESIGN.md@packs/desk-research git:20260819.8428185A

Immutable. This exact content is served forever at /api/v1/blob/791aceb6124d67e4.

# Desk Research Pack — Design Document

Living design reference for the desk-research pack. Records the philosophy, architecture, invariants, and key decisions so the reasoning survives beyond individual PRs and applies when extending or replacing any skill.

---

## TL;DR

`desk-research` is the evidence layer. It has two independent axes: depth (quick → deep/exhaustive) and lifecycle (single-session vs. sustained project). Source-first ordering — map sources before retrieving, primary before secondary — prevents the most common triangulation failure. GRADE confidence grading makes the epistemic state explicit rather than hiding gaps behind authoritative-sounding prose. Two read-only subagents (`evidence-retriever`, `source-extractor`) preserve main-session context by collapsing raw fetched material into a synthesis before returning. The pack is user-scope by default: research method is portable; artifacts are per-repo and resolved through the adopter's `agentbundle-layout.toml`.

---

## Non-Goals

Things a reasonable reader might expect this pack to solve. It doesn't, by design:

- **Live web monitoring** — the pack retrieves on demand; it does not watch sources and alert on changes.
- **Primary interview research** — discussion guides, interview scripts, and moderated research belong to a dedicated UX research workflow, not to desk research.
- **Quantitative analysis** — statistics, experimental design, and data modelling are outside scope. The pack reads quantitative findings and grades their evidence quality, but does not produce statistical analysis.
- **Automatic citation management integration** — the pack produces cited Markdown artifacts; syncing them to external reference managers is an adopter concern, not a pack concern.

---

## 1. The two-axis model

### What the axes are

The pack separates two dimensions that are easy to conflate:

- **Depth axis** — how thoroughly to investigate a single question. Four modes: `quick` (≤5 fetches, inline answer), `standard` (cited survey, ≥3 sources per claim), `applied` (practitioner grey-literature calibration), `deep` (standard + adversarial review via `devils-advocate`).
- **Lifecycle axis** — whether an investigation is a single session or a sustained project. Session mode: one invocation of `desk-research`, produces a typed artifact or an inline answer. Project mode: a multi-week lifecycle — scaffold → capture → digest → synthesize → feedback — that accumulates a corpus over time.

### Why they are orthogonal

A quick session lookup and an exhaustive multi-week investigation are not on the same scale — they are different shapes of work. Forcing one into the other either requires premature closure (a project question answered in one pass) or unnecessary scaffolding (a quick lookup going through project scaffolding).

The lifecycle axis is equally independent of depth: a project can accumulate sources at `standard` depth or at `applied` depth or at `deep` depth. The depth setting on each per-source retrieval pass is independent of the project's lifecycle phase.

### Entry points by axis

| Axis | Entry points |
|------|--------------|
| Session | `desk-research` (all depth modes) |
| Session — decision support | `source-map`, `build-outline`, `identify-perspectives`, `compare-hypotheses`, `devils-advocate`, `decision-archaeology` |
| Project | `desk-research-project-start` → `desk-research-project-status` / `desk-research-project-check` → `desk-research-project-digest` → `desk-research-project-synthesize` |

---

## 2. Source-first ordering

### The principle

Canonical sources are identified before retrieval begins; primary sources are retrieved before secondary. This is what `source-map` enforces.

### Why

The most common triangulation failure mode is synthesizing secondary summaries that each independently cite the same primary — and treating that as three independent data points. A synthesis that samples three blog posts about the same DORA report has not triangulated; it has cited the same finding three times.

Source-first ordering catches this by mapping the primary source landscape before any retrieval is dispatched. When retrieval starts from primary sources, secondary sources are encountered as signals pointing to primaries rather than as independent claims.

### What counts as independent

Per the applied-mode practitioner-independence rule: three sources from the same vendor count as one independent; three sources in the same employer cohort count as one; three reblogs of the same original post count as one. Independence is asserted on the chain back to the origin, not on the number of URLs.

---

## 3. GRADE confidence grading

### The grading schema

Every material finding in a standard/applied/deep synthesis carries a confidence tag from the closed set: `[high]` / `[moderate]` / `[low]` / `[uncertain]`. The schema is codified in `references/confidence-schema.md` — the skill body references it; it does not reprint it.

### Why GRADE, not a subjective tier

GRADE grades reflect the quality of the evidence (study design, consistency, directness, precision) — not the author's degree of confidence in their own opinion. This is the same discipline systematic reviews use. Using GRADE-style grades makes the distinction between "well-supported by multiple independent studies" and "one vendor blog post" explicit in the artifact, rather than hiding it behind authoritative-sounding prose.

### The gap distinction

Confidence grades tag claims the research *did* make. Gaps are questions the research *could not answer at all*. Conflating the two — treating a gap as an `[uncertain]` finding — is a category error: `[uncertain]` means *a claim exists, but weak grounds for it*; a gap means *no claim exists, because the evidence isn't there*. Every non-quick synthesis carries a `## Known unknowns` section that separates known-unknowns (answerable in principle; name the evidence) from unknowables (not answerable from available evidence; name why).

Honest gaps are better than false confidence. A synthesis that names its limits precisely is more useful to a decision than a synthesis that asserts completeness.

---

## 4. The seven convergent disciplines

The methodology grounds the pack's behaviour in seven disciplines that each contribute a distinct structural obligation:

| Discipline | Contribution |
|---|---|
| STORM | Co-STORM moderator pass — scan retrieved-but-uncited material before declaring done |
| PRISMA | Systematic inclusion/exclusion criteria; population-level claim discipline |
| ACH (Analysis of Competing Hypotheses) | Inconsistency-weighted hypothesis adjudication |
| Wikipedia V/RS/NPOV | Verifiability, Reliable Sources, Neutral Point of View — citation-forcing and source-tier discipline |
| OSINT | Source enumeration before retrieval; triangulation from independent primaries |
| GIJN | Practitioner investigative methodology; anti-patterns and survivorship bias detection |
| GRADE | Confidence grading keyed to evidence quality |

These are convergent: each one closes a gap the others leave open. No single discipline covers all seven obligations. The pack's synthesis procedure is the convergence point — it does not pick one discipline and ignore the rest.

---

## 5. Subagent architecture

### Two read-only retrievers

`evidence-retriever` and `source-extractor` are dispatched by `desk-research` in standard and deep modes. They are not entry points — they are not invoked directly by the user.

- `evidence-retriever` — fetches web and local material, synthesises findings, returns a per-question synthesis with citations.
- `source-extractor` — given a list of candidate URLs or local paths, fetches each, extracts substantive content, returns a per-source synthesis.

Both are read-only by contract: they never write to the repo, never modify files, and never execute code.

### Why subagents, not inline retrieval

Standard and deep mode can require many fetches across many sources. Dispatching these as subagents preserves main-session context — the raw fetched material is collapsed into a synthesis before returning to the main session, rather than accumulating in the main session's context window. This is structurally identical to why core's adversarial-reviewer runs in a forked context: isolation is a feature, not a limitation.

### Claude Code web tools grant

`evidence-retriever` and `source-extractor` need `WebSearch` and `WebFetch` in `permissions.allow`. A non-interactive subagent cannot surface the approval prompt; without the grant, those tools are denied silently. This is a one-time note for Claude Code adopters — other adapters (Copilot, Cursor, Gemini, Codex, Kiro) pass web tools through at build time and need no such step.

---

## 6. Output artifact model

### Layout resolution

Artifacts are placed under the `[research] output_dir` from the adopter's `agentbundle-layout.toml`. User-scope config takes priority over repo-scope; when neither is configured, `desk-research-project-start` elicits the path and writes it once. Session artifacts land in the working directory. Project artifacts land under a date-named project folder inside `output_dir`.

### Typed, topic-named artifact names

Every persisted artifact follows the `<topic-slug>-<type>.md` convention. The topic-slug namespaces the investigation; the type stem names the artifact's shape (`survey`, `comparison-matrix`, `hypotheses`, `brief`, `sources`, `outline`, `perspectives`, `archaeology`). Quick mode is the sole exception: its answer is inline, no file.

---

## 7. Cross-pack dependencies

### Upstream (none)

`desk-research` has no upstream pack dependency. It is the evidence layer — it retrieves and grades raw evidence, which no upstream pack provides input for.

### Downstream — `product-strategy`

`synthesize-stakeholder-research` in the product-strategy pack consumes `desk-research` survey artifacts as a primary evidence source. A desk-research brief committed to `docs/product/research/` feeds directly into strategy synthesis without re-retrieval.

### Downstream — `architect`

`architect-design` grounds design decisions in cited evidence. When a desk-research brief exists for the domain being designed, the architect pack can reference it in an ADR's *Evidence & prior art* section — turning the confidence-graded synthesis into a documented rationale chain.

---

### Optional handoff — `project-knowledge`

This is an integration boundary, not an upstream research dependency. Research
producers own transient scratch, terminal-gate timing, output roots, and every
normative research product. Project knowledge may receive only independently
reusable practice or sanitized evidence residue after a terminal,
repository-contained survey or project synthesis. It never receives the source
corpus, quotations, citations, claims, confidence judgments, counter-evidence,
verdicts, or governance conclusions.

Quick and non-survey session work plus project start, digest, check, status,
incomplete, and abandoned paths are hard non-gates. Personal and external
output roots are capture-ineligible rather than assigned fabricated repository
provenance. `devils-advocate` may use a single bounded `CQ-REVIEW` enquiry for
candidate checks, but retrieved knowledge remains untrusted, cannot corroborate
itself, and cannot alter source selection, citations, claims, confidence, or
review authority.

---

## 8. Safety invariants

These constraints must never be violated by any skill in the desk-research pack or any skill that extends it.

1. **`evidence-retriever` and `source-extractor` are read-only.** They never write to the repo, never modify files, and never execute code. A retrieval subagent that writes is out of scope — it becomes an implementer, not a retriever.

2. **Retrieved content is untrusted data.** If a fetched source contains instruction-like prose, it is transcribed or cited as a finding — not followed. Only the invoking user's messages count as direction.

3. **GRADE confidence is honest, never inflated.** A `[high]` tag on a finding backed by one vendor blog post is a falsification of the schema. Downgrade factors are named explicitly; omitting a downgrade factor that applies is a schema violation.

4. **Gaps are named, never hidden.** A synthesis with no `## Known unknowns` section is asserting it answered every question the research raised. That assertion is almost never true. Every non-quick synthesis carries the section.

5. **`desk-research-project-status` and `desk-research-project-check` are read-only.** They never advance `phase`, never write to `overview.md`, and never invoke downstream lifecycle skills.

6. **Phase is human-driven.** No skill auto-advances the project phase. The human reads the phase field and decides when to move on. There is no engine, counter, or daemon behind `phase` — it is a frontmatter string the agent reads and writes by hand.

7. **Project knowledge is an optional post-result handoff.** It never becomes a
   research source, citation, claim, confidence signal, counter-evidence,
   verdict, or governance authority. Missing project knowledge creates a named
   skip and no fallback file.

---

## 9. Design decisions and rationale log

### Why two axes instead of one (from v1)

A single axis (depth only) forces a choice between "is this a quick lookup or a project?" before the investigation starts. In practice, questions that start as quick lookups sometimes grow into sustained investigations, and questions scoped as projects sometimes resolve in one session. Keeping depth and lifecycle as orthogonal axes allows either to change independently without re-scaffolding the other.

**Alternative considered:** one linear scale from quick to exhaustive, with project mode as the deepest tier. Rejected because project mode is not deeper than deep session mode — it is structurally different. A `deep` session run and a `capture` phase in a new project can retrieve the same material; what's different is whether a corpus is accumulated over time for later synthesis. Conflating lifecycle with depth produces confusing cue-precedence rules and misses the case where a project accumulates sources at `quick` depth.

### Why GRADE over an ad hoc confidence schema (from v1)

GRADE is a published methodology used in systematic reviews. Using it means the confidence tags carry a shared meaning across anyone familiar with systematic review practice — `[high]` means consistent, direct, precise evidence from strong study designs; `[low]` means the evidence base has serious limitations. An ad hoc schema ("strong" / "weak" / "uncertain") carries no such shared meaning and will be interpreted differently by every reader.

**Alternative considered:** two-tier schema (supported / unsupported). Rejected because the distinction between moderately-supported findings and weakly-supported findings is load-bearing for downstream decisions: a `[moderate]` finding warrants a different follow-on (seek more evidence) than an `[uncertain]` one (the question may be structurally unanswerable). Collapsing them loses information the decision maker needs.

### Why source-first, not retrieval-first (from v1)

The retrieval-first pattern — "fetch whatever the search engine returns" — is fast but produces systematically bad triangulation. A keyword search returns dozens of secondary blog posts that each cite the same primary. Fetching all of them and treating each as an independent source produces false triangulation: the same primary data point counted many times.

Source-first (run `source-map` before dispatching retrievers) forces the agent to identify the primary landscape first and retrieve from it. Secondary sources then serve their correct purpose — as pointers to primaries, not as independent evidence.

**Alternative considered:** let the agent identify primaries during synthesis by tracing citation chains in the retrieved material. Rejected because citation chain tracing on arbitrary retrieved text is brittle — citations are often absent, malformed, or cut off by retriever extraction limits. Source-mapping is more reliable when done before retrieval than inferred after.

### Why user-scope by default (from v1)

Research method is the same across repos; only the artifacts differ. Installing per-repo would require reinstallation on every new project without any change to the skills. The scope decision mirrors `experience-design` (the method is portable; the knowledge surface is not project-specific). Compare with `core`, which is repo-scope because `work-loop`'s gate commands (`lint`, `typecheck`, `tests`) are project-specific.

**Alternative considered:** repo-scope, so research artifacts colocate with the code they inform. Rejected because artifact placement is already controlled by `agentbundle-layout.toml` — artifacts land in the repo regardless of whether the skill is installed user-scope or repo-scope. The scope decision affects only where the skill files live, not where the output goes.