# Kiss Clarify Specs > Identifies underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec. Use when a spec has gaps or ambiguities, before implementation starts, or when the team disagrees on scope. - Skill: `dauquangthanh/kiss-clarify-specs-2` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add dauquangthanh/kiss-clarify-specs-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/dauquangthanh/kiss-clarify-specs-2/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: dauquangthanh (https://skillmd.com/u/dauquangthanh) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/dauquangthanh/kiss-clarify-specs-2 --- ## User Input ```text $ARGUMENTS ``` You **MUST** consider the user input before proceeding (if not empty). ## Pre-Execution Checks **Check for extension hooks (before clarification)**: - Check if `.kiss/extensions.yml` exists in the project root. - If it exists, read it and look for entries under the `hooks.before_clarify-specs` key - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation - For each executable hook, output the following based on its `optional` flag: - **Optional hook** (`optional: true`): ```text ## Extension Hooks **Optional Pre-Hook**: {extension} Command: `/{command}` Description: {description} Prompt: {prompt} To execute: `/{command}` ``` - **Mandatory hook** (`optional: false`): ```text ## Extension Hooks **Automatic Pre-Hook**: {extension} Executing: `/{command}` EXECUTE_COMMAND: {command} Wait for the result of the hook command before proceeding to the Outline. ``` - If no hooks are registered or `.kiss/extensions.yml` does not exist, skip silently ## 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 `/kiss.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. ### Audience and tone (interactive mode) If `KISS_AGENT_MODE=interactive` (the default), assume the user has **no technical and no business-domain background**. The taxonomy in step 2 is for your **internal** coverage map — never expose its labels (NFR, observability, throughput, RBAC, idempotent, etc.) to the user. When you present a question in step 4: - **Yes / no first.** Phrase so `yes`, `no`, `not sure`, or `skip` is a valid answer. - **Plain English only.** Translate every technical concept into everyday words with concrete examples. "How fast should it feel when a user clicks?" not "What's the latency target?". "Should each user only see their own things?" not "Is this multi-tenant with row-level isolation?". "Are there rules about the personal info you collect — for example medical or children's data?" not "Is this PII subject to GDPR / HIPAA?". - **Always recommend.** State the option you would pick and why in one sentence so the user can reply "yes" / "ok" to accept it. - **Choices, not blank fields.** When yes/no isn't enough, offer 2-4 lettered options (A/B/C/D) with one-line everyday descriptions. Always include "Not sure — use the recommended default". - **Treat `not sure` / `skip` as a default-trigger.** Apply the recommended default, integrate it into the spec marked "(default applied — confirm later)", and continue. Do not block. When `KISS_AGENT_MODE=auto` (or `--auto`), skip the question loop entirely: pick the recommended option for every Partial / Missing category and log decisions to the business-analyst decision log. Execution steps: 1. Run `scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: - `FEATURE_DIR` - `FEATURE_SPEC` - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) - If JSON parsing fails, abort and instruct user to re-run `/kiss.specify` or verify feature branch environment. - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'''m Groot' (or double-quote if possible: "I'm Groot"). 2. 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: - Core user goals & success criteria - Explicit out-of-scope declarations - User roles / personas differentiation Domain & Data Model: - Entities, attributes, relationships - Identity & uniqueness rules - Lifecycle/state transitions - Data volume / scale assumptions Interaction & UX Flow: - Critical user journeys / sequences - Error/empty/loading states - Accessibility or localization notes Non-Functional Quality Attributes: - 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) Integration & External Dependencies: - External services/APIs and failure modes - Data import/export formats - Protocol/versioning assumptions Edge Cases & Failure Handling: - Negative scenarios - Rate limiting / throttling - Conflict resolution (e.g., concurrent edits) Constraints & Tradeoffs: - Technical constraints (language, storage, hosting) - Explicit tradeoffs or rejected alternatives Terminology & Consistency: - Canonical glossary terms - Avoided synonyms / deprecated terms Completion Signals: - Acceptance criteria testability - Measurable Definition of Done style indicators Misc / Placeholders: - TODO markers / unresolved decisions - Ambiguous adjectives ("robust", "intuitive") lacking quantification For each category with Partial or Missing status, add a candidate question opportunity unless: - Clarification would not materially change implementation or validation strategy - Information is better deferred to planning phase (note internally) 3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints: - Maximum of 5 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. 4. Sequential questioning loop (interactive): - Present EXACTLY ONE question at a time. - **Always rewrite the question in plain everyday language before showing it.** Never expose taxonomy labels (NFR, observability, scalability, throughput, idempotent, RBAC, PII, eventual consistency) to the user. Translate the underlying concept into a concrete everyday situation with an example. E.g., instead of "What is the latency target?", ask "How fast should it feel when a user clicks something?". Instead of "Is this PII-bearing under GDPR?", ask "Are there special rules about the personal data you collect — for example medical, financial, children's data, or EU users?". - 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 in plain words explaining why this is the best choice). - Format as: `**Recommended:** Option [X] - ` - Then render all options as a Markdown table. Each option's description must be **plain consequence**, not a technical implication ("users wait a bit longer" not "added latency"; "you store a bit more data" not "increased storage cost"): | Option | Plain-language answer | What this means for you | |--------|------------------------|--------------------------| | A | | | | B | | | | C | | (add D/E up to 5) | | Not sure | Use the recommended default | | | Short | Tell me in your own words (<=5 words) | I'll translate it into the spec for you (include only if a free-form answer is appropriate) | - After the table, add: `You can reply with the option letter (e.g., "A"), say "yes" or "recommended" to accept the suggestion, say "not sure" to use the default, or give a short answer in your own words.` - For short‑answer style (no meaningful discrete options): - Provide your **suggested answer** based on best practices and context. - Format as: `**Suggested:** - ` - Then output: `Format: Short answer (<=5 words). Say "yes" or "suggested" to accept, "not sure" to use the suggestion as a default, or give 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. - If the user replies with "not sure" or "skip", apply the recommendation/suggestion as a default, mark the resulting spec entry as "(default applied — confirm later)", and continue without blocking. - Otherwise, validate the answer maps to one option or fits the <=5 word constraint. - If ambiguous, ask for a quick disambiguation in plain words (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", "that's enough"), 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. 5. 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: → A: `. - 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 Success Criteria > Measurable Outcomes (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). 6. 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. 7. Write the updated spec back to `FEATURE_SPEC`. 8. 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 `/kiss.plan` or run `/kiss.clarify-specs` 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 `/kiss.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: $ARGUMENTS ## Post-Execution Checks **Check for extension hooks (after clarification)**: Check if `.kiss/extensions.yml` exists in the project root. - If it exists, read it and look for entries under the `hooks.after_clarify-specs` key - If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally - Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. - For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation - For each executable hook, output the following based on its `optional` flag: - **Optional hook** (`optional: true`): ```text ## Extension Hooks **Optional Hook**: {extension} Command: `/{command}` Description: {description} Prompt: {prompt} To execute: `/{command}` ``` - **Mandatory hook** (`optional: false`): ```text ## Extension Hooks **Automatic Hook**: {extension} Executing: `/{command}` EXECUTE_COMMAND: {command} ``` - If no hooks are registered or `.kiss/extensions.yml` does not exist, skip silently ## Inputs - **Feature Specification** (`{context.current.spec}`): current.spec. - If set: Read the specification file. - If null: Search {context.paths.specs} for the most recent spec.md. - If not provided: Ask the user to run /kiss-specify first. ## Outputs - **Updated Specification** (`{context.current.spec}`): current.spec. - Behavior: Update the spec file in-place with clarifications. Ask before overwriting if confirm_before_write is true. - Overwrite guarded by `{context.preferences.confirm_before_write}`. ## Context Update After this skill completes successfully, update `.kiss/context.yml`: - Do not change any context.yml values (clarifications are in-spec updates only) ## Handoffs - **Build Technical Plan**: run `/kiss-plan` to continue the workflow.