research

Files (1)

• SKILL.md

SKILL.md (first lines)

# Research (QRSPI Step 3)

**PRECONDITION:** Invoke `qrspi:using-qrspi` skill to ensure global pipeline rules are in context. (Idempotent on session re-entry. Subagents are exempt — SUBAGENT-STOP in using-qrspi handles that.)

**Announce at start:** "I'm using the QRSPI Research skill to investigate the research questions."

## Overview

Objective exploration driven by the research questions. Gathers facts, not opinions. Each question gets a focused specialist agent with the right tools for its research type. Research isolation is structural — no research subagent ever sees `goals.md`.

## Artifact Gating

**Required inputs:**
- `questions.md` with `status: approved`

If `questions.md` doesn't exist or isn't approved, refuse to run and tell the user to complete the Questions step first.

Read `config.md` from the artifact directory to determine whether second-model reviews are enabled. If `config.md` doesn't exist, default to `second_reviewer: false`.

<HARD-GATE>
Do NOT pass goals.md to ANY research subagent, including the collation subagent.
Research isolation is structural — this is not optional, not a judgment call.
If a subagent prompt contains goals.md content, the isolation invariant is broken.
</HARD-GATE>

## Execution Model

**Parallel specialist subagents** (ISOLATED — structurally enforced). One subagent per question (or per small group of related questions). A collation subagent assembles the per-question `## Summary` blocks into `_collated.md` at the end; the orchestrator then renames `_collated.md` to `summary.md` via a single `mv` Bash call.

**CRITICAL: `goals.md` is deliberately withheld from ALL research subagents.** This is enforced structurally — subagent prompts contain only the question(s) assigned to them. `goals.md` is never passed to any research subagent, including the collation subagent. This prevents confirmation bias.

## Process

### Dispatch

1. Parse `questions.md` — extract each numbered question with its research type tag
2. Group related questions (e.g., two questions about the same subsystem) to avoid redundant exploration
3. Dispatch specialist subagents based on research type tags:

| Research Type | Agent Tools | Focus |
|--------------|-------------|-------|
| `[codebase]` | File read, grep, glob | Read code, trace logic flows, map architecture. Report `file:line` references. |
| `[web]` | Web search, web fetch | Search competitors, libraries, best practices, docs. Report URLs and sources. |
| `[hybrid]` | All tools | Compare local implementation against external standards/alternatives. |

4. Independent questions run in **parallel** subagents (use the Agent tool with multiple concurrent calls)
5. Each subagent writes its own report directly to `{ABS_RESEARCH_DIR}/q{NN}-{type}.md` using the `Write` tool. The orchestrator passes the absolute path into the subagent prompt; subagents do NOT return findings as text. The `q*.md` filename pattern is intentionally outside the Claude Code 2.1.x subagent-guardrail blocklist (filenames whose stem starts (case-insensitive) with `report`, `summary`, `findings`, or `analysis`), so direct write succeeds.

### Per-Researcher Subagent

## Evergreen-Output Rule

Any artifact in the QRSPI run directory governed by `status: draft → approved` frontmatter promotion (goals, design, structure, phasing, plan, parallelization, roadmap, future-goals, and any future artifact adopting this lifecycle) describes the **current state** of decisions. The reader is a downstream agent or future maintainer.

*(Excludes by design: `SKILL.md` files — skills carry rule rationale legitimately; `feedback/*.md` — the designated home for dialogue exhaust; `reviews/**/*.md` — finding rationale; `config.md` — non-narrative.)*

**Litmus test (apply to every paragraph before write).** Two filters, in order:

1. Is the subject the **decision** (the thing being designed / planned / scoped)? → keep.
2. Is the subject the **document itself** — its drafts, its history, the dialogue that produced it, "us"? → cut.

A sentence that only makes sense as a delta from a prior state is **dialogue exhaust** — strip it.

**Permitted substantive content** (do NOT confuse with dialogue exhaust):

- Chosen approach and its rationale (inline)
- Rejected alternatives and tradeoffs, where the artifact template asks for them (e.g., design.md's `## Trade-offs Considered` — substantive content about the decision space, not about the document's history)
- Rationale embedded inline as one parenthetical when a downstream reader needs it

