questions

name	questions
description	Use when goals.md is approved and the QRSPI pipeline needs research questions generated — produces tagged questions that guide the Research step without leaking goals

Questions (QRSPI Step 2)

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 Questions skill to generate research questions."

Overview

Generate targeted research questions — query planning before any code is read. Separates "what we need to know" from "finding the answers," preventing unfocused research tangents. Questions are tagged by research type to dispatch the right specialist agents.

Critical constraint: Questions MUST NOT leak goals or intent. They should be neutral inquiries about how things work, not what we want to change.

Artifact Gating

Required inputs:

• goals.md with status: approved

If goals.md doesn't exist or isn't approved, refuse to run and tell the user to complete the Goals 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.

Do NOT generate questions without an approved goals.md. Do NOT pass goals.md to any research subagent — research isolation is structural.

Execution Model

Subagent (clean context). The subagent receives only goals.md.

Process

Question Generation Subagent

Inputs: goals.md

Task: Analyze goals to identify which codebase zones and external knowledge domains are relevant. Generate specific, objective research questions.

Research type tags:

• [codebase] — requires reading local code, tracing logic flows, understanding existing architecture
• [web] — requires web searches for competitors, existing tools, libraries, best practices, documentation
• [hybrid] — needs both local code reading and external research. Use ONLY when the question literally cannot be answered without both (e.g., "how does our auth token format compare to the JWT spec?"). Default to splitting into separate codebase and web questions instead.

Goal leakage rules:

• BAD: "We want to add real-time notifications — how do competitors handle this?" (leaks the goal)
• GOOD: "How do existing tools in this space handle real-time event delivery to clients?" (neutral inquiry)
• BAD: "How should we refactor the auth module?" (prescriptive)
• GOOD: "How does the auth module work? What are its dependencies and data flows?" (objective)

