Speckit Clarify

Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:

• Maximum of 10 total questions across the whole session.
• Each question must be answerable with EITHER:
  • A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
  • A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
• Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
• Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
• Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
• Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
• If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

Sequential questioning loop (interactive):

• Present EXACTLY ONE question at a time.

• For multiple‑choice questions:

  • Analyze all options and determine the most suitable option based on:
    • Best practices for the project type
    • Common patterns in similar implementations
    • Risk reduction (security, performance, maintainability)
    • Alignment with any explicit project goals or constraints visible in the spec
  • Present your recommended option prominently at the top with clear reasoning (1-2 sentences explaining why this is the best choice).
  • Format as: **Recommended:** Option [X] - <reasoning>
  • Then render all options as a Markdown table:

  Option	Description
  A	<Option A description>
  B	<Option B description>
  C	<Option C description> (add D/E as needed up to 5)
  Short	Provide a different short answer (<=5 words) (Include only if free-form alternative is appropriate)

  • After the table, add: You can reply with the option letter (e.g., "A"), accept the recommendation by saying "yes" or "recommended", or provide your own short answer.

• For short‑answer style (no meaningful discrete options):

  • Provide your suggested answer based on best practices and context.
  • Format as: **Suggested:** <your proposed answer> - <brief reasoning>
  • Then output: Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

• After the user answers:

  • If the user replies with "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
  • Otherwise, validate the answer maps to one option or fits the <=5 word constraint.
  • If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
  • Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.

• Stop asking further questions when:

  • All critical ambiguities resolved early (remaining queued items become unnecessary), OR

Integration after EACH accepted answer (incremental update approach):

• Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
• For the first integrated answer in this session:
  • Ensure a ## Clarifications section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
  • Under it, create (if not present) a ### Session YYYY-MM-DD subheading for today.
• Append a bullet line immediately after acceptance: - Q: <question> → A: <final answer>.
• Then immediately apply the clarification to the most appropriate section(s):
  • Functional ambiguity → Update or add a bullet in Functional Requirements.
  • User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
  • Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
  • Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
  • Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
  • Terminology conflict → Normalize term across spec; retain original only if necessary by adding (formerly referred to as "X") once.
• If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
• Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
• Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
• Keep each inserted clarification minimal and testable (avoid narrative drift).

Validation (performed after EACH write plus final pass):

• Clarifications session contains exactly one bullet per accepted answer (no duplicates).
• Total asked (accepted) questions ≤ 5.
• Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
• No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
• Markdown structure valid; only allowed new headings: ## Clarifications, ### Session YYYY-MM-DD.
• Terminology consistency: same canonical term used across all updated sections.

Write the updated spec back to FEATURE_SPEC.

Report completion (after questioning loop ends or early termination):

• Number of questions asked & answered.
• Path to updated spec.
• Sections touched (list names).
• Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
• If any Outstanding or Deferred remain, recommend whether to proceed to /speckit-plan or run /speckit-clarify again later post-plan.
• Suggested next command.

Never reveal future queued questions in advance.

If no valid questions exist at start, immediately report no critical ambiguities.