speckit-clarify-zh

User Input

$ARGUMENTS

Outline

/speckit.plan

1. Run

   {SCRIPT}

   once from the repository root (in 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 flows.)
   • If JSON parsing fails, abort and instruct the user to re-run

     speckit-specify

     or validate the feature branch environment.
   • For single quotes in arguments, such as "I'm Groot", use escape syntax: e.g., 'I'''m Groot' (or double quotes if possible: "I'm Groot").
2. Load the current specification file. Perform a structured ambiguity and coverage scan using this taxonomy. 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 role / persona distinctions
   Domain and Data Model:
   • Entities, attributes, relationships
   • Identity and uniqueness rules
   • Lifecycle/state transitions
   • Data volume / scale assumptions
   Interaction and User Experience Flow:
   • 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 applicable)
   Integration and External Dependencies:
   • External services/APIs and failure modes
   • Data import/export formats
   • Protocol/version assumptions
   Edge Cases and Fault 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:
   • Specification glossary
   • Avoided synonyms / deprecated terms
   Completion Signals:
   • Acceptance criteria testability
   • Measurable definition of done style metrics
   Miscellaneous / Placeholders:
   • TODO markers / unresolved decisions
   • Vague adjectives without quantification ("robust", "intuitive")
   For each category with status Partial or Missing, add a candidate question opportunity unless:
   • Clarification would not materially change the implementation or validation strategy
   • Information is better deferred to the planning phase (documented internally)
3. Generate an (internal) prioritized queue of candidate clarification questions (max 5). Do not output all questions at once. Apply these constraints:
   • Max 10 questions total across the entire session.
   • Each question must be answerable via:
     • Short multiple choice (2-5 distinct, mutually exclusive options), or
     • A single word / phrase answer (explicit constraint: "Answer ≤5 words").
   • Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, user experience behavior, operational readiness, or compliance validation.
   • Ensure balanced category coverage: Try to cover 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 plan-level execution details (unless blocking 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 options and identify the most appropriate option based on:
       • Best practices for 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 your recommended option at the top, with a clear rationale (1-2 sentences explaining why this is the best choice).
     • Format as:

       **Recommended:** Option [X] - <rationale>

     • 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 as needed up to 5 options)
     Short	Provide a different short answer (<=5 words) (include only if free-form alternative is appropriate)

     • Add after the table:

       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 suggested answer> - <brief rationale>

     • Then output:

       Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide your own answer.

   • After user response:
     • If the user replies "yes", "recommended", or "suggested", use your previously stated recommendation/suggestion as the answer.
     • Otherwise, verify the answer maps to an option or meets the <=5 words constraint.
     • If ambiguous, ask for quick clarification (counts towards the same question; do not advance).
     • Once satisfied, record it in working memory (do not write to disk yet) and move to the next queued question.
   • Stop further questioning when:
     • All critical ambiguities are resolved early (remaining queued items become unnecessary), or
     • The user sends a completion signal ("done", "good", "no more"), or
     • You reach 5 asked questions.
   • Never reveal future queued questions in advance.
   • If no valid questions exist at the start, immediately report no critical 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 content.
   • For the first integrated answer in this session:
     • Ensure a

       ## Clarifications

       section exists (create it after the highest-level context/overview section in the specification template if missing).
     • Create (if not present) a

       ### Session YYYY-MM-DD

       subheading for today under it.
   • Immediately append a bullet line after acceptance:

     - Q: <question> → A: <final answer>

     .
   • Then apply the clarification to the most appropriate section immediately:
     • Feature ambiguity → Update or add bullet points in functional requirements.
     • User interaction / actor distinction → Update user stories or actor subsections (if present) with clarified roles, constraints, or scenarios.
     • Data shape / entity → Update the data model (add fields, types, relationships) while maintaining ordering; concisely document added constraints.
     • Non-functional constraints → Add/modify measurable criteria in the non-functional / quality attributes section (convert vague adjectives to metrics or explicit targets).
     • Edge cases / negative flows → Add new bullet points under edge cases / error handling (or create such a subsection if the template provides a placeholder).
     • Terminology conflicts → Normalize terminology across the specification; retain the original term only if necessary, adding

       (formerly known as "X")

       once.
   • If the clarification invalidates an earlier ambiguous statement, replace that statement instead of repeating it; do not leave outdated conflicting text.
   • Save the specification file after each integration to minimize context loss risk (atomic overwrite).
   • Preserve formatting: Do not reorder unrelated sections; keep heading hierarchy intact.
   • Keep each inserted clarification minimal and testable (avoid narrative drift).
6. Validation (Performed After Each Write Plus Final Pass):
   • The clarification session includes one bullet per accepted answer (no duplicates).
   • Total asked (accepted) questions ≤ 5.
   • Updated sections do not contain ambiguous placeholders that the answers should resolve.
   • No conflicting earlier statements remain (scan for removed invalid alternative choices).
   • Markdown structure is valid; only new headings allowed:

     ## Clarifications

     ,

     ### Session YYYY-MM-DD

     .
   • Terminology consistency: All updated sections use the same specification terminology.
7. Write the updated specification back to

   FEATURE_SPEC

   .
8. Report Completion (After Questioning Loop Ends or Early Termination):
   • Number of questions asked and answered.
   • Path to the updated specification.
   • Sections touched (list names).
   • Coverage summary table listing each taxonomy category with status: Resolved (previously partial/missing and resolved), Deferred (exceeds question quota or better suited for planning), Clear (sufficient), Unresolved (still partial/missing but low impact).
   • If any are unresolved or deferred, advise whether to proceed to

     speckit-plan

     or run

     speckit-clarify

     again later.
   • Suggested next command.

• If no meaningful ambiguities are found (or all potential questions are low impact), respond: "No critical ambiguities worthy of formal clarification detected." and suggest proceeding.
• If the specification file is missing, instruct the user to run

  speckit-specify

  first (do not create a new specification here).
• Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
• Avoid speculative tech stack questions unless their absence blocks feature clarity.
• Respect user early termination signals ("stop", "done", "proceed").
• If no questions are asked due to full coverage, output a compact coverage summary (all categories clear) then suggest moving forward.
• If quota is reached but high-impact categories remain unresolved, explicitly mark them as deferred with a rationale.