Question Classification

# Lens: Question Classification

> Reusable policy lens. Decide whether a story gap is worth surfacing, how urgent it is, and what assumption to carry if unanswered.

## Purpose
Turn vague "open questions" into a small, relevant set of planning inputs. This lens exists to stop the agent from inventing questions for the sake of sounding thorough.

## Length budget
**<=25 lines.** Output only questions that materially affect implementation, scope, risk, dependency choice, test burden, rollback complexity, or user-visible behavior.

## When to use
- During `explain-story` to surface story-quality gaps early.
- During `plan-story` before the open questions gate.
- During plan refresh when a new answer may resolve or reopen prior assumptions.

## Trigger patterns — always classify when spotted
These story or AC patterns should automatically produce at least one question, even if the rest of the story looks complete:

- **Partial population coverage** — an AC explicitly names one segment (existing users, active records, paid accounts, etc.) without stating what applies to everything outside that segment. Ask: what is the intended behaviour for the unaddressed group?
- **Vague action verb** — any verb (submit, update, sync, reset, clear, delete, cancel, etc.) applied to an undefined object or scope. Ask: what exactly is affected, and what is explicitly excluded?
- **Action with no stated boundary** — AC describes an action but doesn't define its reach: one record or all, session-only or persisted, local or synced, current user or all users.
- **State change with no recovery path** — any AC that modifies persisted state with no mention of how to undo, retry, or recover from partial failure.
- **Side effects not mentioned in ACs** — the action implies downstream consequences (cascades, navigation, notifications, linked data) that no AC addresses.
- **Missing UX consequence for a significant action** — no mention of confirmation, feedback, error state, or navigation outcome for an action that materially changes data or context.

## Do not surface a question when
- Only ask questions in the business, product, or design domain — intended behaviour, scope, user-facing outcomes, UX intent, or business rules. The PM can answer directly or loop in stakeholders and the design team.
- Do not ask questions that a non-technical person could not usefully answer. Anything that requires inspecting the codebase, an API spec, or existing system behaviour is a technical discovery task — handle it in `plan.md` as a "candidate, verify" note or silent assumption.
- Do not ask when a safe default exists and taking it does not change implementation shape — record it as an assumption instead.
- Do not ask when the uncertainty is already covered by an explicit assumption in the current plan.

**Self-check before surfacing any question:** Would a PM, designer, or business stakeholder be the right person to answer this? If no — do not ask. Take the safe default and note it as an assumption.

### Technical domain examples — never ask the PM these
The following question types are always technical discovery tasks. Classify them as silent assumptions, then flag them in `plan.md` for codebase investigation:

- **Conflict resolution / sync strategy** — "if local and server state differ, which wins?" / "is the local write optimistic or authoritative?" — this depends on existing sync architecture, not product intent. Default: server wins on re-sync; local write is optimistic UI only. Verify in codebase.
- **API contract details** — request shape, field names, error codes, idempotency keys, versioning — inspect the API spec or existing calls.
- **State management internals** — where state lives (store, cache, session), how it's invalidated, which layer owns a given piece of data.
- **Existing behaviour of adjacent code** — "does the current auth flow handle X?" — requires reading the code, not a PM answer.
- **Infrastructure / deployment scope** — "is this a single-region or multi-region deploy?" — ops/engineering question.

If any of these surfaces as a potential question, convert it to an assumption block in `plan.md` instead: