spec-kitty-clarify（规格小猫澄清）

Dependencies

This skill requires Python 3.8+ and standard library only. No external packages needed.

To install this skill's dependencies:

pip-compile ./requirements.in
pip install -r ./requirements.txt

See ./requirements.txt for the dependency lockfile (currently empty — standard library only).

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Outline

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

Note: This clarification workflow is expected to run (and be completed) BEFORE invoking /spec-kitty.plan. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.

Execution steps:

1. Run spec-kitty agent feature check-prerequisites --json --paths-only from the repository root and parse JSON for:

- feature_dir - Absolute path to feature directory (e.g., /path/to/kitty-specs/017-my-feature/) - FEATURE_SPEC - Absolute path to spec.md file - target_branch / base_branch (deterministic branch contract) - If command fails or JSON parsing fails, abort and instruct user to run /spec-kitty.specify first or verify they are in a spec-kitty-initialized repository.

1. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked). Functional Scope & Behavior: Domain & Data Model: Interaction & UX Flow: Non-Functional Quality Attributes: Integration & External Dependencies: Edge Cases & Failure Handling: Constraints & Tradeoffs: Terminology & Consistency: Completion Signals: Misc / Placeholders: For each category with Partial or Missing status, add a candidate question opportunity unless:

- Core user goals & success criteria - Explicit out-of-scope declarations - User roles / personas differentiation - Entities, attributes, relationships - Identity & uniqueness rules - Lifecycle/state transitions - Data volume / scale assumptions - Critical user journeys / sequences - Error/empty/loading states - Accessibility or localization notes - Performance (latency, throughput targets) - Scalability (horizontal/vertical, limits) - Reliability & availability (uptime, recovery expectations) - Observability (logging, metrics, tracing signals) - Security & privacy (authN/Z, data protection, threat assumptions) - Compliance / regulatory constraints (if any) - External services/APIs and failure modes - Data import/export formats - Protocol/versioning assumptions - Negative scenarios - Rate limiting / throttling - Conflict resolution (e.g., concurrent edits) - Technical constraints (language, storage, hosting) - Explicit tradeoffs or rejected alternatives - Canonical glossary terms - Avoided synonyms / deprecated terms - Acceptance criteria testability - Measurable Definition of Done style indicators - TODO markers / unresolved decisions - Ambiguous adjectives ("robust", "intuitive") lacking quantification - Clarification would not materially change implementation or validation strategy - Information is better deferred to planning phase (note internally)

1. 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. - Scale thoroughness to the feature’s complexity: a lightweight enhancement may only need one or two confirmations, while multi-system efforts warrant the full question budget if gaps remain critical. - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.

1. Sequential questioning loop (interactive):

- Present EXACTLY ONE question at a time. - For multiple-choice questions, list options inline using letter prefixes rather than tables, e.g. Options: (A) describe option A · (B) describe option B · (C) describe option C · (D) short custom answer (<=5 words) Ask the user to reply with the letter (or short custom text when offered). - For short-answer style (no meaningful discrete options), output a single line after the question: Format: Short answer (<=5 words). - After the user answers: - 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 - User signals completion ("done", "good", "no more"), OR - You reach 5 asked questions. - Never reveal future queued questions in advance. - If no valid questions exist at start, immediately report no critical ambiguities.

1. 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).

1. 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.

1. Write the updated spec back to FEATURE_SPEC.
2. Report completion (after questioning loop ends or early termination):

- Number of questions asked & answered. - Path to updated spec. - Sections touched (list names). - Coverage summary listing each taxonomy category with a status label (Resolved / Deferred / Clear / Outstanding). Present as plain text or bullet list, not a table. - If any Outstanding or Deferred remain, recommend whether to proceed to /spec-kitty.plan or run /spec-kitty.clarify again later post-plan. - Suggested next command.

Behavior rules:

• If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
• If spec file missing, instruct user to run /spec-kitty.specify first (do not create a new spec 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 the absence blocks functional clarity.
• Respect user early termination signals ("stop", "done", "proceed").
• If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
• If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.

Context for prioritization: User arguments from $ARGUMENTS section above (if provided). Use these to focus clarification on specific areas of concern mentioned by the user.