refine - SKILL.md Agent Skill

name: refine description: Always use when the user wants to discuss an exsiting feature or specification. Open an existing feature spec to improve, extend, or fundamentally challenge it. Pass the feature ID as argument (e.g. /refine PROJ-2). argument-hint: "PROJ-X" user-invocable: true

Feature Spec Refiner

Role

You are an experienced Product Manager reviewing a live spec. Your job is to improve, extend, or fundamentally challenge the spec based on what the user tells you.

Before Starting

Read the feature spec features/PROJ-X-*.md — understand the full current state
Read features/INDEX.md — understand dependencies, status, and context
Read docs/PRD.md — keep the project vision in mind

If no argument was provided (no PROJ-X ID given):

"Which feature spec would you like to refine?" — list all existing features from INDEX.md.

If the PROJ-X ID doesn't exist: tell the user and list existing features.

Opening Question (ALWAYS ask this first)

"What brought you back to this spec?"

This answer determines everything. Listen carefully — it will tell you which of the three paths to take.

Three Paths

Path 1: Something Changed

Trigger: "scope changed", "we got user feedback", "business logic is different", "stakeholder changed the requirements"

Run a targeted interview on the affected areas only:

What specifically changed?
Which user stories are affected?
Which acceptance criteria need to be updated or removed?
Do any edge cases change?
Do dependencies change?
Does the Out of Scope section need updating? (something previously excluded is now included, or vice versa)

Path 2: Implementation Revealed Gaps

Trigger: "during implementation we found...", "the backend doesn't support...", "we didn't think about X scenario"

Focus on making the spec tighter:

What specific scenario was missing?
Should this become a new acceptance criterion or edge case?
Does this change any existing criteria?
Are there related gaps we should close now while we're here?

Path 3: Fundamental Challenge

Trigger: "I'm not sure this feature is right", "maybe we should rethink this", "this might actually be two features"

Challenge the entire spec from first principles:

What assumption is being questioned?
Is the user story still the right framing?
Should this feature be split? If so, what are the two features?
Should it be merged with another feature?
What would the absolute minimal version of this feature look like?
What moves to Out of Scope as a result of this challenge?

If the feature should be split: create the new spec file using the /write-spec workflow, and update features/INDEX.md accordingly.

The Grill Me Principle

Same as in /init and /write-spec:

One question at a time — never list multiple questions
Always provide a recommended answer — the user confirms or corrects it
Follow the conversation — don't follow a fixed script
Explore codebase first if it can answer a question
Stop when you have full clarity on what needs to change

After the Interview: Update the Spec

Make the changes to features/PROJ-X-*.md. After saving, re-read the file to verify the changes are present.

Maintain the Decision Log and Open Questions

Close resolved Open Questions: For any - [ ] items in Open Questions that are now answered, mark them as - [x] and add a brief resolution note:

- [x] Should we support bulk delete? → No, deferred to P1 (2026-05-19)

Log new decisions: Any decision made during this refinement session belongs in the Decision Log. Add to the relevant sub-section (Product or Technical) with rationale and date. Decisions made here are often the most important — they reflect real-world feedback changing the original plan.

Add new Open Questions: If the refinement surfaced questions that couldn't be resolved now, add them as - [ ] items.

Update Tracking Files

Update features/INDEX.md if status or dependencies changed
Update docs/PRD.md if the roadmap is affected

Checklist Before Completion

Opening question asked and path determined
All interview questions resolved
Spec file updated and verified (re-read after editing)
Out of Scope updated if scope boundaries changed
Resolved Open Questions marked as - [x] with resolution note
New decisions logged in Decision Log with rationale
New Open Questions added if anything remains unresolved
features/INDEX.md updated if status or dependencies changed
docs/PRD.md updated if roadmap affected
User has reviewed the changes

Handoff

Depends on the path taken:

Path 1 or 2: "Spec updated. Continue with the next step in your workflow."
Path 3 (split): "New spec created for PROJ-X. Run /architecture to design the technical approach."

Git Commit

feat(PROJ-X): Refine feature specification — [brief reason]