Skill

refine

Refines specification files with AI-assisted improvements for clarity, completeness, testability per INVEST criteria. Generates categorized suggestions, impact reports, and applies interactive or auto changes.

Markdown

documentation

code-quality

npx claudepluginhub melodic-software/claude-code-plugins --plugin spec-driven-development

Tool Access

This skill is limited to using the following tools:

ReadGlobGrepWriteEditSkillTask

Preview

Apply AI-assisted refinement to improve specification quality.

SKILL.md

Similar Skills

refine-spec

Reviews PRDs and specs for completeness, ambiguities, edge cases, acceptance criteria quality. Structures findings by severity and offers direct fixes.

pm-os

requirements-quality

Assesses requirements quality against INVEST criteria, improves clarity, detects ambiguity, ensures completeness, and guides MoSCoW prioritization with checklists and refinement patterns.

3 files6 tools

spec-driven-development

analyze-spec

Analyzes spec files for inconsistencies, missing information, ambiguities, and structure issues. Detects depth level (full-tech, detailed, high-level) and generates markdown/HTML reports.

5 files7 tools

agent-alchemy-sdd-tools

Stats

Parent Repo Stars63

Parent Repo Forks9

Last CommitFeb 15, 2026

Actions

View Source View Plugin View on GitHub View README

Help us improve

Share bugs, ideas, or general feedback.

Refine Specification

Apply AI-assisted refinement to improve specification quality.

Workflow

Load Specification
- Read the specification file
- Parse all requirements and acceptance criteria
Analyze Quality
- Spawn spec-processor refine agent
- Evaluate against INVEST criteria
- Score clarity and completeness
- Identify improvement opportunities
Generate Suggestions
- Clarity enhancements
- Missing acceptance criteria
- Ambiguity resolution
- Requirement splitting recommendations
- Priority adjustments
Present Improvements
- Show suggestions grouped by category
- Indicate impact level (high/medium/low)
- Provide before/after comparisons
Apply Changes
- Interactive: Confirm each change
- Batch: Apply all approved changes
- Update specification file

Arguments

$ARGUMENTS - Path to specification file
--auto - Apply all improvements without confirmation
--focus - Focus area: clarity, completeness, testability, or all

Examples

# Interactive refinement
/spec-driven-development:refine .specs/user-auth/spec.md

# Auto-apply all improvements
/spec-driven-development:refine .specs/user-auth/spec.md --auto

# Focus on clarity
/spec-driven-development:refine .specs/user-auth/spec.md --focus clarity

Refinement Categories

Clarity Enhancements

Remove ambiguous words (some, few, many, etc.)
Add specific values and thresholds
Clarify actor and system boundaries

Completeness Improvements

Add missing acceptance criteria
Add edge case scenarios
Add error handling requirements

Testability Improvements

Make outcomes observable
Add verification methods
Specify expected values

Structure Improvements

Split large requirements
Consolidate duplicates
Improve requirement ordering

Refinement Report

# Refinement Report: user-auth

## Summary
- **Improvements Found:** 8
- **High Impact:** 3
- **Medium Impact:** 4
- **Low Impact:** 1

## Improvements

### HIGH: FR-2 - Ambiguous Threshold
**Before:**
> The system SHALL respond quickly to login requests.

**After:**
> The system SHALL respond to login requests within 500ms (p95).

**Rationale:** "quickly" is ambiguous; specific SLA is testable.

---

### MEDIUM: FR-1 - Missing Error Case
**Added AC:**
> Given the email format is invalid, when submitted, then display "Invalid email format" error.

**Rationale:** Original ACs only covered happy path.

Related Commands

/spec-driven-development:validate - Validate specification
/spec-driven-development:audit - Full quality audit
/spec-driven-development:specify - Generate new specification