define-requirement

name	define-requirement
description	Gathers the requirement from the user and produces it_{iteration}_product-requirement-document_001.md (indexed). Triggered by: nvst define requirement.
user-invocable	true

Create Product Requirement Document

Produce it_{current_iteration}_product-requirement-document_{index3}.md in .agents/flow/ by interviewing the user about the feature or change they want to build.

Important: Do NOT start implementing. Just gather the requirement and write the document.

---

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. "user wants auth feature", "scope: login + logout").
• Purpose: reduce token usage during reasoning (question selection, scope inference, PRD structuring) without degrading output quality.
• User-facing output is unaffected: questions asked to the user, PRD content, and state updates must remain complete, clear, and fully formed.

---

The Job

1. Check if .agents/state.json exists. If it does, read it to obtain current_iteration (and any other required fields). If it does not exist, ask the user to provide the required information:
   • A. Enter the 6-digit iteration number (e.g. 000037)
2. Understand the project first. Read AGENTS.md, .agents/PROJECT_CONTEXT.md, and explore the codebase structure (main entry points, conventions, existing features) before starting the interview. This context will make your questions more relevant and the PRD better aligned with the project.
3. Ask 3–5 clarifying questions (see Questions Flow).
4. Generate the document following the Output Structure.
5. Write to .agents/flow/it_{current_iteration}_product-requirement-document_{index3}.md where {index3} is the zero-padded 3-digit PRD index (e.g. 001 for the first PRD in the iteration).
6. If .agents/state.json exists, update it: requirement_definition.status = "in_progress", requirement_definition.file = filename. If it does not exist (standalone mode), skip this step and notify the user: "Running standalone — state.json not found, skipping state update."

---

Questions Flow

CRITICAL: Ask ONE question at a time. Wait for the user's answer before asking the next question. Do NOT present all questions at once.

Ask only questions where the initial prompt is ambiguous. Present lettered options so the user can reply with short codes (e.g. "1A").

Questions to ask (one by one, in order):

1. What problem does this solve or goal does it achieve?
   • A. [inferred option]
   • B. [inferred option]
   • C. Other: [please specify]

(Wait for answer, then ask question 2)

2. Who is the primary user or actor?
   • A. End user / customer
   • B. Internal operator / admin
   • C. Another system or automated process
   • D. Other: [specify]

(Wait for answer, then ask question 3)

3. MVP scope — what is the minimum set of use cases needed to validate the idea? List only the user stories you consider strictly necessary. (e.g. "UC-1: user can log in, UC-2: user can view dashboard")

(Wait for answer, then ask question 4)

4. Are there hard constraints (deadline, platform, dependencies)? (Skip if the user says none)

(Wait for answer, then ask question 5)

5. What does "done" look like? How will we know it works? (Describe acceptance criteria or how you'd verify success)

(Wait for answer, then generate the document)

---

Output Structure

# Requirement: [Feature or Change Name]

## Context
Brief description of the problem or opportunity this addresses.

## Goals
- [Specific, measurable objective]
- …

## User Stories
Each story must be small enough to implement in one focused session.

### US-001: [Title]
**As a** [actor], **I want** [capability] **so that** [benefit].

**Acceptance Criteria:**
- [ ] [Specific, verifiable criterion — not vague]
- [ ] [Another criterion]
- [ ] Typecheck / lint passes
- [ ] **[UI stories only]** Visually verified in browser

### US-002: …

## Functional Requirements
- FR-1: …
- FR-2: …

## Non-Goals (Out of Scope)
- …

## Open Questions
- …

---

Writing Guidelines

• MVP first: include only the user stories from the answer to question 3. If the user did not list explicit stories, propose the smallest set possible and confirm before writing. Do not pad scope.
• Be explicit and unambiguous — the reader may be a junior developer or an AI agent.
• Acceptance criteria must be verifiable: "button shows confirmation dialog before deleting" ✓ — "works correctly" ✗.
• Every story with a UI change must include browser verification as an acceptance criterion.
• Number requirements (FR-N) for easy cross-reference with it_{iteration}_PRD.json.

---

---

After writing the PRD: Resolve open questions

CRITICAL: Do this at the end of the session, after you have written the PRD file and before you update state.json.

1. Detect open questions. Read the PRD file you just wrote (.agents/flow/it_{current_iteration}_product-requirement-document_{index3}.md). If it contains a section ## Open Questions with one or more list items (lines starting with - or * or a number), treat each list item as an open question. Skip placeholders such as "None", "…", or "TBD" — only ask items that are real questions.
2. Ask the open questions one by one. For each open question (in order), ask the user that question. When asking each open question, always include valid suggestions or inferred options (e.g. lettered choices A, B, C, or "Other: [specify]") so the user has helpful context to provide an answer. Infer options from the PRD context when possible; if none fit, offer at least 2–3 plausible options plus "Other".
3. Wait for the user's answer before proceeding. After asking a question, wait for the user to respond. Only then ask the next question (or, if there are no more, proceed to update state.json and finish).

If there are no open questions (section missing or only placeholders), skip this block and go straight to the state update step (step 6).

---

Checklist

Before saving:

• Clarifying questions asked and answered
• Each user story has verifiable acceptance criteria
• Functional requirements are numbered and unambiguous
• Non-goals define clear scope boundaries
• File written to .agents/flow/it_{current_iteration}_product-requirement-document_{index3}.md
• Open questions (if any) asked one by one with suggestions/options per question, and user answers collected
• If .agents/state.json exists: requirement_definition.status = "in_progress", requirement_definition.file set. If absent (standalone): user notified "Running standalone — state.json not found, skipping state update."