clarify_skill

Overview

This skill transforms vague or ambiguous user requests into precise, actionable requirement specifications through iterative, focused questioning. It captures the original request, identifies ambiguities, asks targeted multiple-choice questions, and produces a clear before/after requirement summary. It can optionally save the clarified specification as a Markdown file in a project-appropriate location.

How this skill works

First, the skill records the user's original requirement verbatim and scans it for ambiguity across scope, behavior, interface, data, constraints, and priority. It then runs an iterative loop of single-topic, option-based questions until all ambiguities are resolved, updating its internal specification each step. Finally, it emits a Requirement Clarification Summary with goal, scope, constraints, success criteria, and a table of decisions, and offers to save the result to a requirements/ file.

When to use it

• User asks to "clarify", "/clarify", or explicitly requests clarification or refinement
• A request is vague, underspecified, or could be interpreted multiple ways
• Before starting implementation, planning, or estimating work
• When a bug report or feature request lacks reproducible detail
• When stakeholder input conflicts or leaves critical decisions open

Best practices

• Ask specific, single-concern questions rather than broad ones
• Prefer 2–4 concrete options for each question to reduce friction
• Preserve the user’s original intent—don’t reframe goals without permission
• Only ask the minimal number of questions needed to remove ambiguity
• Record every decision and present a before/after comparison for traceability
• Offer a save option to standardize requirement storage in the project

Example use cases

• Turning "Add a login feature" into a full auth specification (method, session, password policy)
• Refining a bug report like "export is broken" into a reproducible defect with scope and steps
• Clarifying API requirements: request/response formats, auth, error handling, and rate limits
• Converting stakeholder feature notes into acceptance criteria and success metrics
• Creating a shareable requirements.md for handoff to design or engineering