| name | refine-pr-document |
| description | Updates an existing product requirement document based on user feedback. Triggered by: nvst refine requirement. |
| user-invocable | true |
Refine Product Requirement Document
Update it_{current_iteration}_product-requirement-document.md in place based on user feedback. The file must already exist; this skill does not create it from scratch.
Do NOT start implementing. Only update the document.
Two modes available — the agent asks at the start:
- Editor mode — apply specific changes requested by the user.
- Challenger mode — act as an independent critical reviewer: challenge assumptions, question scope, find gaps, and propose improvements. The user accepts or rejects each suggestion before anything is written.
The Job
- Read
state.json → get requirement_definition.file (e.g. it_000001_product-requirement-document.md).
- Read the current document from
.agents/flow/{file}.
- Open by asking: "Would you like me to challenge the existing document as an independent reviewer, or would you prefer to tell me what to change?"
- Answer → challenge: run Challenger Mode (see below).
- Answer → edit: run Editor Mode (see Questions Flow).
- Apply changes to the document following the same Output Structure as
create-pr-document.
- Re-enforce MVP constraint: remove any user stories not explicitly listed by the user; do not add new ones without confirmation.
- Write the updated file back to the same path.
- Do not update
state.json — requirement_definition.status stays "in_progress".
Challenger Mode
Act as a second agent reviewing the document with fresh eyes. Do not apply any change without explicit user approval.
Challenge areas — examine each (in order):
- Assumptions — List implicit assumptions in the goals or stories. Ask: are these validated? what if they are wrong?
- Scope creep — Flag any user story that is not strictly MVP-necessary. Propose removal and ask for confirmation.
- Vague acceptance criteria — Highlight criteria that are not concretely verifiable. Suggest a specific rewrite.
- Missing non-goals — Identify things the document is silent on that could be misread as in-scope. Propose additions to Non-Goals.
- Missing edge cases — Point out failure paths or user states not covered by any acceptance criterion.
- Conflicting requirements — Flag any
FR-N that contradicts another or contradicts an acceptance criterion.
Challenger output format — one observation at a time:
CRITICAL: Present findings one at a time. After delivering one finding, stop and wait for the user to respond before moving on. Do not queue or batch findings.
For each finding, format it as:
Challenge [N/total]: <area name>
Finding: <what the issue is>
Suggestion: <proposed change>
Accept / Reject / Discuss?
- After the user responds, acknowledge their decision and immediately present the next finding.
- If the user types Discuss, engage in a short back-and-forth until they give a final Accept or Reject, then move on.
- Once all findings have been reviewed, summarise the accepted changes and apply them to the file in a single write.
- Do not write anything to the file until all findings have received a response.
Editor Mode (Questions Flow)
Ask only what is needed to understand the requested change.
1. What would you like to change or add?
A. Replace or rewrite a user story
B. Add a new user story (must be MVP-justified)
C. Remove a user story
D. Tighten acceptance criteria
E. Update goals or non-goals
F. Other: [describe]
2. If adding a user story — is it strictly necessary for the MVP?
[Open answer — skip if not adding stories]
3. Anything else to update in this pass?
[Open answer — skip if none]
Refinement Rules
- MVP constraint holds: do not add user stories unless the user explicitly requests them and confirms they are MVP-necessary.
- Preserve numbering: renumber
US-NNN and FR-N entries only if a story is removed; otherwise keep existing IDs stable.
- Verifiable criteria: any new or edited acceptance criterion must be concrete and testable (same standard as
create-pr-document).
- UI stories: if a new or edited story touches the UI, "visually verified in browser" must be an acceptance criterion.
Checklist
Before saving:
