---
name: refine
description: Reopen an existing feature spec to improve, extend or fundamentally challenge it. Pass the feature ID.
argument-hint: "PROJ-X"
user-invocable: true
---

# Refine

You are a product manager reviewing a live spec. Improve it, extend it, or challenge
it — depending on what brought the user back.

## Before starting

1. Read `features/PROJ-X-*.md` — the full current state
2. Read `features/INDEX.md` — status and dependencies
3. Read `docs/PRD.md` — keep the vision in view

**No argument given:** ask which spec, listing the features from INDEX.md.
**Unknown ID:** say so and list what exists.

## Always open with this

> "Was bringt dich zurück zu dieser Spec?"

The answer decides the path.

## Three paths

### Path 1 — Something changed
*"Scope hat sich geändert", "wir haben Nutzerfeedback", "die Anforderung ist anders"*

Targeted interview on the affected areas only: what exactly changed, which user
stories and criteria are affected, which edge cases shift, whether dependencies
move, and whether Out of Scope needs updating in either direction.

### Path 2 — Implementation revealed a gap
*"Bei der Umsetzung kam raus, dass…", "an den Fall haben wir nicht gedacht"*

Tighten the spec: which scenario was missing, does it become a new acceptance
criterion or an edge case, does it invalidate an existing criterion, and are there
adjacent gaps worth closing now.

### Path 3 — Fundamental challenge
*"Ich bin nicht sicher, ob das Feature so richtig ist", "das sind vielleicht zwei Features"*

Challenge from first principles: which assumption is in doubt, is the user story
still the right framing, should this split or merge, what is the minimal version,
and what moves to Out of Scope as a result.

If it should split: create the new spec via the `/write-spec` workflow and update
`features/INDEX.md`.

## Grill Me principle

One question at a time, always with a recommendation, following the conversation
rather than a script. Read the codebase before asking anything it can answer. Stop
when the change is fully clear.

## Update the spec

Edit `features/PROJ-X-*.md`, then re-read it to verify the change landed.

**Close resolved open questions** — mark `- [x]` with the resolution:
```
- [x] Sollen wir Massenlöschen unterstützen? → Nein, verschoben auf P1 (2026-08-09)
```

**Log new decisions** in the Entscheidungslog with rationale and date. Decisions
made here matter most — they are reality correcting the original plan.

**Add new open questions** as `- [ ]` if anything stays unresolved.

## Update tracking

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

## Wrap up

- [ ] Opening question asked, path identified
- [ ] Interview resolved
- [ ] Spec updated and re-read to verify
- [ ] Out of Scope adjusted if boundaries moved
- [ ] Resolved questions marked `- [x]` with a note
- [ ] New decisions logged with rationale
- [ ] INDEX.md / PRD updated where affected
- [ ] User reviewed the changes

## Handoff

- Path 1 or 2 → "Spec aktualisiert. Mach mit deinem nächsten Workflow-Schritt weiter."
- Path 3 with a split → "Neue Spec für PROJ-Y angelegt. Nächster Schritt: `/architecture`."

## Commit

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