autospec-clarify

name	autospec-clarify
description	Identify underspecified areas in YAML spec and encode clarifications back into the spec.

autospec-clarify

This Agent Skill is generated from autospec.clarify. When the user invokes "$autospec-clarify" or "/autospec.clarify", load and follow these instructions directly. Treat the text after the skill or command name as "$ARGUMENTS". Do not route back through "autospec clarify"; this skill is the prompt for the stage.

Project specs directory: ./specs

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.yaml file.

Note: This clarification workflow should run BEFORE $autospec-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.

Pre-computed Context

The following paths have been pre-computed and are available for use:

• FEATURE_DIR: {{.FeatureDir}}
• FEATURE_SPEC: {{.FeatureSpec}}

1. Load and analyze the spec file at {{.FeatureSpec}}. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing.

   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

2. Generate candidate questions (maximum 5). 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
   • Exclude questions already answered, trivial stylistic preferences, or plan-level execution details
   • Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests

3. Sequential questioning loop (interactive):

   • Present EXACTLY ONE question at a time

   • For multiple-choice questions:

     • Analyze all options and determine the most suitable option based on best practices, common patterns, risk reduction, and alignment with project goals
     • Present your recommended option prominently at the top with clear reasoning (1-2 sentences)
     • Format as: **Recommended:** Option [X] - <reasoning>
     • Then render all options as a Markdown table:

     Option	Description
     A
     B
     C
     Short	Provide a different short answer (<=5 words)

     • 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 proposed answer> - <brief reasoning>
     • Then output: Format: Short answer (<=5 words). You can accept the suggestion by saying "yes" or "suggested", or provide 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
     • Otherwise, validate the answer maps to one option or fits the <=5 word constraint
     • If ambiguous, ask for a quick disambiguation

   • Stop asking when:

     • All critical ambiguities resolved early, 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

4. Integration after EACH accepted answer (incremental update approach):

   • Maintain in-memory representation of the spec.yaml plus the raw file contents

   • For the first integrated answer in this session, ensure a clarifications: section exists in the YAML

   • Add clarification entry in this format:

     clarifications:
       - date: "<YYYY-MM-DD>"
         question: "<the question asked>"
         answer: "<the answer provided>"
         applied_to: "<section(s) updated>"
     

   • Then immediately apply the clarification to the most appropriate section(s):

     • Functional ambiguity -> Update or add items in requirements.functional
     • User interaction / actor distinction -> Update user_stories section
     • Data shape / entities -> Update key_entities section
     • Non-functional constraint -> Add/modify in requirements.non_functional
     • Edge case / negative flow -> Add to edge_cases section
     • Terminology conflict -> Normalize term across spec

   • If the clarification invalidates an earlier ambiguous statement, replace that statement

   • Save the spec file AFTER each integration (atomic overwrite)

   • Preserve YAML formatting: do not reorder unrelated sections; keep structure intact

   • Keep each inserted clarification minimal and testable

5. Validate the artifact after each write:

   autospec artifact {{.FeatureSpec}}
   

   • If validation fails: fix schema errors (missing required fields, invalid types) and retry
   • If validation passes: proceed

6. Report completion (after questioning loop ends):

   • Number of questions asked & answered
   • Path to updated spec.yaml
   • 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 $autospec-plan or run $autospec-clarify again
   • Suggested next command

Key Rules

• Output MUST be valid YAML (use autospec artifact {{.FeatureSpec}} to verify schema compliance)
• If no meaningful ambiguities found, respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding
• If spec file missing, instruct user to run $autospec-specify first
• 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 quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale