speckit-clarify-zh

User input

$ARGUMENTS

Youmustconsider user input (if not empty) before continuing.

Outline

Goal: Detect and reduce ambiguity or missing decision points in the active feature specification, and record the clarification directly in the specification file.

Note: This clarification workflow is expected to run (and complete) before invoking /speckit.plan . If the user explicitly states that they are skipping clarification (for example, exploratory probing), you may proceed, but you must warn that the risk of downstream rework will increase.

Execution steps:

scripts: sh: .specify/scripts/bash/check-prerequisites.sh --json --paths-only ps: .specify/scripts/powershell/check-prerequisites.ps1 -Json -PathsOnly

1. Run once from the repository root {SCRIPT}(combined --json --paths-only mode / -Json -PathsOnly). Parse the minimal JSON payload fields:

   • FEATURE_DIR
   • FEATURE_SPEC
   • (optionally capture IMPL_PLAN, TASKS for future chained workflows.)
   • If JSON parsing fails, abort and instruct the user to rerun speckit-specify or verify the feature branch environment.
   • For single quotes in arguments, such as "I'm Groot", use escaped syntax: for example 'I'''m Groot' (or if possible use double quotes: "I'm Groot").

2. Load the current specification file. Use this taxonomy to perform a structured ambiguity and coverage scan. For each category, mark the status: Clear / Partial / Missing. Generate an internal coverage map for prioritization (do not output the raw map unless no questions are asked).

   Feature scope and behavior:

   • Core user goals and success criteria
   • Explicit out-of-scope statements
   • User roles / persona distinctions

   Domain and data model:

   • Entities, attributes, relationships
   • Identity and uniqueness rules
   • Lifecycle/state transitions
   • Data volume / scale assumptions

   Interaction and user experience flows:

   • Key user journeys / sequences
   • Error/empty/loading states
   • Accessibility or localization notes

   Non-functional quality attributes:

   • Performance (latency, throughput targets)
   • Scalability (horizontal/vertical, limits)
   • Reliability and availability (uptime, recovery expectations)
   • Observability (logs, metrics, tracing signals)
   • Security and privacy (authentication/authorization, data protection, threat assumptions)
   • Compliance / regulatory constraints (if any)

   Integrations and external dependencies:

   • External services/APIs and failure modes
   • Data import/export formats
   • Protocol/version assumptions

   Edge cases and failure handling:

   • Negative scenarios
   • Rate limiting / throttling
   • Conflict resolution (e.g., concurrent edits)

   Constraints and trade-offs:

   • Technical constraints (language, storage, hosting)
   • Explicit trade-offs or rejected alternatives

   Terminology and consistency:

   • Normative Glossary
   • Avoided Synonyms / Deprecated Terms

   Completion Signal:

   • Acceptance Criteria Testability
   • Measurable Definition of Done Style Metrics

   Miscellaneous / Placeholders:

   • TODO Markers / Unresolved Decisions
   • Vague Adjectives Lacking Quantification ("robust", "intuitive")

   For each category whose status is partial or missing, add one candidate question opportunity, unless:

   • The clarification would not materially change the implementation or verification strategy
   • The information is better deferred to the planning phase (internal note)

3. Generate an (internal) prioritized queue of candidate clarification questions (maximum 5). Do not output all questions at once. Apply these constraints:

   • Maximum 10 questions across the entire session.
   • Each question must be answerable by:
     • Short multiple choice (2-5 distinct, mutually exclusive options), or
     • A one-word / phrase answer (with an explicit constraint: "answer <=5 words").
   • Include only questions whose answers materially affect architecture, data modeling, task decomposition, test design, user experience behavior, operational readiness, or compliance verification.
   • Ensure balanced category coverage: attempt to cover the highest-impact unresolved categories first; avoid asking two low-impact questions while a single high-impact area (e.g., security posture) remains unresolved.
   • Exclude already-answered questions, trivial style preferences, or planning-level execution details (unless they block correctness).
   • Prioritize clarifications that reduce downstream rework risk or prevent inconsistent acceptance tests.
   • If more than 5 categories remain unresolved, select the top 5 using the (impact * uncertainty) heuristic.

