rc-questions

Start a QRDS-PI cycle with a deep interview.

Task input: $ARGUMENTS

What this skill does

1. Understands the goal (ask if unclear, explore if enough context)
2. Pours the qrds-pi formula to create the phase bead graph with gates
3. Tactically explores the codebase to understand what exists
4. Grills the design with small, dependency-aware batches of questions
5. Provides a recommended answer for every question
6. Repeats batches as many times as needed until the design tree is resolved
7. Writes the complete Q&A into the questions bead and closes it

Prerequisites

• bd CLI installed (bd --version >= 1.0.0)
• .beads/ workspace initialized in the current project (bd init if not)
• gate registered as custom type (bd config set types.custom "gate")
• qrds-pi formula available in ~/.beads/formulas/

Steps

1. Verify prerequisites

bd --version
bd formula list | grep qrds-pi

If .beads/ doesn't exist, ask the user if you should run bd init. If the formula isn't found, tell the user to check ~/.beads/formulas/qrds-pi.formula.json.

2. Understand the goal

Read $ARGUMENTS. Determine whether you have enough context to explore.

If the input is substantial (a paragraph or more with clear intent): Skip to step 3. You know what to look for.

If the input is short or vague (a sentence, a few words, or empty): Ask the user to describe what they're trying to accomplish before exploring. You need to know the goal to know where to look.

"Before I explore the codebase, tell me what you're trying to accomplish and why. I'll figure out the specifics from the code."

Do NOT explore blindly. Get the goal first.

3. Determine work type and pour the formula

Infer the work type from the task description:

• bugfix: bugs, errors, crashes, regressions, broken behavior
• feature: adding, building, implementing new functionality
• research: evaluating, comparing, deciding, architecture decisions

Confirm with the user briefly, then pour:

bd mol pour qrds-pi --var name="<task title>" --var type="<work type>"

Capture the root epic ID. Read the full bead graph:

bd children <epic-id> --json

Parse the JSON to identify all bead IDs by title prefix:

• questions bead: title starts with "questions:"
• research bead: title starts with "research:"
• design bead: title starts with "design:"
• design-review bead: title starts with "design-review:"
• structured-outline bead: title starts with "structured-outline:"

Record ALL bead IDs — you'll need them in step 7.5 to enrich descriptions with concrete dependency references.

4. Tactical codebase exploration

Now that you know the goal, explore the codebase to understand what exists. This is NOT the deep research phase — that comes later in its own context window. This exploration is tactical: learn enough to ask smart questions.

What to look for based on work type:

For features: Where does this fit? What patterns exist? What adjacent code would be affected? What test infrastructure is in place?

For bugfixes: Where is the affected code? Can you see the bug? What tests exist? What changed recently in that area?

For research: What are the current implementations? What dependencies or constraints are visible in the code?

Use sub-agents for parallel exploration when the task touches multiple areas. Each sub-agent explores one area and reports back. This keeps exploration fast.

Example: task touches API + database + tests
- Agent 1: explore the API layer (routes, middleware, handlers)
- Agent 2: explore the database layer (models, migrations)
- Agent 3: explore the test setup (framework, fixtures, patterns)

5. Formulate and present questions (GRILL MODE, BATCHED)

Default stance: grill the design relentlessly until there is shared understanding. Walk down each branch of the design tree, resolve dependencies between decisions one-by-one, and provide a recommended answer for every question.

Ask questions in small, coherent batches. A batch should contain only the minimum set of questions needed to unlock the next branch of decisions. Do NOT dump the whole interview at once.

What to ask about (the model decides based on context — no templates):

• Things you CANNOT determine from the code: intent, priorities, constraints, preferences, acceptable trade-offs, edge case behavior
• Things where the code is ambiguous or could be interpreted multiple ways
• Things where you found something surprising or contradictory
• Scope boundaries: what's in, what's out, what's deferred

What NOT to ask about (you already know from exploration):

• What framework/language the project uses
• Where specific files or modules live
• What test infrastructure exists
• How existing patterns work

Presentation format:

Present your findings first (what you learned from exploration), then the current batch. This gives the user context for answering.

"Here's what I found in the codebase:

• [finding 1]
• [finding 2]
• [finding 3]

Questions — answer this batch in one go:

1. [question about intent/constraint] Recommended answer: [best current recommendation]
2. [question about scope boundary] Recommended answer: [best current recommendation]
3. [question about edge case preference] Recommended answer: [best current recommendation] ... N. [question about priority/trade-off] Recommended answer: [best current recommendation]

Reply instructions:

• reply accept to accept all recommendations in this batch
• reply with a number and your preferred answer to override a specific item
• reply with multiple numbered overrides if needed
• anything you do not mention will be treated as accepted as recommended"

Aim for 2-5 questions per batch, 7 max in unusually broad cases. If a batch is larger than that, it is probably not dependency-aware enough. If a single question is especially high-risk, ask only that question in the batch.

6. Collect answers (voice-optimized)

The user will likely answer via voice dictation — one long response covering multiple questions. Expect:

• Answers may be out of order
• Answers may skip some questions
• Answers may combine multiple questions into one response
• Answers may ramble or include tangential context (this is valuable)
• Answers may use different terminology than your questions
• Answers may simply say accept

Parse the response gracefully. Map answers back to questions even if they're not numbered. Extract the signal from imperfect speech-to-text.

Treat accept as acceptance of the whole batch.

If the user overrides only specific numbered items, treat every unmentioned item in that batch as accepted as recommended.

If a reply is ambiguous, preserve any clear accepts/overrides you can parse, then ask a narrow cleanup batch only for unresolved items.

If the answers unlock the next branch of decisions but new uncertainty appears, ask the next focused batch. If critical questions went unanswered, ask a tighter follow-up batch. Repeat as many times as needed until the decision tree is resolved.

Do not stop just because a fixed number of rounds has passed. Stop when the important branches are resolved well enough for research to proceed.

7. Write Q&A to the questions bead

Synthesize the full interview into a structured artifact. This is what the research phase reads — it must be self-contained.

bd update <questions-bead-id> --description "$(cat <<'EOF'
# Questions: <task title>

**Work type:** <type>
**Epic:** <epic-id>

## Codebase Context (from exploration)

- <what exists today — files, patterns, frameworks>
- <relevant adjacent code>
- <test infrastructure>

## Interview

### Q1: <question>
**Recommended:** <recommended answer>
**Decision:** <accepted as recommended | overridden by user to ...>

### Q2: <question>
**Recommended:** <recommended answer>
**Decision:** <accepted as recommended | overridden by user to ...>

...

## Key Findings

- <bullet summary of critical constraints or context>
- <bullet summary of scope boundaries>
- <bullet summary of risk areas identified>

## Research Directions

- <specific areas the research phase should explore deeply>
- <questions that need codebase-level answers>
- <patterns to verify or investigate>

## Open Items

- <anything the user flagged as uncertain>
- <questions the user deferred or didn't answer>
EOF
)"

The Research Directions section is critical — it tells the autonomous research phase what to focus on. Without it, research explores blindly.

7.5. Enrich phase bead descriptions with dependency IDs

This is critical for context firewalling. Each phase bead needs to know exactly which bead(s) to read.

Read .claude/templates/phase-enrichment.md for the enrichment template.

Replace all <*-bead-id> and <epic-id> placeholders with the actual IDs from step 3.

8. Close the questions bead and mark epic autonomous

bd close <questions-bead-id>
bd label add <epic-id> autonomous

The autonomous label signals the overseer that R-D-S phases are ready to run. Without it, the overseer ignores the epic.

9. Report

Output to the user:

• Epic ID and title
• Key findings summary (3-5 bullets)
• Research directions (what the next phase will explore)
• Current state: "Questions complete. Research → Design → Structure will run autonomously. Structure document will be ready for review when the loop finishes."
• The command to start the autonomous QRDS loop: ralph-loop <epic-id>

Do NOT tell the user to resolve gates or close beads manually. The R-D-S chain has no intermediate gates — dependencies handle ordering. The only gate is after structured-outline (reviewed via rc-next).

bd list --parent <epic-id>
bd ready

Hard rules

1. The model does not have opinions about final product choices. It may provide recommended answers to sharpen the discussion, but the human decides.
2. No question templates. The model determines what to ask based on the task, the codebase, and what the human has already said.
3. Grill-mode rigor is always on. Interrogate the design until the important branches are resolved.
4. Ask questions in small, dependency-aware batches, not one giant questionnaire and not necessarily one at a time. Expect voice answers.
5. Every question must include a recommended answer.
6. Every batch must include an explicit response contract: accept accepts the full batch, numbered replies override specific items, and unmentioned items count as accepted as recommended.
7. The reply instructions block must be the final block in every batch.
8. If the codebase can answer a question, explore the codebase instead of asking the user.
9. Explore before asking. Don't ask "what framework?" when you can read the code.
10. Tactical exploration only. The research phase does the deep dive. You're learning enough to ask the right questions.
11. Write the FULL Q&A into the bead description. This is the only artifact downstream phases see. Nothing is lost between sessions.
12. The questions bead contains the Q&A AND codebase context AND research directions. The research phase reads ONLY this bead.
13. Use sub-agents for parallel exploration when the task touches multiple areas of the codebase.
14. Use single-quoted HEREDOC (<<'EOF') for bead descriptions.
15. If the user wants to stop mid-interview, write what you have so far into the bead but do NOT close it.