SKILL.md
ABOUTME: Structured requirements refinement using AskUserQuestion before planning
ABOUTME: Identifies gray areas, clarifies with concrete options, captures decisions for the plan
Requirements Refinement
Invoke explicitly or triggered automatically by plan-first-workflow for 🟡/🔴 tasks.
Process
- Pick the scope mode before any other question. Classify the task, then:
| Task class | Modes offered | Applied |
|---|---|---|
| bugfix, refactor | none, no question asked | Hold Scope, silently |
| feature | Hold Scope (recommended) / Selective Expansion / Reduction | user's answer |
| greenfield | Hold Scope (recommended) / Selective Expansion / Reduction / Expansion | user's answer |
| unsure which class | none, no question asked | Hold Scope, silently |
One AskUserQuestion for the mode where modes are offered; Hold Scope is the recommended option. Never ask on a bugfix or refactor, and never ask when the class is unclear: Hold is the escape from misclassifying.
- Hold Scope: clarify HOW to build what was requested, never WHETHER to add more (steps 1-4 below as written) - Selective Expansion: adjacent additions may be proposed, one at a time - Expansion: same, with a wider radius (greenfield only) - Reduction: propose cuts to what was requested, one at a time
In Selective Expansion and Expansion: each proposed addition is its own AskUserQuestion; never bundle. Reduction works the same way for cuts: one question per cut, nothing dropped silently. Declined proposals become deferred ideas, exactly as in Hold Scope.
- Identify gray areas by domain:
- Visual → layout, density, interactions, empty states - API/CLI → response format, error handling, auth flow - Infrastructure → scaling, redundancy, monitoring - Integration → protocol, auth method, error recovery
- For each gray area, use
AskUserQuestion:
- Concrete options ("JWT" not "Option A"), 2-4 choices - Include "You decide" when Claude's discretion is fine - Follow threads: each answer may reveal the next question
- Scope guard: in Hold Scope (and outside the opted-in mode's radius), if user suggests new scope, capture as deferred idea, redirect back
- Output: list of decisions to include as
## Decisionsin the plan file
Anti-patterns
- Generic questions ("What are your requirements?") → ask about specific decisions
- Checklist walking → follow the thread the user cares about
- Expanding scope in Hold Scope → clarify HOW to implement what's requested, not WHETHER to add more
- Asking the mode question on a bugfix, a refactor, or an unclear task → Hold applies, silently
- Bundling several additions into one "expansion accepted" → one question per addition, always