Smith Question Contract

This skill is the single source of truth for how Smith asks the user a decision question and processes the answer. Any Smith workflow that reaches a point where it must ask the user to choose between options invokes this skill at that moment so the contract is fresh in context, then follows it verbatim.

It does not generate questions — the calling workflow supplies the questions (from plan artifacts, spec ambiguities, an intake template, etc.). This skill defines only the presentation, pacing, and answer-handling contract.

Hard rule: never use the interactive popup

Do NOT use the AskUserQuestion tool (the interactive multiple-choice popup) to present these questions. Questions are presented as markdown text per the contract below. This is enforced by the question-gate-guard.sh PreToolUse hook (config question_gate.mode) and by a graded rule in the CLAUDE.md rule set; this skill states it so the contract is self-reinforcing in context.

Rationale: the markdown contract shows the full Context, every option's tradeoffs, and the recommendation with its reasoning — and leaves a durable, reviewable record. The popup hides that reasoning and leaves nothing behind.

Presentation contract

Present exactly one question at a time. For each question, render:

## Question [N] of [Total]: [Short topic]

**Context:** [Quote or summarize the spec/plan/code that raises this question —
why it is being asked and what it affects.]

**Question:** [The specific decision, phrased so an option letter answers it.]

**Options:**

| Option | Description | Implications |
|--------|-------------|--------------|
| A | [first option] | [pros: … / cons: … — effort, risk, tradeoffs] |
| B | [second option] | [pros: … / cons: …] |
| C | [third option] | [pros: … / cons: …] |

**Recommended:** [Option letter] — [Clear reasoning for why this is the best
choice given the context.]

Reply with an option letter (e.g. "A"), "yes" to accept the recommendation,
"skip" to defer, or type your own answer.

Rules:

• Every question has at least two options, each with real tradeoffs.
• Every question has a Recommended option with reasoning — never a bare letter.
• Order questions by impact (highest-impact first).
• Do not ask about matters with an obvious default or a clear best practice.
• After presenting a question, stop and wait for the user's reply. Do not present the next question, and do not begin implementation, until the current question is answered.

Response grammar

When the user replies, interpret it as:

Reply	Meaning
yes / recommended / rec	Use the recommended option.
An option letter (A, B, C, …)	Use that option.
skip	Defer — record SKIPPED — needs follow-up.
done	Stop asking; mark all remaining questions SKIPPED.
Anything else	Accept it verbatim as a custom answer.

If a reply is ambiguous, ask one brief disambiguation before advancing (it still belongs to the same question — do not count it as a new question).

After each answer

1. Record the answer immediately — if the gate persists answers, write the chosen answer into the question's **Answer:** field in questions.md (see format below) before moving on. This makes the flow resumable: an interrupted session leaves answered questions filled in and unanswered ones blank.
2. Confirm and advance — e.g. Saved: Q[N] → [brief answer]. ([remaining] remaining).
3. Present the next unanswered question.

After all questions

1. Display an answers summary table (# | Topic | Answer).
2. Ask: "Would you like to change any answers? Reply with a question number to revise, or 'looks good' to continue." Revise on request.
3. Update the persisted file's status header from AWAITING ANSWERS to ANSWERED (or PARTIALLY ANSWERED if any were skipped).

Persisted questions.md format

Gates that persist answers (smith-new, smith-clarify) use this file shape. This is the canonical definition — other skills reference it rather than restating it.

# Implementation Questions: [Feature Name]

**Generated**: [DATE]
**Feature**: [link to spec.md]
**Plan**: [link to plan.md]
**Status**: AWAITING ANSWERS

---

## Q1: [Topic]

**Context**: [Quote the spec/plan/research section that raises this question]

**Question**: [Specific decision]

**Options**:

| Option | Description | Implications |
|--------|-------------|--------------|
| A | [first option] | [tradeoffs, effort, risk] |
| B | [second option] | [tradeoffs, effort, risk] |

**Recommended**: [A/B] — [reasoning]

**Answer**: ___

---

[repeat for all questions]

• **Answer**: ___ is the blank field, filled in as each question is answered.
• The Status header moves AWAITING ANSWERS → ANSWERED when complete.

Invocation

• From a workflow: invoke smith-question at the step where the gate begins presenting questions, then follow the contract above. Keep only your gate-specific concerns in your own SKILL.md (e.g. where questions.md lives, how questions are generated, the ≤5-question budget, an intake template's navigation) — do not restate this contract.
• Standalone (/smith-question): prints this contract as a reference. It does not generate questions on its own.

Consumers

• smith-new — Phase 5 Questions Gate (persists questions.md in the feature folder).
• smith-clarify — Interactive Answer Collection + sequential ≤5-question loop.
• smith — init interview (29-question intake walk; keeps its own ok/skip/back navigation and specs/init-intake.md persistence, uses this contract for presentation).