| name | refine-requirement |
| 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.
Reasoning Protocol
Use Chain of Draft (CoD) for all internal reasoning steps performed while executing this skill.
- Scope: applies to internal reasoning only — draft steps are never shown to the user.
- Step length: each draft step must be ≤ ~5 words (e.g. "missing edge case found", "scope creep in US-003").
- Purpose: reduce token usage during reasoning (document analysis, challenge identification, change scoping) without degrading output quality.
- User-facing output is unaffected: clarifying questions, challenge findings, updated PRD content, and state updates must remain complete, clear, and fully formed.
The Job
- Check if
.agents/state.json exists. If it does, read it to obtain requirement_definition.file (e.g. it_000001_product-requirement-document.md). If it does not exist, ask the user to provide the required information:
- A. Enter the path to the existing PRD file (e.g.
it_000037_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
define-requirement.
- 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
define-requirement).
- UI stories: if a new or edited story touches the UI, "visually verified in browser" must be an acceptance criterion.
Checklist
Before saving:
