teamcraft:capture-requirements

What this skill does

## 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
6. Review & certify an existing PRD in place — a PRD already exists (often inherited or written outside Teamcraft) and the developer wants it verified and certified as accurate, not rewritten

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, create each work item yourself to the **work-item standard** (`../references/work-item-standard.md`) — drafted from the PRD section it traces back to, shown to the developer for review (present the set together), then written and committed. Don't send the developer off to run `create-issue` per item; decomposition does the creation inline, to the same full standard. 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.

**Certify the document.** Stamp it with the Teamcraft provenance block per `../references/doc-provenance.md` — the single `prd.md`, or **each per-feature file** under `prds/` (each is consulted independently). When you authored or rewrote content, stamp `kind: created`. On the review-&-certify-in-place path — the developer confirmed an existing/inherited PRD is accurate and you are not rewriting it — insert or refresh ONLY the stamp block (`kind: reviewed`) and leave the body untouched. Source `date` from the system clock and `plugin_version` from the plugin manifest, as the reference describes.

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 the natural next step:

- `/capture-technical-design` if technology/architecture decisions haven't been documented yet;
- `/plan-iteration` to scope the next time-boxed iteration from these requirements (it will create any remaining work items it needs, to standard);
- `/plan-and-implement-issue <id>` to build a single feature that's ready right now;
- or nothing, if they're done for the session.