/sw-research

name: sw-research
description: >-
  Deep outward-facing research. Investigates external documentation, APIs,
  industry patterns, and best practices. Produces validated research briefs.
argument-hint: "[topic or question to research]"
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Task

Specwright Research

Goal

Produce validated, referenced research briefs as input to the design phase. Focus is outward — external docs, APIs, SDKs, industry patterns. Output is facts and evidence, never design opinions. Operates fully autonomously — briefs are consumed by sw-design (which has its own gate).

Inputs

• Research topic(s) from argument or conversation context
• `{projectArtifactsRoot}/research/` — existing briefs (for deepening or refresh)
• `{projectArtifactsRoot}/CHARTER.md` — technology vision (for relevance filtering)

Outputs

• `{projectArtifactsRoot}/research/{topic-id}-{YYYYMMDD}.md` per `protocols/research.md`

Constraints

**Stage boundary (LOW freedom):** Reads and researches. NEVER writes code, branches, mutates workflow state, or produces design artifacts. No `currentWork`, no lock. Can run anytime. It is not a core workflow stage and never claims top-level work ownership.

**Triage (MEDIUM freedom):**

• Break request into 1-5 tracks. Derive tracks from the argument + existing gaps.

Apply `protocols/decision.md` DISAMBIGUATION if topic is ambiguous.

• Assign output shape per track (API contracts, pattern comparison, claim verification,

domain survey). If no topic provided, infer from recent conversation context.

**Research (HIGH freedom):** Delegate to `specwright-researcher` per `protocols/delegation.md`. One call per track. Parallel if Agent Teams available. Cite all sources with URLs. UNFETCHED → noted, not fabricated.

**Synthesis (MEDIUM freedom):** Merge findings. Score confidence: HIGH (official docs, multiple sources), MEDIUM (reputable secondary), LOW (single, unverified). Tag LOW/MEDIUM as potential assumptions. Flag open questions honestly.

**Auto-approval (MEDIUM freedom):** If all tracks have ≥MEDIUM confidence: auto-approve and persist the brief. Low-confidence tracks noted in the brief for consumer awareness. Briefs are consumed by sw-design which validates findings at its own gate.

**Persistence (LOW freedom):** Write to `{projectArtifactsRoot}/research/{topic-id}-{YYYYMMDD}.md`. Overwrite same topic+date. Max 10 briefs. If at cap: log warning, list by date, suggest cleanup. Briefs older than 90 days are STALE — warn when loading.

Protocol References

• `protocols/decision.md` -- autonomous decision framework (DISAMBIGUATION, auto-approval)
• `protocols/research.md` — brief format, staleness, lifecycle
• `protocols/delegation.md` — agent delegation

Failure Modes

| Condition | Action | |-----------|--------| | No topic | Infer from conversation context. If undetermined, STOP. | | Researcher returns no findings | Note as "no results" for that track | | Source cannot be fetched | Mark UNFETCHED; do not fabricate | | All tracks LOW confidence | Persist with prominent warning. Consumer decides. | | Research directory at cap | Log warning, list briefs by date | | Compaction | Re-run from scratch |