<!-- source: openspec/current/muse/research.md -->

---
title: Muse Research
status: stable
owner: pavel
audience: [founder, executor]
tldr: The muse research subcommand family turns a falsifiable thesis into a structured Inquiry — a multi-stream desk-research artifact with promoted Findings.
---

# Capability — `muse research`

The `muse research` subcommand family turns a falsifiable thesis into a
structured **Inquiry** — a multi-stream desk-research artifact with promoted,
falsifier-bearing Findings. It operationalises the manual 4-parallel-agent
research pattern (first run 2026-05-13) into a headless, repeatable CLI.

Shipped via `openspec/archive/2026-05-21-add-muse-research-mode/` (RAP-907,
Phase 2 — Waves 1-4: RAP-921 / 922 / 923 / 924). Code lives at
`packages/muse/bin/muse/commands/research/`.

## Why this exists

Research is the studio's only **compounding** asset: accumulated, structured
thinking is the moat that cost, scale, and technology cannot replicate. The
manual research pattern worked but only inside an interactive Claude Code
session — not headless, not Linear-tracked, not repeatable. `muse research`
removes that ceiling.

## Subcommand family

```
muse research scope <slug>       Create an Inquiry file from a thesis
muse research run <slug>         Execute research streams in parallel
muse research synthesize <slug>  Consolidate streams into promoted Findings
muse research review <slug>      AI-as-reviewer pass (devil's-advocate)
```

Canonical happy path: `scope → run → synthesize → review`. Each step is
idempotent and re-runnable; state lives in the markdown Inquiry file.

### `scope`

Creates `openspec/_methodology/research/inquiry-<slug>.md` with frontmatter
per the Inquiry output contract. Validates the thesis (10–300 chars) and
capability-refs (each must resolve under `openspec/current/`). Idempotent —
fails `slug_exists` unless `--force`.

**`--kind public` config-check.** A `kind = public` Inquiry requires model
rotation at review time (see Binding invariants below). `scope --kind public`
therefore verifies a second model class is configured (`MUSE_REVIEWER_MODEL_CLASS`,
distinct from the primary `--model`) **at scope time** — failing immediately
with `public_requires_second_model_class` rather than letting the author
invest `run` + `synthesize` cost into an Inquiry that cannot reach
`published_to_world`.

### `run`

Spawns one parallel sub-agent per **canonical thesis framing** —
`architecture`, `strategy`, `metric`, `decision-history`. `--framings`
selects a subset (default: all four); not every thesis benefits from all
four. Each sub-agent runs web search under a depth-bounded budget
(`--depth shallow|medium|deep`), grades sources on the credibility-4-tier
rubric (`experimental | engineering_claim | marketing | discourse`), and
appends a contribution to the Inquiry's `## Triage` section. A pre-flight
cost estimate refuses with `cost_cap_exceeded` above `--max-cost-usd`
(default $5). Partial failure is tolerated — surviving streams proceed; a
failed stream is recorded `status=rejected, reason=stream_failed`.

### `synthesize`

Consolidates all stream contributions into a `## Findings (promoted layer)`
section. Each promoted Finding carries a **mandatory falsifier** — a finding
without a concrete, checkable falsifier is an opinion, not a finding. Emits a
`Thesis result` verdict (`supported | falsified | inconclusive`) into
frontmatter. Idempotent — re-running overwrites the prior synthesis.

### `review`

An AI agent in devil's-advocate mode reviews the Inquiry before ratification,
producing `inquiry-<slug>-review-round-<N>.md` (N auto-increments).

## Binding invariants

### §4.1 — Synthesis context-rot guard

Synthesis input is capped at **30K tokens**. Under the cap, synthesis is a
single flat pass. Over the cap (typically `--depth deep`), synthesis runs
**hierarchically** — contribution blocks split into two groups, each digested,
then a final pass over the two digests — keeping every model call under the
cap. A research mechanism premised on "scaffolding beats raw context" must not
itself dump unbounded context into one model call.

### §3.4.1 — Model rotation for `kind = public`

For `kind = public` Inquiries, the reviewer model **class** MUST differ from
the class that authored the majority of contributions — else `review` refuses
with `same_model_class_review_forbidden`. Model class is `<vendor>:<family>`;
the version suffix is excluded (`claude-opus-4-8` and `claude-opus-4-9` are
one class — confirmation bias correlates with training corpus, not point
release). For `kind = internal`, rotation is recommended, not required;
same-model reviews are stamped with a methodological-disclosure note.

## Output contract

