Qrspi

---
name: qrspi
description: Run a coding task through the QRSPI workflow — Questions, Research, Spec (Design + Structure), Plan, Implement — one self-contained artifact per phase under thoughts/<task-id>/, each phase a fresh session reading only that artifact. Use it to run a ticket through qrspi, to research-then-plan-then-implement work too big for one session, to set up or advance thoughts/ artifacts, tell which phase one is in, or review one before moving on, and when a session drifts past 40% context and needs compacting at a phase boundary.
---

# QRSPI

**Q**uestions → **R**esearch → **S**pec (Design + Structure) → **P**lan →
**I**mplement. Five letters, six phases: the "S" is two sessions, two artifacts.

## The one idea

Each phase burns whatever context it needs, then compresses what it learned into
**one markdown file on disk**. The next phase opens a fresh session and reads only
that file. Context stays under 40%, where models work best, and the artifacts
become a reviewable, diffable record of the decision.

```
Questions   ~20k burned    →  00-questions.md   (~3k)
Research    150-250k       →  01-research.md    (~7k)
Design      starts at 10k  →  02-design.md      (~4k)
Structure   starts at 4k   →  03-structure.md   (~3k)
Plan        starts at 7k   →  04-plan.md        (~13k)
Implement   starts at 7k   →  code + PR
```

These are the phase's own context. The harness adds a floor on top of every phase —
system prompt, tools, CLAUDE.md, installed skills and MCP servers — measured at ~56k on
the one run behind these figures (WB-1 in whipbench, #91); it depends on your setup.

## Six non-negotiable rules

1. **Fresh session at every phase boundary.** Never continue.
2. **The artifact is the only channel.** If it is not written there, it does not
   exist for the next phase.
3. **Artifacts are self-contained.** Repo-root paths, explicit symbols, line
   numbers — never "the file from before".
4. **The ticket does not enter Research.** Handing the agent the ticket makes it
   hunt for evidence supporting a solution it already assumed. It returns in Design.
5. **The 40% rule.** Past the threshold, stop and compact — do not push through.
6. **Do not outsource the thinking.** Every phase is a checkpoint where *you* correct.

## Phases

Budgets are guardrails on a 1M window: incoming context, then the alarm at which
you **stop and compact** — both counted above the harness floor.

| # | Phase | Input | Output | Effort | Budget / alarm |
|---|---|---|---|---|---|
| 0 | Questions | ticket | `00-questions.md` | `medium` | 20k / 40k |
| 1 | Research | `00` — **not the ticket** | `01-research.md` | `medium`, `low` subagents | delegate / 400k in the main loop |
| 2 | Design | `00` + `01` + ticket | `02-design.md` | `xhigh` | 50k / 100k |
| 3 | Structure | `02` | `03-structure.md` | `high` | 30k / 60k |
| 4 | Plan | `02` + `03` | `04-plan.md` | `xhigh` / `max` | 80k / 150k |
| 5 | Implement | `04` (one step) + `99` | code + PR | `high` / `xhigh` | 100k per step / 400k |

Spend effort where errors propagate: a wrong Plan multiplies across the whole
implementation, a wrong Research gets caught by the Design review.

## Running a phase

Artifacts live in `<repo>/thoughts/<task-id>-<slug>/` — `00-questions.md` through
`04-plan.md` plus `99-progress.md`. `<task-id>` is the Linear/Jira ID, so the
artifact stays traceable; the directory lives in the task worktree and gets
committed.

Load **only** `references/0N-<phase>.md` for the phase you are in: each holds that
phase's prompt and the artifact skeleton to fill. `05-implement.md` is a prompt
only — its output is code — and Implement keeps state in `99-progress.md`.

`/qrspi:new <TASK-ID> <ticket>` bootstraps; `/qrspi:next` prints the next phase prompt
at each boundary — or, when several Implement steps can run in parallel, an execution
plan of worktrees, prompts and merge order; `/qrspi:review <file>` reads one artifact for the weaknesses the
gates cannot see (`references/reviewing.md`). Implement finding an upstream artifact
wrong → `references/recovery.md`, one phase re-entered narrowly. Artifacts into a
reviewable PR → `references/landing.md`.

## The test that matters

> An agent with **zero context** must be able to execute `04-plan.md` without
> asking a single question.

If it cannot, the plan is incomplete — and you are about to pay a rework round that
costs as much as the entire Research phase.

The *why* (measurement, ratios, caching) is the `token-efficiency` skill; the *craft*
of filling a template so it survives the reset is the `handoff` skill.