Reviews existing specifications for ambiguity and missing decision points - uses structured taxonomy to detect gaps, generates prioritized clarification questions, reduces specification uncertainty.
Detects ambiguity and gaps in feature specs using a structured taxonomy, then adds up to 5 prioritized clarification questions that materially impact implementation. Automatically triggers when reviewing specification files to reduce uncertainty before planning.
/plugin marketplace add samjhecht/wrangler/plugin install wrangler@samjhecht-pluginsThis skill inherits all available tools. When active, it can use any tool Claude has access to.
MANDATORY: When using this skill, announce it at the start with:
š§ Using Skill: refining-specifications | [brief purpose based on context]
Example:
š§ Using Skill: refining-specifications | [Provide context-specific example of what you're doing]
This creates an audit trail showing which skills were applied during the session.
You are an expert software engineer and product designer. Your job is to review a feature specification file and suggest refinements. Review the provided spec with the aim of detecting and reducing ambiguity or missing decision points.
For each category with Partial or Missing status, add a candidate question opportunity unless:
Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Apply these constraints:
Add your questions to a new section at the bottom of the spec titled "Open Questions for Clarification".
Update the specification file with:
## Open Questions for Clarification
### Question 1: [Category - Brief Topic]
**Question**: [Clear, specific question]
**Options** (if multiple choice):
- A: [Option description]
- B: [Option description]
- C: [Option description]
**Impact**: [Why this matters for implementation]
---
### Question 2: [Category - Brief Topic]
**Question**: [Clear, specific question (answer in <=5 words)]
**Impact**: [Why this matters]
---
[... up to 5 questions total]
writing-specifications - Create initial specrefining-specifications - Detect and resolve ambiguitywriting-plans - Create detailed implementation planAfter spec creation: Run refinement to catch gaps before planning Before implementation: Ensure all decisions are clear After feedback: Incorporate stakeholder input and re-check for gaps
User: "Review the auth spec for gaps" You: Scan taxonomy, identify missing error handling approach, unclear session timeout, ambiguous "secure" requirement, generate 3-5 questions
User: "Is this spec ready for planning?" You: Check completeness across taxonomy, identify missing acceptance criteria, unclear performance requirements, add questions section
User: "We got feedback on the spec, check for new gaps" You: Re-scan with new information, identify areas still ambiguous, prioritize remaining questions
A good refinement session:
ā Identifies genuine ambiguities that would cause implementation confusion ā Asks questions that materially impact design decisions ā Prioritizes high-impact uncertainties ā Limits questions to 5 most critical ā Makes questions easy to answer (multiple choice or short phrase) ā Focuses on what can't be deferred to planning phase
writing-specifications - Create specifications (use before refinement)validating-roadmap - Check consistency across multiple specs (use for projects with many specs)writing-plans - Create implementation plans (use after refinement)Master defensive Bash programming techniques for production-grade scripts. Use when writing robust shell scripts, CI/CD pipelines, or system utilities requiring fault tolerance and safety.