defining-requirements

Defining Requirements

Step 1 of the atdd-kit v1.0 flow. Take an Issue number, walk the author through the 6 PRD sections one question at a time, and write docs/issues/<NNN>/prd.md based on templates/docs/issues/prd.md.

Scope ends at the PRD. User Story extraction (incl. persona-less Connextra form and constraint stories) is owned by extracting-user-stories (Step 2, #189). This skill does not write User Stories.

Trigger

• Explicit: /atdd-kit:defining-requirements <issue-number>
• Keyword-detected (confirm before invoking): When user messages mention PRD authoring intent (e.g. "PRD", "要件定義", "Issue NNN を整理して"), ask Run defining-requirements skill on <issue>? Y/n before starting. Auto-invocation without confirmation is forbidden by the v1.0 Step B progression rule (#179).

Input

• Issue number (command-line argument or recognized in a user message)
• Issue body / title / labels read via gh issue view <NNN> --json title,body,labels

No other inputs. No Context Block. No resume of existing docs/issues/<NNN>/prd.md.

Output

Artifact	Path
PRD file	docs/issues/<NNN>/prd.md (copied from templates/docs/issues/prd.md, filled in)

No Issue comment, no skill-status fenced block. The PRD draft is committed and pushed before approval and presented as the Draft PR diff (mode-independent — the same order regardless of the caller).

Flow

1. Read the Issue (gh issue view).
2. Section 1 — Problem (one question): "Describe the concrete pain. Separate the current state and the consequence."
3. Section 2 — Why now (one question): "Why does this need to happen now? Deadlines, triggers, opportunity cost?"
4. Section 3 — Outcome (one question): "What measurable state is reached when done?"
5. Section 4 — What (one question): "List in-scope features or changes."
6. Section 5 — Non-Goals (one question): "List intentionally excluded items with one-line rationale each."
7. Section 6 — Open Questions (one question): "List unresolved decisions, or state 'none remain'."
8. Write draft. cp templates/docs/issues/prd.md docs/issues/<NNN>/prd.md, then fill in each section in place.
9. Commit / push / Draft PR. Commit the draft to the Issue's work branch (Conventional Commits), push, and if no Draft PR exists open one with gh pr create --draft.
10. Approval gate (on the PR). In the terminal present only the PR link + the points needing a human decision — never the full PRD body — then ask via AskUserQuestion (header Approve PRD?; first option (Recommended) 承認 (ok) for one-tap approval, then the context-specific section send-backs Problem を修正 / Outcome を修正 / スコープを変更; multiSelect: false):

    Approve PRD? Reply 'ok' to approve, or name a section to revise.

    Recommended: 承認 (ok) — reply 'ok' to accept, or name a section to revise
    

    The Other option is harness-auto — never list it manually; an Other free-text comment flows into the existing natural-language revision route unchanged. On non-selection-UI channels (headless / cron), the Recommended: ... — reply 'ok' line is the fallback: approve with the legacy ok text input. Revisions loop back to that section; commit and push each revision so the Draft PR diff stays current. Do not proceed without explicit ok.

Each section step is one question at a time. Do not bundle multiple sections into a single prompt.

Responsibility Boundary

Concern	Owner
Issue → PRD	defining-requirements (this skill)
PRD → User Stories (persona-less Connextra, constraint stories)	extracting-user-stories (Step 2, #189)
Plan + Acceptance Tests	writing-plan-and-tests (Step 3, #190)
ATDD double-loop implementation	running-atdd-cycle (Step 4, #191)
PRD / US / Plan / Code / AT review	reviewing-deliverables (Step 5, #192)
Parallel-session conflict, in-progress label management	skill-gate (#197)

This skill does not spawn reviewer subagents — PRD review happens at Step 5. This skill does not add or remove the in-progress label — that is skill-gate's responsibility.

Integration

• Upstream: session-start (may suggest this skill in Recommended Tasks)
• Downstream: extracting-user-stories (consumes docs/issues/<NNN>/prd.md)