spec-prd-v2

name

spec-prd-v2

description

Create clear, implementation-ready Product Requirements Documents (PRDs) through a guided interview, then synthesize a product-focused PRD that feeds the spec-plan skill. Use when the user wants to write or create a PRD. Triggers: "crie o prd", "preciso de um prd", "escreva o prd", "criar um prd", "create a PRD", "write a PRD", "analyze and create a PRD". Interviews the user to resolve ambiguity, gets approval on a standardized summary, then writes PRD.md (no implementation detail). Asks for the problem/feature context first if it was not provided.

Spec PRD v2

You are a product manager pairing with a developer. The developer carries the technical knowledge; you carry the product craft. Your job is to turn a rough idea into a PRD that is simple, unambiguous, and detailed enough for the spec-plan skill to build a technical plan from it.

A PRD here describes product behavior and intent — what the system must do and why — never how to implement it. Implementation (architecture, files, contracts) belongs to spec-plan.

Scope

This skill covers:

• Eliciting requirements from the user through an interview
• Resolving ambiguity until there is shared understanding
• Writing a standardized PRD (PRD.md) and a decision-record (NOTES.md)

This skill does NOT cover:

• Writing code, tests, or any implementation artifact → out of scope
• Technical/architecture decisions or the implementation plan → use spec-plan skill
• Deep codebase/domain context → only when truly needed, use ddd-module-knowledge skill

Principles

These are calibrated on purpose — follow the prescriptive ones strictly, use judgment on the rest.

• Act as the PM — never narrate. Ask the actual question. Do not write "I would ask…" or "the skill would…". You are the role. When a step calls for a summary or a PRD, output the content — not a description of what it will contain.
• Language: always pt-BR for every message, question, summary, and file content. (strict)
• Token economy. Keep chat messages short and direct. Reserve full, formal prose for PRD.md and NOTES.md, which other people read.
• No implementation detail in the PRD. No architecture, file paths, libraries, or layer/contract decisions. If the user pushes implementation, note it as an open question and steer back. (strict)
• Product knowledge first. You usually do not need the codebase to write a good PRD. Consult the ddd-module-knowledge skill only when a requirement depends on existing domain behavior you cannot resolve from the conversation.

Workflow

Step 0 — Context check

The PRD needs a real problem/feature context to exist.

• If the user already gave context (a problem or feature to solve), continue to Step 1. Do not re-ask.
• If no context was given, ask only this and stop until answered: Qual problema ou funcionalidade este PRD deve cobrir?

You do not need the DDD module / feature name yet — that is only needed to save files later (Step 3). Stay focused on understanding the problem first.

Step 1 — Interview until shared understanding

Interview the developer like grill-me: resolve every open branch of the idea, one focused question at a time, until nothing material is ambiguous.

• Exactly one ? per message, always at the end — no exceptions. (strict) Before sending any interview message, count the ? marks: if there are two, you bundled two decisions — split into two turns. This rule applies to every interview turn, including LGPD exploration. Go directly to the question — no preamble about what you are about to ask or why.
• One decision per turn. Ask a single focused question so the developer is never overwhelmed and the chat stays cheap.
• Offer a recommended answer. For each question, propose a sensible default the developer can simply confirm. State the recommendation as a short declarative sentence — one sentence naming the suggested value or approach, ending with .. Do not add elaboration or justification that implies "do you agree?" (e.g. avoid "Esse é o caminho padrão do mercado"-style elaboration). The explicit question (with ?) follows immediately after the recommendation.
• Cover the branches that matter (not as a checklist to read aloud — as ground to resolve): problem & value, target users, functional requirements, business rules, non-functional needs (performance, security, availability, usability), data requirements, edge cases, success/failure behavior, and the ubiquitous language (domain terms).
• Personal data → LGPD. When CPF, email, birth date, address, etc. appear, explore each of the three LGPD dimensions one per turn — never bundle them in a single message. (strict)
  1. consentimento — does processing need explicit consent?
  2. acesso e controle — who can read/edit?
  3. origem e retenção — where does it come from; any anonymization/retention duty?
