Requirements Detective Handbook
"The hardest part of building software isn't how to implement it—it's precisely defining what to implement."
Your job is to eliminate ambiguity.
genesis Step 2 (scope and handoff)
Compared with templates/.agents/skills/spec-writer, this template adds craft scaffolding, spec contract (on-disk semantics), sub-agent orchestration, and completion. The normative force of Execution checklist / Methodology / 10-dimension ambiguity scan / User Story quality gate sections is unchanged—rules such as Socratic probing, one question at a time, the hard cap on [NEEDS CLARIFICATION], Non-Goals, and the User Story gate apply verbatim.
Craft scaffolding (artifact skeleton)
Before Execution checklist step 4 (writing 01_PRD.md), the skeleton must first be in place; when filling content, do not remove normative sections from the template. Where there is no information, write [NOT APPLICABLE | reason] or [ASSUMPTION]—never leave blanks that pretend completeness.
| Artifact |
Path |
Requirement |
| Version directory |
.anws/v{N}/ |
v{N} must match host genesis / session convention; create on first round or explicitly reuse existing v{N}; silent fork forbidden. |
| PRD |
.anws/v{N}/01_PRD.md |
Single source of truth for Step 2 output; content driven by references/prd_template.md; forbidden to replace on-disk artifact with long chat-only prose only. |
| Template |
references/prd_template.md |
Read in full before drafting PRD; heading levels and mandatory sections follow the template; extra appendices allowed but cannot replace mandatory template sections. |
Readiness check (internal; may summarize for user): v{N} chosen; this SKILL + prd_template.md read; enumerate at least 3 User Story drafts and ≥3 Non-Goals before expanding written PRD sections.
Spec contract (PRD on-disk semantics)
[!IMPORTANT]
When folded into the genesis pipeline, PRD sections are treated as assertable draft contracts for downstream work (architecture, task breakdown, challenge) and must satisfy:
- Verifiable: Any statement of "must / must not / SLA / user counts / compatibility" needs Given-When-Then, metrics, or enumerated options; otherwise it cannot be marked as implemented—only
[ASSUMPTION] or move to Non-Goals.
- Traceable: Every User Story carries
[REQ-XXX]; terms and systems must be internally consistent with "Affected systems" below (when aligning to 02_ARCHITECTURE_OVERVIEW.md downstream, no arbitrary renames).
- Ambiguity-bounded:
[NEEDS CLARIFICATION] ≤ 3 (hard limit); if exceeded, use defaults + [ASSUMPTION: …]; forbidden to re-ask generic defaults stated in this document's 10-dimension scan to pad counts.
- Value-traceable: Every requirement aligns to user value in one sentence; Non-Goals and Goals are mutually exclusive with no empty "maybe won't do".
- Consistent: The same fact is not stated twice contradictorily in summary vs detail; fixes use atomic paragraph replacement, not side-by-side conflicting wording.
Challenge / downstream alignment: If excerpts from the PRD appear in reports or attachments, excerpts must carry subsection anchors or stable headings from 01_PRD.md; do not cite only "see PRD".
Sub-agent orchestration (optional)
When the host supports parallel sub-sessions:
| Role |
Responsibility |
| Parent agent |
Choose v{N}, load user intent and context, merge structured blocks returned by sub-agents, dedupe and pick best among same-topic answers, maintain single writer for .anws/v{N}/01_PRD.md, run mandatory "10-dimension ambiguity scan" and User Story quality gate, then deliver for user confirmation. |
| Sub-agent |
Consumes bounded slices only—e.g. "generate clarification question batches only (with suggested answers)", "extract / rewrite User Stories only (still drafts)", "annotate dimension k of the 10-dimension table with Clear/Partial/Missing + patch suggestions", "rewrite feeling words into candidate metric lists only"; return Markdown structured blocks + anchor suggestions; do not assume access to parent-only context. |
Single writer: Only one writer for 01_PRD.md per genesis Step 2 round; sub-agents must not write that path without parent authorization.
Handoff checklist (sub → parent)
Completion (genesis Step 2 done signal)
Step 2 must not be claimed complete unless all of:
| Gate |
Condition |
| On-disk |
.anws/v{N}/01_PRD.md exists and opens standalone; structure aligns with mandatory sections of prd_template.md. |
| Content |
Contains User Stories (pass quality gate), acceptance criteria, ≥3 Non-Goals; every requirement is testable, measurable, or explicitly assumed. |
| Ambiguity |
"10-dimension ambiguity scan" executed; every Partial / Missing fixed, [ASSUMPTION]-ized, or closed under hard-limit rules. |
| Tags |
[NEEDS CLARIFICATION] ≤ 3; no Story has untracked feeling words unless rewritten or assumed away. |
| Human |
User confirmed PRD (or explicitly waived in writing logged as [ASSUMPTION: stakeholder sign-off deferred]); do not fake confirmation. |
| Handoff |
Parent delivered short summary table to user (goals / key REQ count / open clarifications / Non-Goals count / recommended reading order for next Step). |
Failing any hard row above → Step 2 is blocked / in_progress; do not silently advance the pipeline into architecture drafting.
Execution checklist (single source of order)
Aligned with craft scaffolding and the completion table above; release is gated by completion hard rows—this section only sequences work (merges former Quick start / Mandatory steps / Completion checklist to avoid duplicate reading).
- Read the request: identify feeling words and hidden boundaries (mandatory).
- Think deeply: 3–7 rounds of structured reasoning (by complexity); produce User Story drafts, ambiguity, clarification questions (mandatory).
- Probe for answers: do not advance the main line until answers arrive (mandatory).
- Before disk: ≥3 User Stories, ≥3 Non-Goals, clarify feeling words; read
references/prd_template.md, create .anws/v{N}/01_PRD.md—do not substitute chat for disk (mandatory).
- After disk: run the 10-dimension ambiguity scan and close
Partial / Missing; User Story quality gate; [NEEDS CLARIFICATION] ≤ 3 (mandatory).
- Close: satisfy completion hard rows + user sign-off on PRD (or logged waiver).
Methods and tools
1. Socratic probing
- User: "I want it to be fast."
- You: "Does that mean p99 under 100ms? Or optimistic UI updates only?"
- Goal: Turn adjectives into numbers and verifiable criteria.
2. Context compression
- Input: 500-line chat log.
- Action: Extract User Stories—"As a User, I want X, so that Y."
- Drop: Premature implementation details (e.g. "use Redis").
3. Non-Goals (draw the circle)
- Explicitly define what we do not do.
- Why: Prevent scope creep and endless "what about X?" follow-ups.
Detective rules
- Contract first: If it cannot be verified, do not put it in the PRD.
- Don't steal design work: Describe what to do, not prematurely how. Implementation belongs in architecture.
- User value first: Every requirement must trace to clear user value.
Toolbox
references/prd_template.md: Product requirements template.
10-dimension ambiguity scan
After drafting the PRD, you must scan the full text across these 10 dimensions. This replaces ad-hoc "anything else?" with a repeatable, exhaustive pass.
For each dimension, mark status: Clear / Partial / Missing
| # |
Dimension |
What to check |
Status |
| 1 |
Functional scope and behavior |
Core goals / success criteria / explicit exclusions / user role distinction |
|
| 2 |
Domain and data model |
Entities, attributes, relationships / uniqueness rules / lifecycle and state transitions / data volume assumptions |
|
| 3 |
Interaction and UX flows |
Key user paths / error, empty, loading states / a11y and i18n |
|
| 4 |
Non-functional quality |
Performance / scalability / reliability / observability / security and privacy / compliance |
|
| 5 |
Integrations and externals |
External failure modes / import-export formats / protocol version assumptions |
|
| 6 |
Edge cases and failures |
Negative paths / rate limits / concurrent conflict handling |
|
| 7 |
Constraints and tradeoffs |
Technical constraints / explicit tradeoffs / rejected architecture options |
|
| 8 |
Terminology consistency |
Glossary / synonym unification across the doc |
|
| 9 |
Done signals |
Acceptance testable? / DoD quantifiable? |
|
| 10 |
Placeholders and vague words |
TODOs / unquantified adjectives (fast, scalable, secure, intuitive, robust) |
|
Rules:
- For
Partial or Missing, sort by impact × uncertainty, ask user about top 5
- One question at a time; offer a suggested answer; user may accept or customize
- After answers, atomically write the matching PRD section; no mutually contradictory text
[NEEDS CLARIFICATION] hard cap ≤ 3; if still over, use reasonable defaults + [ASSUMPTION: ...]- Do not ask users to clarify these reasonable defaults: industry-standard data retention, typical web/mobile performance expectations, friendly errors with fallbacks, standard Session or OAuth2 authentication
User Story quality gate
Every User Story in the PRD must pass before the PRD is considered done:
| Check |
Requirement |
| Unique ID |
Must include [REQ-XXX] for traceability |
| Priority |
P0 / P1 / P2, P0 first |
| Independently testable |
How the story is independently demoed and verified |
| Affected systems |
Concrete system IDs (must align with 02_ARCHITECTURE_OVERVIEW.md) |
| Acceptance criteria |
At least one Given-When-Then + at least one error path |
| Edge cases |
At least one boundary condition |
| No vague feeling words |
No unquantified adjectives (e.g. fast → <100ms p99; scalable → supports N users) |
| User value |
One-sentence end-user value |
If any User Story fails, fix before delivering the PRD.
1---2name: spec-writer-23description: genesis Step 2: turn fuzzy or high-level needs into strict product requirement documents (PRDs); includes craft scaffolding, PRD spec contract, optional sub-agent shard orchestration, and Step completion signals. Use when requirements are vague, scope is too large, or expression stays conceptual.4---56# Requirements Detective Handbook78> "The hardest part of building software isn't how to implement it—it's precisely defining what to implement."910Your job is to **eliminate ambiguity**.1112## genesis Step 2 (scope and handoff)1314Compared with `templates/.agents/skills/spec-writer`, this template adds **craft scaffolding**, **spec contract** (on-disk semantics), **sub-agent orchestration**, and **completion**. The normative force of **Execution checklist / Methodology / 10-dimension ambiguity scan / User Story quality gate** sections is **unchanged**—rules such as Socratic probing, **one question at a time**, the hard cap on `[NEEDS CLARIFICATION]`, Non-Goals, and the User Story gate **apply verbatim**.1516### Craft scaffolding (artifact skeleton)1718Before **Execution checklist** step 4 (writing `01_PRD.md`), the skeleton **must first** be in place; when filling content, **do not remove normative sections** from the template. Where there is no information, write **`[NOT APPLICABLE | reason]`** or **`[ASSUMPTION]`**—never leave blanks that pretend completeness.1920| Artifact | Path | Requirement |21|----------|------|---------------|22| Version directory | `.anws/v{N}/` | `v{N}` must match host genesis / session convention; create on first round or explicitly reuse existing `v{N}`; silent fork forbidden. |23| PRD | `.anws/v{N}/01_PRD.md` | **Single source of truth** for Step 2 output; content driven by `references/prd_template.md`; **forbidden** to replace on-disk artifact with long chat-only prose only. |24| Template | `references/prd_template.md` | Read in full **before** drafting PRD; heading levels and mandatory sections follow the template; extra appendices allowed but cannot replace mandatory template sections. |2526**Readiness check (internal; may summarize for user):** `v{N}` chosen; this SKILL + `prd_template.md` read; enumerate at least 3 User Story drafts and ≥3 Non-Goals before expanding written PRD sections.2728### Spec contract (PRD on-disk semantics)2930> [!IMPORTANT]31> When folded into the genesis pipeline, PRD sections are treated as **assertable draft contracts** for downstream work (architecture, task breakdown, challenge) and must satisfy:32>33> - **Verifiable:** Any statement of "must / must not / SLA / user counts / compatibility" needs Given-When-Then, metrics, or enumerated options; otherwise it cannot be marked as implemented—only `[ASSUMPTION]` or move to Non-Goals. 34> - **Traceable:** Every User Story carries `[REQ-XXX]`; terms and systems must be **internally consistent** with "Affected systems" below (when aligning to `02_ARCHITECTURE_OVERVIEW.md` downstream, no arbitrary renames). 35> - **Ambiguity-bounded:** `[NEEDS CLARIFICATION]` **≤ 3** (hard limit); if exceeded, use defaults + `[ASSUMPTION: …]`; **forbidden** to re-ask generic defaults stated in this document's 10-dimension scan to pad counts. 36> - **Value-traceable:** Every requirement aligns to user value in one sentence; Non-Goals and Goals are **mutually exclusive** with no empty "maybe won't do". 37> - **Consistent:** The same fact is **not stated twice contradictorily** in summary vs detail; fixes use **atomic paragraph replacement**, not side-by-side conflicting wording.3839Challenge / downstream alignment: If excerpts from the PRD appear in reports or attachments, excerpts must carry **subsection anchors** or **stable headings from `01_PRD.md`**; do not cite only "see PRD".4041### Sub-agent orchestration (optional)4243When the host supports parallel sub-sessions:4445| Role | Responsibility |46|------|----------------|47| **Parent agent** | Choose `v{N}`, load user intent and context, merge structured blocks returned by sub-agents, **dedupe and pick best among same-topic answers**, maintain **single writer** for `.anws/v{N}/01_PRD.md`, run mandatory "10-dimension ambiguity scan" and User Story quality gate, then deliver for user confirmation. |48| **Sub-agent** | Consumes bounded slices only—e.g. "generate clarification question batches only (with suggested answers)", "extract / rewrite User Stories only (still drafts)", "annotate dimension k of the 10-dimension table with Clear/Partial/Missing + patch suggestions", "rewrite feeling words into candidate metric lists only"; return **Markdown structured blocks + anchor suggestions**; do not assume access to parent-only context. |4950**Single writer:** Only **one** writer for `01_PRD.md` per genesis Step 2 round; sub-agents must not write that path without parent authorization.5152#### Handoff checklist (sub → parent)5354- [ ] State deliverable type (question list / Story draft / scan vector / feeling-word metric table) and **N/A dimensions** (one-line reason each).55- [ ] Every item maps to a **subsection title or `[REQ-XXX]` placeholder** the PRD will use; if no anchor, mark "pending parent mount".56- [ ] Do not introduce requirements conflicting with parent-declared Non-Goals; if conflict is possible, list "requires parent ruling".57- [ ] Sub-agent stops at structured handoff; subsequent edits merged by parent.5859### Completion (genesis Step 2 done signal)6061Step 2 **must not be claimed complete** unless all of:6263| Gate | Condition |64|------|-----------|65| On-disk | `.anws/v{N}/01_PRD.md` exists and opens standalone; structure aligns with **mandatory sections** of `prd_template.md`. |66| Content | Contains User Stories (pass quality gate), acceptance criteria, **≥3** Non-Goals; every requirement is testable, measurable, or explicitly assumed. |67| Ambiguity | "10-dimension ambiguity scan" executed; every `Partial` / `Missing` fixed, `[ASSUMPTION]`-ized, or closed under hard-limit rules. |68| Tags | `[NEEDS CLARIFICATION]` **≤ 3**; no Story has untracked feeling words unless rewritten or assumed away. |69| Human | **User confirmed PRD** (or explicitly waived in writing logged as `[ASSUMPTION: stakeholder sign-off deferred]`); do not fake confirmation. |70| Handoff | Parent delivered **short summary table** to user (goals / key REQ count / open clarifications / Non-Goals count / recommended reading order for next Step). |7172Failing any **hard** row above → Step 2 is **blocked / in_progress**; do not silently advance the pipeline into architecture drafting.7374---7576## Execution checklist (single source of order)7778Aligned with **craft scaffolding** and the **completion** table above; release is gated by **completion hard rows**—this section only sequences work (merges former Quick start / Mandatory steps / Completion checklist to avoid duplicate reading).79801. **Read the request**: identify feeling words and hidden boundaries (mandatory).812. **Think deeply**: 3–7 rounds of structured reasoning (by complexity); produce User Story drafts, ambiguity, clarification questions (mandatory).823. **Probe for answers**: do not advance the main line until answers arrive (mandatory).834. **Before disk**: ≥3 User Stories, ≥3 Non-Goals, clarify feeling words; read `references/prd_template.md`, create `.anws/v{N}/01_PRD.md`—**do not** substitute chat for disk (mandatory).845. **After disk**: run the **10-dimension ambiguity scan** and close `Partial` / `Missing`; User Story quality gate; `[NEEDS CLARIFICATION]` ≤ 3 (mandatory).856. **Close**: satisfy **completion** hard rows + user sign-off on PRD (or logged waiver).8687## Methods and tools8889### 1. Socratic probing90* **User:** "I want it to be fast."91* **You:** "Does that mean p99 under 100ms? Or optimistic UI updates only?"92* *Goal:* Turn adjectives into numbers and verifiable criteria.9394### 2. Context compression95* **Input:** 500-line chat log.96* **Action:** Extract *User Stories*—"As a User, I want X, so that Y."97* **Drop:** Premature implementation details (e.g. "use Redis").9899### 3. Non-Goals (draw the circle)100* Explicitly define what we **do not do**.101* *Why:* Prevent scope creep and endless "what about X?" follow-ups.102103## Detective rules1041051. **Contract first:** If it cannot be verified, do not put it in the PRD.1062. **Don't steal design work:** Describe *what* to do, not prematurely *how*. Implementation belongs in architecture.1073. **User value first:** Every requirement must trace to clear user value.108109## Toolbox110* `references/prd_template.md`: Product requirements template.111112## 10-dimension ambiguity scan113114After drafting the PRD, you **must** scan the full text across these 10 dimensions. This replaces ad-hoc "anything else?" with a **repeatable, exhaustive** pass.115116For each dimension, mark status: `Clear` / `Partial` / `Missing`117118| # | Dimension | What to check | Status |119|---|-----------|---------------|:------:|120| 1 | **Functional scope and behavior** | Core goals / success criteria / explicit exclusions / user role distinction | |121| 2 | **Domain and data model** | Entities, attributes, relationships / uniqueness rules / lifecycle and state transitions / data volume assumptions | |122| 3 | **Interaction and UX flows** | Key user paths / error, empty, loading states / a11y and i18n | |123| 4 | **Non-functional quality** | Performance / scalability / reliability / observability / security and privacy / compliance | |124| 5 | **Integrations and externals** | External failure modes / import-export formats / protocol version assumptions | |125| 6 | **Edge cases and failures** | Negative paths / rate limits / concurrent conflict handling | |126| 7 | **Constraints and tradeoffs** | Technical constraints / explicit tradeoffs / rejected architecture options | |127| 8 | **Terminology consistency** | Glossary / synonym unification across the doc | |128| 9 | **Done signals** | Acceptance testable? / DoD quantifiable? | |129| 10 | **Placeholders and vague words** | TODOs / unquantified adjectives (fast, scalable, secure, intuitive, robust) | |130131**Rules:**132- For `Partial` or `Missing`, sort by **impact × uncertainty**, ask user about top **5**133- **One question at a time**; offer a suggested answer; user may accept or customize134- After answers, **atomically write** the matching PRD section; no mutually contradictory text135- `[NEEDS CLARIFICATION]` **hard cap ≤ 3**; if still over, use reasonable defaults + `[ASSUMPTION: ...]`136- **Do not ask users to clarify these reasonable defaults:** industry-standard data retention, typical web/mobile performance expectations, friendly errors with fallbacks, standard Session or OAuth2 authentication137138## User Story quality gate139140Every User Story in the PRD **must** pass before the PRD is considered done:141142| Check | Requirement |143|-------|---------------|144| **Unique ID** | Must include `[REQ-XXX]` for traceability |145| **Priority** | P0 / P1 / P2, P0 first |146| **Independently testable** | How the story is **independently** demoed and verified |147| **Affected systems** | Concrete system IDs (must align with `02_ARCHITECTURE_OVERVIEW.md`) |148| **Acceptance criteria** | At least one Given-When-Then + at least one error path |149| **Edge cases** | At least one boundary condition |150| **No vague feeling words** | No unquantified adjectives (e.g. fast → <100ms p99; scalable → supports N users) |151| **User value** | One-sentence end-user value |152153If any User Story fails, **fix before delivering the PRD**.
haaaiawd