**Named antagonist patterns — strip on sight, substitute as shown:**

| Antagonist pattern | Recognize by | Replace with |
|---|---|---|
| Session / drafting notes | "Rule X drafting note," "this collapsed from 3 to 1 because…" | Nothing — delete. If a fact matters, embed inline in the decision. |
| Version-history narration | "earlier draft said X," "previously," "originally," "pre-cleanup" | Nothing — git history holds versions. |
| Inside baseball | text addressed to "us" / "the author," meta-explanation of the document's own structure ("this section is split into A and B because…") | The decision the structure expresses — without the structural explanation. |
| Compaction-loss recovery notes | "this nuance was almost lost during…" | Nothing — if the nuance is needed, the rule itself carries it. |
| Failure-modes-prevented lists | bullets that justify why a rule exists rather than state what to do | Strengthen the rule's wording; delete the justification list. |

Decision-process history (drafts, review rounds, feedback applied, compaction recovery) lives in feedback files, review findings, PR descriptions, and git history — never in the artifact.

**Inputs:** Only the assigned question(s) from `questions.md`. NO `goals.md`. NO raw `feedback/research-round-*.md` files (raw feedback may carry user goals/intent — forwarding it to a research subagent breaks the research-isolation invariant). The orchestrator also passes the absolute output path (`{ABS_RESEARCH_DIR}/q{NN}-{type}.md`) and, for grouped questions, the full set of question IDs the report should cover. On re-dispatch via Rejection path 2, the orchestrator passes a **sanitized defect summary** it authors itself from the user's feedback — defect-only bullet points (e.g., "missed the auth module", "TL;DR is missing", "broken file:line citation"). Goal-bearing or intent-bearing language is stripped before the summary reaches the subagent.

**Dispatch** — for each question (or grouped set of related questions), dispatch `Agent({ subagent_type: "qrspi-research-specialist", model: "sonnet" })` in parallel via concurrent Agent tool calls. The agent body (loaded by the runtime) carries the full research-agent rules, output-format template, and contract; the dispatch prompt carries only the parameters below.

Dispatch parameters (per specialist):

- `question_body`: wrapped body of the assigned `research/q*.md` question(s) between `<<<UNTRUSTED-ARTIFACT-START id=question>>>` and `<<<UNTRUSTED-ARTIFACT-END id=question>>>` markers; for grouped questions, all assigned question texts concatenated within the wrapper
- `output_path`: absolute path the specialist writes its report to (`<ABS_RESEARCH_DIR>/q{NN}-{type}.md`)
- `question_ids`: comma-separated numeric IDs the report should cover (e.g., `3` or `3,7`)
- `defect_summary` (re-dispatch via Rejection path 2 only): orchestrator-authored sanitized defect summary; goal-bearing/intent-bearing language stripped

**Direct-write contract (unambiguous default).** Per-researcher subagents write their `q*.md` report directly to `output_path` via the `Write` tool. They do **not** return report content as text. Text-return is not used anywhere in the research pipeline — the collation subagent also direct-writes (to the `research/_collated.md` staging filename, which the orchestrator then renames to `research/summary.md`). The staging-filename pattern exists precisely to avoid text-return through main chat. If the orchestrator ever omits `output_path` from a per-researcher dispatch, that is a dispatch defect — fix the orchestrator, do not fall back to text-return.

**Summary-last authoring order.** The per-question report template places the structured summary block (TL;DR / key findings / surprises / caveats) at the **top** of the file — that is the consumer-facing reading order. Authoring order is the inverse: investigate first, draft the full report body, then author the summary block **last**, then place it at the top of the file. Do not generate the summary from intent before the body is complete.

**Research-isolation invariant** — the specialist dispatch carries NO `companion_goals`, NO other-question content, and NO `feedback/research-round-*.md` files. This is structurally enforced — the agent body refuses goals.md / cross-question content if it ever appears in the dispatch prompt. Research isolation prevents confirmation bias.

