Claude-Refine
A Claude Code plugin that converts a rough feature idea into a refined product spec. Distribution via the Claude Code plugin marketplace.
Installation
/plugin marketplace add carlosas/claude-refine
/plugin install claude-refine@claude-refine
Usage
Fresh refinement:
/refine Add a customer search feature
Update an existing spec with additional requirements (@<slug> resolves against .claude-refine/<YYYYMMDDHHMM>-<slug>.md; unique-prefix match works too):
/refine @customer-search also allow filtering by customer tier
Output
/refine writes a refined feature specification inside a .claude-refine/ folder in your project.
Structure:
- Problem Statement: the problem, not the solution
- Target User: concrete, not "users"
- Core Functionality: 1-3 essential things, plain language
- Out of Scope: explicit boundaries
- Success Criteria: measurable, technology-agnostic
- Codebase Context: relevant existing code found during scan (observations, not prescriptions)
- Assumptions: decisions made with rationale
- Open Questions: anything still unresolved
What it does
/refine acts as a senior PM reviewing your feature request:
- Scans your codebase for relevant existing code (entities, services, patterns, auth mechanisms) to ground the refinement in project reality
- Identifies gaps in your feature description using a product taxonomy (problem, target user, scope, success criteria, edge cases)
- Asks targeted questions to the user, only the ones that actually matter
- Writes a spec markdown file, a clean, unambiguous product spec ready to hand to
/plan or any other implementation tool
Inspiration
Editing guidance
Constraints:
- Most changes are prompt-engineering on
skills/refine/SKILL.md. Treat the description, phase rules, output template, and quality checklist as the four load-bearing parts — do not loosen the constraints (e.g., the 8-question cap, the AskUserQuestion-only Q&A rule, the "observations not prescriptions" rule for Codebase Context) without explicit reason.
- Keep the marketplace name and the plugin name (both
claude-refine in marketplace.json) stable — renaming either breaks every existing user's /plugin install claude-refine@claude-refine and forces them to re-add the marketplace.
- In fresh mode the output file is
.claude-refine/.draft-requirement.md, fully overwritten each run (no merge, no history). The Stop hook keys off this exact path; renaming it requires updating hooks/hooks.json in lockstep. In retrofit mode (/refine @<slug> …) the skill does not write .draft-requirement.md at all — it edits the matched dated spec in place by appending to a ## Refinement Updates section, so the Stop hook silently does not fire. Phase 0 of the skill also deletes any stale .draft-requirement.md at retrofit entry to mitigate Stop-hook false-trigger from a previously interrupted run.
- Section order and headings of the base spec are fixed (Problem Statement → Target User → Core Functionality → Out of Scope → Success Criteria → Codebase Context → Assumptions → Open Questions). Downstream tools like
/plan consume this structure. Retrofit and post-plan never mutate these base sections — they append ## Refinement Updates and ## Updates After Planning blocks below them. When both appended sections exist, ## Refinement Updates always appears before ## Updates After Planning (refinement is conceptually pre-plan).
- Problem/Target User/Core Functionality/Out of Scope/Success Criteria sections must contain no technology choices or implementation details. Codebase Context is observations only, never prescriptions. The skill enforces this via a quality checklist that runs before save.
- Hook commands in
hooks/hooks.json must stay POSIX-portable (macOS + Linux). The mtime read uses stat -f %m with a stat -c %Y fallback for exactly this reason.
- Questions are asked via the native
AskUserQuestion tool. ≤4 markers → one round; 5–8 markers → two rounds (max). Never the manual lettered-option chat format.
- Once
/refine finishes and .claude-refine/.draft-requirement.md is written (mtime within 60 seconds), a Stop hook injects a follow-up instruction that invokes the claude-refine:-internal-post-draft skill. No sentinel files, no stale-flag risk if the user interrupts mid-refinement.
