# Domain Tools, Gates, and Output Templates

> Per-domain tool surface, reasoning gates, and synthesis output template.
> Load when domain has been detected (Step 1d) or when synthesizing
> (Step 10).

The four domains are detected from the user's question in Step 1d and
recorded as immutable in `research-spec.md ## Domain`. The detected
domain determines which tools each `apt-researcher` role gets, which
reasoning steps are enabled, and what shape the final `RESEARCH.md`
output takes.

## Domain detection signals

| Domain | Signals | Examples |
|---|---|---|
| **mechanistic** | physics, math, distributed systems, algorithms, deterministic engineering systems with provable behavior | "how does Raft handle leader election", "what does axle stiffness do to chassis dynamics", "is this algorithm O(log n)" |
| **empirical** | medicine, biology, nutrition, psychology, public-health, social science, anything where human variation dominates and replication matters | "does intermittent fasting cause muscle loss", "what's the effect of X on Y in older adults", "is supplement X effective" |
| **strategic** | tool/vendor comparison, market analysis, license/contract evaluation, anything where the answer depends on vendor disclosure + ecosystem health | "best embedded DB for offline-first 2026", "should we pick Vitest or Bun test", "is Turso safe to depend on" |
| **general** | catch-all when none of the above fit; usually broad knowledge questions or framing-questions | "what is consensus in distributed systems", "explain bitemporal databases" |

Ambiguous question → `general`. The user can override with explicit
flag (future: `--domain <name>`); for v1, signal-based detection is
authoritative.

## Per-domain tool surface

Each `apt-researcher` role gets the base tools (Read, Grep, Glob,
WebSearch, WebFetch, Context7) PLUS the domain extras below.

### mechanistic

| Tool | How invoked | Used by |
|---|---|---|
| arxiv search | `curl "http://export.arxiv.org/api/query?search_query=..."` | Retriever |
| PDF reader | `curl -o /tmp/x.pdf {url} && pdftotext /tmp/x.pdf -` | Builder, Skeptic, Retriever |
| Wolfram Alpha (if API key set) | `curl "https://api.wolframalpha.com/v2/query?..."` | Builder, Skeptic |

First-principles derivation: **ENABLED**. Builder and Skeptic may
produce derivations grounded in domain theory. Judge accepts them
into `claims.json` at `source_tier: derived-theory` (weight 0.6
in `uncertainty` formula).

### empirical

| Tool | How invoked | Used by |
|---|---|---|
| Crossref DOI resolve | `curl "https://api.crossref.org/works/{doi}"` | Retriever, citation audit |
| PubMed E-utilities | `curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/esearch.fcgi?db=pubmed&term=..."` | Retriever |
| PMC full-text fetch | `curl "https://eutils.ncbi.nlm.nih.gov/entrez/eutils/efetch.fcgi?db=pmc&id={pmcid}"` | Builder, Skeptic |
| Europe PMC fallback | `curl "https://www.ebi.ac.uk/europepmc/webservices/rest/search?query=..."` | Retriever |

First-principles derivation: **DEMOTED**. Builder/Skeptic may invoke
theory (mechanism, leucine threshold, etc.) but Judge demotes the
output to `source_tier: hypothesis` (weight 0.1). Hypotheses cannot
reach `confidence: high` regardless of how compelling the reasoning
sounds — only empirical evidence at `tier ≥ independent-test` can
elevate a claim to `high`.

Citation audit is **MANDATORY** every iteration (not every N) in
empirical domains. Every new citation MUST be DOI/PMID-verified
via Crossref or NCBI before promotion to `sources.json`. Failures
go straight to `suspect-citations.md` and the claim depending on
them is downgraded.

### strategic

| Tool | How invoked | Used by |
|---|---|---|
| GitHub releases | `gh release list -R {owner}/{repo} --limit 20` | Retriever |
| GitHub code search | `gh search code "..." --limit 20` | Retriever, Skeptic |
| License fetch | `gh api repos/{owner}/{repo}/license` or WebFetch raw LICENSE | Retriever |
| Changelog fetch | WebFetch `CHANGELOG.md` or `gh api repos/{owner}/{repo}/contents/CHANGELOG.md` | Retriever |
| Package metadata | `npm view {pkg} --json` / `pip show {pkg} --verbose` / `cargo search {pkg}` | Retriever |

First-principles derivation: **DISABLED**. "Derive whether libSQL is
stable from theory" is nonsense. Builder is instructed to synthesize
from sources only. If Builder produces a derivation-shaped output,
Judge rejects it with `## reason: derivation invalid in strategic domain`.

