---
name: pstack-research
preamble-tier: 3
version: 0.2.0
description: |
  Research spike. Output is a research doc, not code. Frames the question
  via superpowers:brainstorming; optionally consults gstack /codex consult
  for cross-model second opinions during the spike. Optionally graduates
  to /pstack-plan or /pstack-anti-pattern. Use when asked to "research",
  "spike", "investigate", "/pstack-research", or "do a research spike".
triggers:
  - /pstack-research
  - research spike
  - investigate this
  - spike on
allowed-tools:
  - Bash
  - Read
  - Write
  - WebFetch
  - WebSearch
  - Skill
---

# pstack-research

Investigate a question. Output captures findings, not code.

## Skills orchestrated

| Skill | When |
|---|---|
| `superpowers:brainstorming` | Step 1 — frame the question rigorously before investigating |
| gstack `/codex consult` | Step 2 (optional) — second opinion when investigation hits a fork where multiple approaches are plausible |
| `pstack-plan` | Step 4 — when research graduates to a feature |
| `pstack-anti-pattern` | Step 4 — when research concludes "we should NOT do this" |

## Steps

### 1. Frame the question

Invoke `superpowers:brainstorming` to clarify:
- What are we trying to learn?
- Why now? (What decision does this unblock?)
- What's the cheapest evidence that would resolve it?
- What's explicitly out of scope?

A sharp question saves hours of investigation. Don't skip framing.

### 2. Investigate

Read code, search docs, fetch external references, run small experiments
(in `/tmp` or scratch worktree). Skip TDD discipline — this is exploratory.

**When you hit a fork** where multiple approaches are plausible (e.g.,
"library X vs library Y", "approach A vs B vs C"), optionally invoke
gstack `/codex consult` for an independent second opinion. Codex sees
only the question and the relevant code, so it can spot tradeoffs
without our session's framing bias.

Use sparingly — most research questions are clear once you've read
the relevant docs/code.

### 3. Capture findings

Create `docs/research/<topic>.md` from `${CLAUDE_SKILL_DIR}/../../templates/research.md`.

Required sections:
- Question (verbatim from Step 1)
- Findings (bullets — what we now know)
- Evidence (code/links/benchmarks/repro steps)
- Recommendation (action or no-action)
- Open questions (what's still unresolved)

### 4. Graduation prompt

Ask:

> "Research complete. Three paths:
>   1. Graduate to a feature → invoke `/pstack-plan` with this research doc as starting context
>   2. No-action — keep as reference; the doc remains in `docs/research/`
>   3. Abandoned — the research concluded against doing this; invoke `/pstack-anti-pattern` to log why so we don't reconsider without new evidence"

- If 1: invoke `pstack-plan` and pass the research doc path as input.
- If 2: leave the doc in place; the recommendation section is the artifact.
- If 3: invoke `pstack-anti-pattern` with the "Tried / Failed because / Decision / Search hooks" fields filled in from the research findings.

## Do not

- Do not write production code. Experiments in `/tmp` or scratch worktrees only.
- Do not file GitHub issues for the research itself; only when it graduates via `/pstack-plan`.
- Do not skip Step 1 (framing). A vague question wastes the spike.