researching-prior-art

Researching Prior Art

Gather verified external evidence for one technology decision, in parallel, without touching the working tree outside docs/research/ and .superpowers/research/. Evidence only — this skill never chooses an approach.

When invoked by brainstorming, never ask the user anything — all user interaction already happened at brainstorming's research gate. The one exception: invoked directly by the user without an explicit N, present the gate message below yourself to obtain N (the user is the invoker; no gate has happened yet). Never pick N silently.

On every invocation path — whether the gate message below is shown or not — a non-zero N ends, on success, with findings cached under docs/research/ and committed to the currently checked-out branch in this repository, unless HEAD is detached, in which case the commit is skipped and the cache stays uncommitted on disk (step 6 item 5, sub-step 5e). State this to the invoker before that commit can run.

On that direct path, present this gate message verbatim — the same block brainstorming presents, copied character-exactly (<candidates>, <S>, and <branch> filled in — the backticks around them are placeholder markup, dropped with the angle brackets when the values are filled; the bracketed sentence appears only when the choice is difficult to reverse):

Research gate: this decision triggers prior-art research. Candidates: <candidates>. [This choice is difficult to reverse — consider a higher N.] How many research subagents should I dispatch? Suggested N=<S> (number of candidates + 3, at most 10). Reply with a number, or 0 to skip — a skip is recorded in the spec. On a non-zero reply, findings are cached under docs/research/ and committed to this repository, on the branch checked out right now (<branch>).

A direct invocation usually has no spec. On a 0 reply, state the skip in the conversation and stop; record it in a spec's "Prior art and alternatives" section only when a spec exists. <branch> = the name of the branch checked out at the moment the gate fires, resolved like this: first run git rev-parse --git-dir at the repo root. A non-zero exit means this is not a git repository — fill <branch> with the text not a git repository — the cache will not be committed and stop there; do not run git symbolic-ref -q HEAD in that case, its exit status does not distinguish a non-git project from a detached HEAD. When git rev-parse --git-dir succeeds, next run git symbolic-ref --short -q HEAD. A non-zero exit here means HEAD is detached — fill <branch> with the text detached HEAD — the cache will not be committed. A zero exit means HEAD is attached to a branch, and the command's output is the branch name: <branch> = that output. This works on a branch with no commits yet (a repository right after git init). Never use git rev-parse --abbrev-ref HEAD for this: on a detached HEAD it prints the literal string HEAD, and on a branch with no commits it fails and still prints HEAD, so in both cases its output looks like a branch name and is not one. A negative or non-numeric reply → ask once more; a second unusable reply → treat it as a skip, exactly as a 0 reply: state the skip and stop, and never fall back to the suggested <S>. A non-zero N dispatches researchers and ends with a commit to the user's checked-out branch, and a user who twice answered something other than a number has not agreed to either. This is the same rule brainstorming applies at its gate.