4. Sequential Questioning Loop (Interactive):

   • Ask only one question at a time.

   • For multiple choice questions:

     • Analyze all optionsand determine based onthe most suitable option：
       • 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 specification
     • Highlight yourrecommended optionat the top, and provide a clear rationale (1-2 sentences explaining why this is the best choice).
     • Format as:**推荐：** 选项 [X] - <理由>
     • Then present all options as a Markdown table:

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

     • After the table add:您可以回复选项字母（例如，"A"），通过说"yes"或"recommended"接受推荐，或提供您自己的简短答案。

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

     • Provide yoursuggested answerbased on best practices and context.
     • Format:**建议：** <您的建议答案> - <简要理由>
     • Then output:格式：简短答案（<=5 个单词）。您可以通过说"yes"或"suggested"接受建议，或提供您自己的答案。

   • After the user responds:

     • If the user replies "yes", "recommended", or "suggested", use the recommendation/suggestion you previously declared as the answer.
     • Otherwise, verify that the answer maps to one option or satisfies the <=5 word constraint.
     • If ambiguous, ask for a quick clarification (the count still belongs to the same question; do not advance).
     • Once satisfied, record it in working memory (not yet written to disk) and move to the next queued question.

   • Stop asking further questions when:

     • all key ambiguities are resolved in advance (the remaining queued items become unnecessary), or
     • the user signals completion ("done", "good", "no more"), or
     • you reach 5 asked questions.

   • Never reveal future queued questions in advance.

   • If there are no valid questions at the start, immediately report that there are no key ambiguities.

5. Integration after each accepted answer (incremental update approach):

   • Maintain an in-memory representation of the specification (loaded once at startup) plus the original file contents.
   • For the first integrated answer in this session:
     • Ensure that the ## Clarifications section exists (if missing, create it after the highest-level context/overview section in the specification template).
     • Under it, create (if it does not exist) a ### Session YYYY-MM-DD subheading for today.
   • Immediately after acceptance, append a bullet line:- Q: <问题> → A: <最终答案>。
   • Then immediately apply the clarification to the most appropriate section:
     • Functional ambiguity → update or add a bullet in the functional requirements.
     • User interaction / actor differentiation → update the user stories or actor subsection (if it exists) with the clarified role, constraint, or scenario.
     • Data shape / entity → update the data model (add fields, types, relationships) while preserving ordering; concisely document the added constraints.
     • Non-functional constraints → add/modify measurable criteria in the non-functional / quality attributes section (convert vague adjectives into metrics or explicit targets).
     • Edge cases / negative flows → add a new bullet under edge cases / error handling (or create such a subsection if the template provides a placeholder).
     • Terminology conflict → normalize terminology throughout the specification; retain the original term only when necessary, adding(以前称为"X")once.
   • If the clarification invalidates an earlier ambiguous statement, replace that statement rather than duplicating it; do not leave stale contradictory text.
   • Save the specification file after each integration to minimize the risk of context loss (atomic overwrite).
   • Preserve formatting: do not reorder unrelated sections; keep the heading hierarchy intact.
   • Keep each inserted clarification minimal and testable (avoid narrative drift).

6. Verification (perform after each write plus a final pass):

   • The clarification session contains one bullet for each accepted answer (no duplicates).
   • Total asked (accepted) questions ≤ 5.
   • Updated sections do not contain new ambiguous placeholders that the answers should resolve.
   • Non-contradictory early statements are retained (invalid alternative choices removed by scanning).
   • Markdown structure is valid; only new headings are allowed:## Clarifications, ### Session YYYY-MM-DD。
   • Terminology consistency: all updated sections use the same canonical terminology.

7. Write the updated spec back to FEATURE_SPEC。

8. Report completion (after the question loop ends or is terminated early):

   • Number of questions asked and answered.
   • Path to the updated spec.
   • Sections touched (list names).
   • Coverage summary table lists each classification category, status: resolved (previously partial/missing and now resolved), deferred (beyond the question quota or better suited to planning), clear (already sufficient), unresolved (still partial/missing but low impact).
   • If there are any unresolved or deferred items, recommend whether to continue to speckit-plan again later speckit-clarify。
   • Recommended next command.

Behavior rules:

• If no meaningful ambiguity is found (or all potential issues are low impact), respond: "No critical ambiguity worth formal clarification detected." and recommend proceeding.
• If the spec file is missing, instruct the user to run speckit-specifyfirst (do not create a new spec here).
• Never exceed 5 total questions asked (clarification retries of a single question do not count as new questions).
• Avoid speculative tech stack questions unless the omission blocks functional clarity.
• Respect the user's early termination signals ("stop", "done", "proceed").
• If no questions are asked due to complete coverage, output a compact coverage summary (all categories clear) and then recommend proceeding.
• If the quota is reached but unresolved high-impact categories remain, explicitly mark them as deferred with justification.

Priority context: {ARGS}