swe-research

Pipeline

swe-shape → swe-spec → [swe-plan] → [swe-worktree] → swe-execute → swe-review. This skill is not one of those stages: it runs at any point, standalone or delegated by any of them, often several times between two stages.

• This stage: answer one concrete factual question and preserve the evidence.
• Reads: the repository, external sources, the existing corpus, and any artifact the caller supplies.
• Writes: a subject report in the shared corpus, plus artifacts.
• Next: return the answer to whoever asked. The caller decides what to do with it.

Purpose

Answer a concrete engineering question with evidence, and add that evidence to a shared, long-lived research corpus so later changes reuse it instead of rediscovering it.

Research returns evidence to the caller; it does not change product intent, design, or contracts.

Invoke when the answer is worth preserving. Ordinary reading — "what does this function do", "where is this defined" — is not research and needs no artifact. Research is for questions whose answer another change, or another agent, would otherwise have to rediscover: how an external API actually behaves, what the blast radius of a change is, whether a dependency supports something, why a subsystem works the way it does.

Corpus

One shared corpus per repository, organized by subject, not by question:

.swe/research/
  INDEX.md                      # generated — never edit by hand
  <subject-slug>/
    report.md
    artifacts/

There is no per-change research directory. Findings about an API, a subsystem, or a dependency outlive the change that prompted them, and changes in the same repository overwhelmingly ask about the same domain and the same external services. A change references the reports it relied on from its own brief.md and spec.html.

A subject is a thing you can keep learning about: sec-edgar-api, tenant-resolution-middleware, legacy-dto-usage, postgres-jsonb-indexing. It is not a single question. report.md holds a standing summary plus dated findings; artifacts/ holds only what is needed to inspect or reproduce the evidence — probe scripts, captured responses, fixtures, benchmark output, query results. Omit artifacts/ when repository paths and cited sources fully support the answer.