Research

Research command

Contract

Refusals

• Codebase-internal research: dispatch a scout subagent. This skill researches external libraries, frameworks, and services.
• Assertions derived solely from training data without a [Speculative] label: rejected. Every factual claim must cite at least one source URL or doc path.
• Returning without writing the artifact: rejected. Do not return without writing the artifact.

Inputs

Subject (required): the library, framework, SDK, API, CLI, or service name extracted from the user request. Version (optional): pinned version string if stated, e.g. pydantic@2.7. If unstated, resolve latest stable at Tier 1. Target path (optional): preferred output directory. Defaults to docs/research/ if it exists, else .outline/research/.

Procedure

1. Identify the subject. Extract the canonical name and version from the user request. Capture version if stated. If unstated, note "latest stable" and resolve from Tier 1. Done when: the canonical name and resolved version are recorded.

2. Dispatch a background subagent via task with self-contained instructions: subject, version, source ladder requirements, target artifact path. The worker owns completion and writes the artifact. Done when: the artifact is written to disk, or the worker reports BLOCKED with a named failure class.

3. Walk the 5-tier source ladder inside the subagent. Resolve the canonical name from official docs, then probe tiers in priority order. Proceed to the next tier only on hard failure (source unavailable, no results, non-authoritative). Record skipped tiers.

   Tier	Priority	Source type
   1	Highest	Official docs: library/framework documentation site, SDK reference pages
   2	High	API refs: reference pages, repository README and docs folders, and source code
   3	Medium	Books/papers: RFCs, academic papers, vendor whitepapers, standards documents
   4	Low	Tutorials: tutorial articles, blog posts, vendor how-to guides
   5	Lowest	Community: repository issues and discussions, forums, Q&A threads

   Done when: all tiers are probed, the first authoritative match is found and recorded (primary-source-only mode), or a hard failure stops the ladder.

4. Cite every claim. Every factual claim must cite at least one source URL or doc path. Assertions derived solely from training data must carry [Speculative — training data only]. Done when: every claim has a citation or speculative label.

5. Write the artifact. Persist all findings into a single Markdown file at the target location. The file name is a slug of the subject. Done when: the artifact is written to disk.

Primary-source-only mode

When the task needs primary-source reading, restrict the ladder to its strictest tier: search only authoritative primary sources (Tier 1 official docs, and Tier 2 API refs, repository README/docs folders, and source code). Stop after the first authoritative match; do not iterate the rest of the ladder. Every factual claim must link to its owning primary source URL or file path, and each citation must uniquely own the claim it annotates. A claim that cannot be sourced from a primary source is written with the label [Unverified — no primary source available] and the gap is left unfilled; never substitute a community, tutorial, or non-authoritative source to close it. If a primary source is unreachable, stop after one retry rather than dropping to a lower tier. If the target write fails, delete any partial file before reporting. This mode never widens beyond primary sources; the lower tiers (3-5) are not probed.

Failure and recovery

• ladder-exhausted: no authoritative source found after Tier 5; surface all attempted tiers and any partial findings.
• invalid-output: artifact missing required fields, unparseable, or not written to the target path.
• task-dispatch-failed: background subagent could not start or returned no result.
• Partial-result rule: when the background subagent partially succeeds (artifact written but claims sparse), return the artifact path and list the specific gaps.
• Blocked/non-converged result: if no artifact can be written, return BLOCKED: <named failure class> with the specific blocking reason. Do not pretend the done predicate holds.

Output

A single cited Markdown artifact (<subject-slug>.md) with subject id, source-cited claims with confidence labels (Verified for Tier 1-2, Probable for Tier 3-4, Unverified for Tier 5, Speculative for training data only), and open questions listing attempted tiers, ordered: subject id, claims, open questions.