The Inquiry artifact is markdown at
`openspec/_methodology/research/inquiry-<slug>.md`. Frontmatter carries
`Status`, `Lead`, `Authors` / `Author_ids`, `Capability_refs`, `Thesis`,
`Kind`, and (post-synthesis) `Thesis result`. Body sections: `## Triage`
(append-only contribution log), `## Findings (promoted layer)`,
`## Companion to`, `## Feeds into`.

Markdown is canonical (per the `add-inquiry-entity` arc, P0.3-inherited).
The entity DB never shipped — see *Inquiry-entity arc re-deferred*
amendment below. `muse research` output stays in markdown indefinitely
under the `## Findings` + `Capability:` + `Grade` + `Falsifier` convention
established through the 2026-05-28 → 2026-05-29 empirical loop.

## Out of scope (later phases)

- **Phase 3** — Linear integration: `scope` auto-creates a sub-issue; `run` /
  `synthesize` post progress.
- **Phase 4** — ~~Inquiry-entity DB wiring~~ — re-deferred 2026-05-29; not
  on roadmap unless a revisit trigger fires (see archive amendment below).
- **Phase 5** — public surface: `publish-to-world` action + render at
  `rapoport.studio/research/<slug>`.

## Related specs

- `openspec/current/muse.md` — Muse AI substrate.
- `openspec/current/agents/muse.md` — Muse CLI agent spec (`draft` command).
- `openspec/archive/2026-05-29-add-inquiry-entity/` — the Inquiry domain
  entity proposal, archived as re-deferred (captured-idea memory).
- `openspec/archive/2026-05-29-add-inquiry-workflow-gates/` —
  research-lineage workflow gates, archived by inheritance with the entity
  arc; source of the §3.4 / §3.4.1 review discipline (the discipline itself
  is preserved here in this spec).

---

## Inquiry-entity arc re-deferred (applied 2026-05-29 from changes `add-inquiry-entity` + 3 siblings + `add-inquiry-workflow-gates`)

The 6-PR empirical-loop arc (#1884 → #1885 → #1903 → #1904 → #1906 → #1907)
concluded that the marker convention (`## Findings` section + per-section
`Capability:` tag + 4-tier `Grade` column + per-row `Falsifier` column)
addresses all three of the entity's original triggers at zero database
cost. Final scorecard (see archive folder for full measurement):

| Query | Convention | Entity (projected) |
|---|---|---|
| "findings about capability X" | 100% precision / 90% recall | 100% / 100% (requires DB) |
| "findings with credibility ≥ engineering_claim" | 100% / ~95% | 100% / 100% (requires DB) |

All 5 inquiry-arc change folders archived as re-deferred captured-idea
memory under the predecessor's pattern (`openspec/archive/2026-05-12-define-research-domain-entity/`):

- [`openspec/archive/2026-05-29-add-inquiry-entity/`](../../archive/2026-05-29-add-inquiry-entity/) — base entity proposal
- [`openspec/archive/2026-05-29-add-inquiry-visibility-model/`](../../archive/2026-05-29-add-inquiry-visibility-model/) — kind/visibility_kind
- [`openspec/archive/2026-05-29-add-inquiry-agent-grants/`](../../archive/2026-05-29-add-inquiry-agent-grants/) — InquiryAgentGrant RBAC
- [`openspec/archive/2026-05-29-add-inquiry-relationship-graph/`](../../archive/2026-05-29-add-inquiry-relationship-graph/) — InquiryRelationship lineage DAG
- [`openspec/archive/2026-05-29-add-inquiry-workflow-gates/`](../../archive/2026-05-29-add-inquiry-workflow-gates/) — workflow gates (re-defers by inheritance per its own banner)

**Revisit triggers (any one reopens the arc):**

1. Forge audit roles emit findings during a build that subsequent phases must read in the same build → real-time mutation requirement.
2. A second human operates on inquiries via Studio UI (triage, promotion, lineage navigation) → UI-driven workflow.
3. Corpus past ~200 inquiries AND grep-based retrieval shows >50% false-positive rate on common queries → vector-search-or-DB threshold; intersects with `add-knowledge-vector-store` RAP-1020.
4. Phase 3a measurement on real Forge build tokens demonstrates `search_inquiry()` over JSON irreducibly beats convention-based grep for ≥80% of build queries → Phase 3b worth pursuing.

Until one fires, the convention is canonical and this spec's "Output
contract" section above is the source of truth for what `muse research`
ships.

Full empirical justification: [`openspec/_methodology/research/inquiry-drift-coverage-retrieval-spike.md § 5.3`](../../_methodology/research/inquiry-drift-coverage-retrieval-spike.md).
