teamcraft:capture-requirements

---
name: teamcraft:capture-requirements
description: Create or evolve the product requirements document (PRD). Handles new PRDs, major overhauls, adding new feature sets to existing PRDs, targeted section updates, and structural reorganization between single-file and per-feature structures. Identifies constraints that Claude would get wrong without always-loaded guidance and writes developer-approved promotions. Can decompose requirements into work items. Use when the user says 'write a PRD', 'update the PRD', 'capture requirements', 'add requirements for this new feature', 'revise the requirements', or 'rewrite the PRD for the new architecture'.
argument-hint: "[brief description of what's being captured or updated, or empty to be interviewed]"
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Bash
  - AskUserQuestion
---

## Goal

Own the full lifecycle of product requirements for this project. The authoritative document lives in the product-requirements category (opinionated default `/docs/prd.md` for single-PRD projects, or `/docs/prds/*.md` for multi-feature projects). After capture or update, identify any requirements that introduce constraints Claude would get wrong without always-loaded guidance — compliance requirements, data-handling rules, audit requirements — and write developer-approved promotions to `CLAUDE.md` or `.claude/rules/`.

Read `references/example-prd.md` first. It shows the shape of a well-structured PRD and how gotcha-promotion works for requirements-driven constraints.

## Detect What Exists

Look for an existing PRD or PRD directory. If you find one, read it and present a brief summary before interviewing: "I see an existing PRD covering [topics]. What are we doing today?"

If the structure differs from the opinionated defaults, that's fine — the skill works with whatever structure is in place. Note it and proceed. Build-loop skills consult product requirements by category, so non-default structure still works as long as Claude can locate the documents.

If neither exists, this is a new PRD.

## Establish Intent

Ask what kind of capture this is. The flow depends heavily on the answer.

Common scenarios:
1. New PRD — starting fresh
2. Major overhaul — existing PRD; product is being significantly rearchitected or repositioned; large portions of the PRD no longer apply
3. New feature set — existing PRD is still accurate; adding requirements for new functionality
4. Targeted update — specific sections need revision (scope clarification, priority change, new constraint, updated success metric)
5. Structural reorganization — splitting a monolithic PRD into per-feature files or consolidating

Ask the developer which applies. Match the interview scope to the scenario — full interview for new PRDs, narrow for targeted updates.

## Ask About External Sources

Ask whether any external material should inform this — requirements docs, user research, stakeholder notes, mockups, competitive analysis, past PRDs from related projects. Read what the developer points you to. Present findings; let the developer decide what applies. Never auto-apply external content.

## Conduct the Capture

Frame the domain and scenario. Claude knows how to interview for product requirements — who it's for, what problem it solves, functional and non-functional requirements, what's in and out of scope, how success is measured. Match the depth to the scenario.

For new PRDs or major overhauls, be comprehensive. For targeted updates, stay narrow — don't fish for unrelated changes.

## Present for Review

Show the complete document (or the specific diff, for targeted updates) before writing.

For major overhauls and structural reorganizations, present a high-level summary first: "Removing sections X, Y. Rewriting section Z. Adding new sections A, B. Structure changing from single file to per-feature." Let the developer course-correct at a high level before reviewing every detail.

## Decompose to Work Items When It Makes Sense

After the PRD is confirmed and written:
- **New PRD or major overhaul:** ask if the developer wants to decompose into work items now. If yes, walk through requirements.
- **New feature set:** ask about decomposing the NEW requirements. Don't re-create work items for existing requirements.
- **Targeted update:** only offer if the update introduced new actionable requirements.
- **Structural reorganization:** no decomposition — nothing new to build.

When decomposing, use the `create-issue` skill for each work item — that's the single source of truth for work item creation. Each work item traces back to a specific PRD section.

## Write the Document

For a new PRD, ask the developer which structure fits — single file or per-feature. For updates to an existing PRD, use the structure already in place; don't ask.

Commit PRD changes after the developer approves.

## Identify and Promote Gotchas

After the document is confirmed, walk its contents and identify requirements that introduce constraints Claude would get wrong without always-loaded guidance. The test:

> Could Claude figure this out from the codebase, or from reading the PRD when a build-loop skill directs consultation? If yes, it stays only in the PRD. If no — Claude would default to something else from training data without always-loaded guidance — it's a promotion candidate.

Good candidates:
- Compliance requirements that translate to code-level constraints ("all user data access must be logged to the audit table, always")
- Data-handling rules ("PII fields must be encrypted at rest with per-tenant keys")
- Non-obvious default behaviors ("new users default to all notifications off, opposite of the industry norm")
- Hard scope boundaries that Claude might casually cross ("billing endpoints must never be called from the mobile client — web only")

Weak candidates:
- Feature descriptions ("users can toggle notifications") — Claude acts on these via the work item, not via always-loaded rules
- Success metrics — reference material, not request-level constraints
- General scope statements — too broad for always-loaded

Propose each candidate to the developer individually. Show the promotion text and target location. Developer approves, rejects, or edits. Write each approved promotion directly.

## Respect Domain Ownership

This skill writes product requirements and their gotcha promotions. It does not write technology decisions (`capture-technical-design`) or operating conventions (`capture-team-conventions`). If the conversation drifts, redirect.

## Constraints

- Requirements describe WHAT and WHY, not HOW. Implementation belongs in technology decisions or emerges during planning.
- The PRD is a living document — updates are first-class, not exceptions.
- Never lose information on an update. If replacing a section, confirm where the old content should go (archive, delete, or keep elsewhere).

## When You're Done

Confirm what was written and where. Summarize any work items created and any promotions applied. Ask the developer directly: "Are you satisfied with what was captured?" Wait for explicit confirmation. Then point to a reasonable next step — `/capture-technical-design` if tech decisions haven't been documented, `/plan-and-implement-issue` for a new feature ready to build, or nothing if they're done.