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