### Citation-Density Post-Validation Hook (G5; trusted-model re-run path)

Every `qrspi-research-specialist` dispatch is observed at the dispatch boundary by a post-output citation-density validator. The validator runs AFTER the specialist's `q*.md` report is written and BEFORE the report is read by the collation subagent or any downstream consumer. The floor that the validator measures against is the `validators.citation_density_floor:` key in `config.md` (default `0.05` — see the schema documentation in `skills/using-qrspi/SKILL.md` (T01) for the key's full semantics, the citation-counting rule, and the rationale for the default value).

**Above-floor result.** The report proceeds unchanged. The collation subagent reads it on the same schedule as any other specialist output. No re-run, no diagnostic, no telemetry rerun-count increment.

**Below-floor result (first occurrence).** The dispatch re-runs the specialist EXACTLY ONCE on the trusted model (the role's `trusted_path:` route from `config.md`'s `model_routing:` table, OR the trusted-tier default from the routing matrix in `skills/implement/SKILL.md` § G5 Initial Routing Matrix). The re-run carries identical `question_body` and `question_ids` parameters as the original dispatch — only the `(provider, model)` pair changes. The orchestrator increments the per-task `citation_density_rerun_count` field in this task's telemetry record (see `skills/implement/SKILL.md` § Per-Task Telemetry Emission).

**Below-floor result (re-run also below floor).** The validator emits a loud diagnostic naming the below-floor density value, exits non-zero (propagating the failure signal to the Implement orchestrator), and does NOT silently forward the below-floor output to downstream consumers. The non-zero exit is observably distinct from the success path — it is NOT a zero-exit-with-empty-body. The Implement orchestrator treats the non-zero exit as a specialist-dispatch failure and may retry on a different topic angle, escalate to opus, or proceed with degraded output per its BLOCKED escape hatch; the validator never silently degrades.

The dispatch-wrapping contract that consumes this hook (when the wrap fires, how the telemetry rerun-count is incremented, what the orchestrator does with the non-zero exit) is authored in `skills/implement/SKILL.md` § Specialist Citation-Density Validator. This Research section documents the producer-side hook contract that Implement consumes.

### Collation Subagent (verbatim extraction, not synthesis)

After all per-question research completes, dispatch a **lightweight collation subagent** whose ONLY job is to extract the `## Summary` block from each `q*.md` file verbatim and assemble them into the staging file `research/_collated.md` (which the orchestrator subsequently renames to `research/summary.md` via a single `mv` Bash call). This is mechanical extraction — not synthesis, not re-prose. Each per-question report already carries a structured TL;DR / Key findings / Surprises / Caveats block at its head (see Per-Researcher Subagent template above); the assembled output is just those blocks stitched together in question order, plus a short Cross-References section.

**Why a collation subagent (not orchestrator-direct, not synthesis):**

- **Context hygiene.** The collation subagent reads all per-question `q*.md` files into ITS context, then exits. Main chat never loads the full report bodies. If main chat did the collation directly, all `q*.md` contents would persist in main chat's conversation history and slow every downstream stage — Design proposes better architecture on a lean context.
- **No re-synthesis.** Verbatim extraction is bounded mechanical work; re-prosing the per-question reports into one risks interpretive spin not present in the originals. The per-question `## Summary` blocks are the canonical at-a-glance summary by contract.
- **Guardrail-compatible direct write via staging filename.** `summary.md` matches the Claude Code 2.1.x subagent-guardrail blocklist (filenames whose stem starts (case-insensitive) with `report`, `summary`, `findings`, or `analysis`), so the subagent cannot Write to it directly. To avoid text-return (which would route the assembled content through main chat's context, defeating the hygiene goal), the subagent instead writes to a **staging filename outside the blocklist** — `research/_collated.md` — and the orchestrator then renames it to `research/summary.md` with a single `mv` Bash call. The `mv` adds only the command string and a tiny confirmation to main chat's context, not the file body. The public artifact name (`summary.md`) is unchanged, preserving all downstream references in other QRSPI skills.

From dfrysinger/qrspi-plus, MIT.

More from dfrysinger/qrspi-plus