kiss-clarify-specs

name	kiss-clarify-specs
description	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.
compatibility	Requires kiss project structure with .kiss/ directory
metadata	{"author":"github-kiss","source":"agent-skills/kiss-clarify-specs/kiss-clarify-specs.md"}

User Input

$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):

    ## Extension Hooks
    
    **Optional Pre-Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

    ## 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:

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):

    ## Extension Hooks
    
    **Optional Hook**: {extension}
    Command: `/{command}`
    Description: {description}
    
    Prompt: {prompt}
    To execute: `/{command}`
    

  • Mandatory hook (optional: false):

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