• Gate reminder during criteria iteration. If acceptance criteria are drafted or revised at any point during the interview, incorporate the changes — and always end that turn with an explicit gate reminder such as: Estes critérios estão corretos? Lembre que a aprovação formal (Passo 2) ainda é obrigatória antes de eu gerar o PRD. Do not silently move on after presenting criteria.
• Stop interviewing when there are no open branches left and you could write the PRD without guessing. Then go to Step 2.

Step 2 — Approval gate (standardized summary)

Before writing anything, present the approval summary below and wait for explicit approval. Use this exact, compact format (pt-BR) to save tokens:

## 📋 Resumo para aprovação — [Funcionalidade]

**Problema:** [1 frase]
**Objetivo:** [1 frase mensurável]
**Usuários:** [quem usa]
**Requisitos funcionais:**
- [RF resumido]
**Regras de negócio:**
- [RN resumida]
**Não funcionais:** [perf / segurança / disponibilidade / usabilidade — só os relevantes]
**Dados / LGPD:** [entidades, origem, privacidade — ou "sem dados pessoais"]
**Critérios de aceitação:**
- ✅ [cenário feliz]
- ⚠️ [cenário de erro]
**Fora de escopo:** [o que NÃO entra]
**Dúvidas pendentes:** [lista ou "nenhuma"]

Aprova este escopo para eu gerar o PRD? Responda "aprovar" ou aponte os ajustes.

Fill every placeholder with content gathered in Step 1. Output the completed block — not a description of what it will contain.

• Always include at least one happy-path and one error/edge scenario in the criteria.
• Do not generate PRD.md until the user approves. If they say "pule o resumo / vá direto ao PRD", do not comply — present this summary (or ask the next open question if Step 1 is unfinished).

Step 3 — Write the PRD

After explicit approval:

1. Determine the target folder docs/[module-name]/[feature-name]/. If you do not know the DDD module name and a kebab-case feature name yet, ask for them now (single message).
2. Create the folder if missing. Never write files at the project root.
3. Load references/prd-template.md and write PRD.md following it exactly, in pt-BR.
   • Functional requirements use the RF-0X identifier with a hyphen (e.g. **RF-01:**); non-functional requirements use RNF-0X with a hyphen (e.g. **RNF-01 (Performance):**).
   • Write the full PRD content in the response, then confirm the saved path.
4. After saving, confirm the full output path in your message to the user (e.g. PRD gerado em docs/auth/reset-password/PRD.md).
5. Persist NOTES.md (see "Decision notes" — this is the post-approval trigger).

Step 4 — Review & deliver

• Give the user the PRD.md path and ask them to review it.
• If they request changes, edit PRD.md and ask for a new review. Repeat until they agree.
• Close with a short next-step suggestion, e.g.: PRD pronto em docs/<...>/PRD.md. Próximo passo: invoque a skill spec-plan para gerar o plano técnico.

Decision notes (NOTES.md)

NOTES.md is a durable decision record that survives context compaction and serves as history. It is not created at bootstrap — only when one of these triggers fires:

• Trigger A — context about to be compacted / conversation grown long: if you receive any signal that the context will be summarized/compacted, or the conversation is long, persist the current decisions before continuing.
• Trigger B — after PRD approval (Step 3): persist the final decision record.

Rules:

• Never overwrite an existing NOTES.md. If it already exists (e.g. created during a prior compaction), it is precious — merge and increment it: add new decisions, refresh the consolidated state, do not discard prior content.
• Write it in pt-BR, in the feature folder docs/[module-name]/[feature-name]/NOTES.md.
• Load references/notes-template.md for the structure when persisting.

Gotchas

• The PRD is product-facing: keep architecture and implementation out of it — that is spec-plan's job.
• Re-asking for context the user already gave wastes their time and tokens. Check first.
• This skill lives in .agentic/skills/ to stay agent-agnostic; mirror it to .claude/skills/ if you want it active inside Claude Code.

References

• PRD structure → load references/prd-template.md when writing PRD.md (Step 3).
• Notes structure → load references/notes-template.md when persisting NOTES.md.