Vendor-only evidence is a spar trigger (see `overnight-loop.md`
§spar-triggers). Strategic domain treats vendor-doc as
`source_tier: vendor-doc` (weight 0.5) — NOT a high tier.

### general

Default tool surface. First-principles is **SOFT-ENABLED with
hypothesis demotion** — Builder/Skeptic may derive but Judge
demotes to `hypothesis` until empirical or primary-doc evidence
elevates the claim.

## Output gates (Step 10 — synthesis)

The synthesis template in `RESEARCH.md` has a common core (defined in
the main SKILL.md `## 10. Synthesize`) PLUS domain-specific sections.

### mechanistic

Add:

```markdown
## First-principles derivations

For each derivation accepted into the claim graph at
`source_tier: derived-theory`:

- **{derivation name}** — claim {C-id}
  - Premises: {what we assumed}
  - Steps: {compact derivation}
  - Cross-check vs sources: {which sources confirm/contradict the derivation}
  - Failure mode: {when does this derivation break?}
```

If a derivation contradicts an empirical source, the derivation is
flagged as bounded — Judge MUST note the boundary condition.

### empirical

Add (mandatory, non-negotiable):

```markdown
## Not medical / financial / safety advice

This research synthesis is informational. It is not a substitute for
professional advice from a licensed clinician, financial advisor, or
safety expert. Individual circumstances vary; outcomes that apply to
populations may not apply to any specific person.

## What this CAN'T tell you

- {Specific question the evidence does not address}
- {Specific population the evidence does not cover}
- {Specific interaction or confounder the evidence cannot resolve}

## Quality of evidence

For each cited study supporting a critical claim:

| Source | Design | n | Peer-reviewed | Replicated | Notes |
|---|---|---|---|---|---|
| {S-id} | {RCT/cohort/meta} | {n} | {yes/no} | {yes/no/unknown} | {note} |
```

Imperatives in the synthesis prose ("you should…", "do X", "avoid Y")
are STRIPPED by Judge. Empirical synthesis uses descriptive language
("evidence suggests…", "in the populations studied…").

If the synthesis would recommend a course of action affecting health,
finance, or safety, Judge inserts: "**Discuss with a qualified
professional before acting on this synthesis.**"

### strategic

Add (mandatory):

```markdown
## Conditional-tree recommendation

```
if {decision-relevant condition A}:
  → recommend {Option X}
  → reason: {1-line}
elif {decision-relevant condition B}:
  → recommend {Option Y}
  → reason: {1-line}
else:
  → no clear winner — {what's the unresolved question}
```

## Vendor-claim conflicts

For each option where evidence is vendor-only or vendors disagree:

- **{Option}** — {dimension}
  - Vendor claim: {what the vendor says}
  - Independent confirmation: {available | NOT AVAILABLE}
  - Risk if vendor claim is wrong: {what breaks}

## Decision blockers

Questions only the user can answer that change the recommendation:

- {Question} — affects: {which option(s)}
```

Single-winner output is **REJECTED** by Judge when evidence is
vendor-only across the deciding dimension. The skill produces a
conditional tree or explicit "no clear winner" — never a confident
universal recommendation in those cases.

### general

Add:

```markdown
## Outstanding gaps

- {Open question that the synthesis does not close}

## Recommended next reads

- {Source} — covers {what aspect}
```

## Mode-specific additions (orthogonal to domain)

Applied AFTER the domain gates. From the main SKILL.md `## 10.
Synthesize`, repeated here for the per-domain reader:

- **UNDERSTAND** → mental model section with mechanism + analogy
- **VERIFY** → verdict line (`confirmed | partially confirmed | false |
  contested | unknown`)
- **SOLVE** → candidate approaches table + `## Falsification status`.
  For code-domain SOLVE: blocks `CONVERGED` if no falsification was
  run (test / simulator / model-checker / formal-method sketch).
  Force STALLED with `## Cannot certify without falsification` and
  enumerate what falsification harness would be needed.
- **COMPARE** → dimensions × options matrix + per-cell evidence
  pointers (conditional-tree comes from the strategic domain gate)

## Tool-surface fallbacks

If a domain tool is unavailable in the current environment (e.g.
`gh` not installed, no network access for Crossref), the affected
role MUST report this in its output:

```
## Tool unavailable
- {tool name}: {why unavailable}
- Impact on this iteration: {what could not be done}
```

Judge records the missing capability in `iteration-log.md` and adjusts
stop-state evaluation: a STALLED verdict resulting from missing tools
gets `## Cannot resolve without` annotated with "tool {X} unavailable
in this environment". The user can resolve and `--resume`.
