| name | spec-writer |
| description | 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. |
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.