Greenfield detection: Run at the start of the question-generation subagent. Use the Glob tool with pattern **/*.{ts,tsx,js,jsx,py,go,java,rs,rb,swift,kt,cs,cpp,c,h}. If all results are inside node_modules/, vendor/, or .git/ directories (or if there are zero results), treat this as a greenfield project — replace all [codebase] questions with [web] questions about existing solutions, frameworks, and best practices. If source files exist outside those directories, proceed normally.

Output format for questions.md:

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.

---
status: draft
---

# Research Questions

1. [codebase] How does the auth module work? What are its dependencies and data flows?
2. [web] What are the most common OAuth 2.0 libraries for Node.js? How do they compare?
3. [codebase] How are API endpoints registered and routed? Trace the request lifecycle.
4. [hybrid] How does our session token format compare to the JWT specification?
5. [web] What are current best practices for rate limiting in REST APIs?

Review Round

Compaction checkpoint: pre-fanout. Reviewer dispatch reads questions.md + goals.md + the agent-embedded reviewer protocol; saturated context produces shallow findings. See using-qrspi ## Compaction Checkpoints for the iron-rule contract.

Call TaskCreate({ subject: "Recommend /compact (pre-fanout) — questions", description: "pre-fanout: reviewer dispatch reads questions.md + goals.md. User decides whether to /compact." }).

Apply the Standard Review Loop from using-qrspi/SKILL.md. Questions has no scope-reviewer (canonical artifact-tree contract — Questions is not in the scope-reviewer topology). Only the quality reviewer runs.

Dispatch the round through dispatch-agent's high-level entry. Run scripts/dispatch-agent.sh --step questions --round ${ROUND} --artifact-dir <ABS_ARTIFACT_DIR> (plus the per-skill --output-dir/--artifact/--agents flags below). High-level mode invokes scripts/review-prep.sh to emit <ABS_ARTIFACT_DIR>/reviews/questions/round-${ROUND}.diff and threads diff_file_path: into the reviewer prompt; the orchestrator runs no git diff Bash redirect of its own. When the artifact directory is not inside a git repository, review-prep skips diff emission and diff_file_path: is omitted. When using-qrspi step 12 narrows the base ref, pass --base-ref "$(cat reviews/questions/round-$((ROUND-1))-commit.txt)" so review-prep narrows against the prior round's per-round commit SHA (using-qrspi step 12 owns the SHA-format validation and the anchor-file-missing:/sha-format-invalid: halt directions before the SHA reaches git diff). Scope-tag narrowing (when active) reaches the reviewer as scope_hint: wrapped between <<<UNTRUSTED-SCOPE-HINT-START id=scope_hint>>> / <<<UNTRUSTED-SCOPE-HINT-END id=scope_hint>>> markers per the reviewer-protocol Reviewer Dispatch Contract.

The round's reviewers dispatch through the universal dispatch chain (scripts/dispatch-agent.sh → Task fan-out → scripts/await-round.sh). Set the per-skill dispatch parameters below, then include the shared reviewer-dispatch prose. Include the *-codex peer tags in REVIEW_AGENTS only when second_reviewer: true; otherwise list only the *-claude tags.

REVIEW_STEP="questions"
REVIEW_ROUND="${ROUND}"                                  # current review round (NN)
REVIEW_OUTPUT_DIR="<ABS_ARTIFACT_DIR>/reviews/questions/round-${ROUND}/"
REVIEW_ARTIFACT="questions.md"
REVIEW_AGENTS="quality-claude=qrspi-questions-reviewer,quality-codex=qrspi-questions-reviewer"

Reviewer Dispatch (shared)

With $REVIEW_STEP, $REVIEW_ROUND, $REVIEW_OUTPUT_DIR, $REVIEW_ARTIFACT, and $REVIEW_AGENTS set by the per-skill preamble above, run:

scripts/dispatch-agent.sh --step "$REVIEW_STEP" --round "$REVIEW_ROUND" \
  --output-dir "$REVIEW_OUTPUT_DIR" --artifact "$REVIEW_ARTIFACT" \
  --agents "$REVIEW_AGENTS"

dispatch-agent emits M lines on stdout (one per first-party reviewer; zero lines for a third-party-only batch). Each line has the form:

MODE=first_party TAG=<tag> SUBAGENT_TYPE=<agent-name> MODEL=<resolved-model> PROMPT_FILE=<absolute-path>

For every emitted spec line, invoke the Task tool with these arguments (parse the line as space-separated KEY=VALUE pairs; values contain no spaces):

• subagent_type = the SUBAGENT_TYPE value, verbatim
• model = the MODEL value, verbatim
• prompt = the literal string "DISPATCH_FILE=<PROMPT_FILE-value>" — a single-line env-var-style reference; the prompt argument has no other content

Invoke all M Task tool calls in parallel in one orchestrator response (one Task call per spec line). The reviewer agent body's first instruction is to Read its DISPATCH_FILE — do not pre-Read the file yourself; the dispatch context belongs in the subagent's window, not the orchestrator's.

Iron law (orchestrator-side dispatch contract): invoke the Task tool exactly once per emitted spec line, with SUBAGENT_TYPE, MODEL, and PROMPT_FILE copied verbatim. Skipping a line, deduplicating across lines, modifying any value, or substituting a different subagent_type is a contract violation. The dispatch manifest ($REVIEW_OUTPUT_DIR/.dispatch-manifest.json) records expected dispatches; the apply-fix step's "expected tag produced no output" diagnostic catches missed or mis-routed Task invocations.

Capture each Task return value to disk before draining. After each Task call returns, write the subagent's reply text (the full Task return string) to $REVIEW_OUTPUT_DIR/.dispatch/<TAG>.raw using the create tool, where <TAG> is the TAG value from the corresponding spec line. This is mandatory regardless of whether the subagent appeared to write per-finding files itself. Rationale: when a subagent cannot use the Write tool (read-only sandbox; missing allowed-tools entry; tool denial at runtime) it emits findings via the <<<FINDING-BOUNDARY>>> stdout contract instead. await-round.sh recovers those findings via a universal stdout-fallback that reads .dispatch/<TAG>.raw and pipes it through third-party-finding-splitter.sh; without the captured .raw file the fallback has nothing to work with and the round looks (incorrectly) clean.

After all Task tool calls return AND all .raw captures are written (Task tool is synchronous; first-party subagents with working Write tools have already written their per-finding files by this point), drain any third-party background dispatches and finalize the round:

scripts/await-round.sh --round-dir "$REVIEW_OUTPUT_DIR"

await-round is no-op-safe — first-party-only rounds still call it; it returns immediately after reading the manifest. It writes a small $REVIEW_OUTPUT_DIR/.round-complete.json summary and (for third-party dispatches OR any entry that produced no per-finding files but has a .dispatch/<TAG>.raw capture) materializes per-finding files via third-party-finding-splitter.sh. It does NOT echo captured subagent payloads (CD-1 #4 output-bound contract).

Then read $REVIEW_OUTPUT_DIR/.round-complete.json and the per-finding files as needed for apply-fix. The raw per-reviewer prompt content (assembled by dispatch-agent into PROMPT_FILE) never enters the orchestrator's context — only the small spec lines + the small DISPATCH_FILE references passed to Task.

Human Gate

Present the full content of questions.md inline — every question, every tag, verbatim. Do not summarize, show only headers, or present a condensed table. The user must see the complete artifact to give meaningful approval.

Always state the review status when presenting: either "Reviews passed clean in round N" or "Reviews found issues in round N which were fixed but not re-verified."

On approval, if reviews have not passed clean, note this and ask if they'd like a review loop before finalizing. Then write status: approved in frontmatter.

On rejection, write the user's feedback to feedback/questions-round-{NN}.md (see using-qrspi Feedback File Format), then launch a new subagent with goals.md + rejected questions.md + all prior feedback files (not just the latest round). After re-generation, the review cycle restarts.

Quick-Fix Auto-Approve Branch

When config.md carries pipeline: quick, the human-approval gate is skipped after any review round (initial or post-fix) that produces zero kept findings. When this branch fires, status: approved is written to questions.md frontmatter automatically without waiting for user input.

Verifier-gate precondition. "Zero kept findings" is satisfied only when the verifier has affirmatively confirmed the count — a vacuously-zero count from an undispatched verifier does NOT satisfy the gate and surfaces the round to the user as unverified (matching the HARD-GATE contract in skills/implement/SKILL.md). If config.md is missing or unreadable when this branch is evaluated, the auto-approve branch does NOT fire — the orchestrator surfaces a named diagnostic and falls through to the standard human-approval gate (fail-loud, not silent fallback to either pipeline mode). The gate passes when ANY of the following hold for the current round's directory (reviews/questions/round-NN/):

• At least one .score.md sidecar file exists in the round directory AND every sidecar evaluates to no kept-blocker findings per the verifier's scoring rubric (see agents/qrspi-finding-verifier.md and skills/implementer-protocol/SKILL.md). A zero-byte sidecar does not constitute verifier affirmation and the gate does NOT pass. Full sidecar schema validation is the verifier's contract (see agents/qrspi-finding-verifier.md); this skill assumes well-formed sidecars. OR
• A round-NN-verifier-disabled.md marker file is present in the round directory AND the marker conforms to the canonical schema defined in skills/implement/SKILL.md HARD-GATE (a marker failing schema validation, or whose round identifier does not match the current round, is treated as absent). OR
• config.md carries verifier_enabled: false. When this condition satisfies the gate, the orchestrator MUST append an audit-log entry before writing status: approved — recording: timestamp, run slug, step name (questions), and branch label (auto-approve-verifier-disabled-config). The audit entry is written to the cascade audit log if one exists, otherwise to the round directory. An attempt to auto-approve via verifier_enabled: false without successfully writing this audit entry MUST abort with a named diagnostic (fail-loud, matching the audit-write precondition philosophy in skills/implement/SKILL.md HARD-GATE). This path is a deliberate operator-level configuration, not a default; the round appears in the review log as verifier-disabled, not as a normal clean round.

When none of these hold (no sidecars with affirmative zero-kept-findings content, no valid schema-conforming marker for the current round, and verifier_enabled is absent or true), the gate does NOT fire; the review round surfaces to the user as unverified and the standard human-approval gate runs.

Post-fix round behavior. If a fix round still produces kept findings, the auto-approve branch does NOT fire. The orchestrator surfaces the remaining kept findings to the user. The branch fires only when the most recent review round — initial or post-fix — produces verifier-affirmed zero kept findings.

Full pipeline unchanged. When pipeline: full, the human-approval gate runs as before — the branch is inert and the user must explicitly approve.

Terminal State

If the artifact directory is inside a git repository, commit the approved questions.md and the reviews/questions/ directory (per-round per-reviewer files; see using-qrspi → "Commit after approval (when applicable)").

Compaction checkpoint: pre-handoff. Questions approved; the next skill (typically Research) reads questions.md + every prior approved artifact + reviewer findings on a fresh context. See using-qrspi ## Compaction Checkpoints for the iron-rule contract.

Call TaskCreate({ subject: "Recommend /compact (pre-handoff) — questions", description: "pre-handoff: next skill reads questions.md + prior artifacts + reviewer findings. User decides whether to /compact." }).

REQUIRED: Invoke the next skill in the config.md route after questions.

Red Flags — STOP

• A question reveals the user's intended solution ("how do competitors implement feature X that we want to add?")
• A question is prescriptive rather than exploratory ("how should we refactor X?" vs "how does X work?")
• A [hybrid] tag that could easily be split into [codebase] + [web]
• Questions only cover one research type (all codebase, no web, or vice versa) when the goals imply both
• Questions are too broad ("how does the app work?") or too narrow ("what's on line 42 of auth.ts?")
• Duplicate questions asking the same thing with different wording

Common Rationalizations — STOP

Rationalization	Reality
"The questions are good enough"	Run the review. Goal leakage is subtle — you may not notice it yourself.
"This question needs to be hybrid"	Default to splitting. Only use hybrid when splitting loses essential cross-referencing.
"We don't need web research for this"	Even existing-codebase changes benefit from knowing current best practices.
"The goals don't imply any codebase questions"	If you're modifying code, you need to understand the existing code. Check again.
"I can combine these into fewer questions"	More specific questions get better research. Don't over-consolidate.

Worked Example

Goal: "Add per-client rate limiting to the public REST API"

Good questions (no goal leakage):

1. [codebase] How does the Express middleware chain work? What middleware is currently registered and in what order?
2. [codebase] How are client identities resolved in the API? Is there an auth middleware that extracts client IDs?
3. [codebase] How does the application currently connect to and use Redis? What patterns are used for Redis operations?
4. [web] What are the current best practices for distributed rate limiting in Node.js applications?
5. [web] What Redis-based rate limiting algorithms exist (token bucket, sliding window, fixed window)? What are their trade-offs?

Bad questions (goal leakage):

1. [codebase] Where should we add the rate limiting middleware?
2. [hybrid] How can we use our existing Redis connection to implement rate limiting?
3. [web] What's the best rate limiting library for Express that uses Redis?

The bad questions reveal intent ("add rate limiting middleware"), assume decisions ("use existing Redis"), and seek recommendations ("best library").

Iron Laws — Final Reminder

The two override-critical rules for Questions, restated at end:

1. Questions must NOT leak goals or intent. A researcher reading only questions.md should not be able to infer what we're trying to build or change. Goal leakage produces confirmation-biased research downstream.

2. Questions are exploratory, not prescriptive. "How does X work?" is allowed; "How should we change X?" is not. Prescriptive questions presuppose conclusions that Design — not Research — should determine.

Behavioral directives D1-D4 apply — see using-qrspi/SKILL.md → "BEHAVIORAL-DIRECTIVES".