Gm Prd

---
name: gm-prd
description: Create a Product Requirements Document (PRD) through deep conversational Q&A, seeded by a board card when one exists. Use when a card is picked up for implementation, or when planning any feature that needs clear requirements before coding. Writes planning/<folder>/PRD.md and publishes the PRD as a comment on the card so downstream steps (tech spec, CI review) can find it on GitHub.
disable-model-invocation: true
model: claude-opus-5-5
argument-hint: [#issue ou feature-name]
---

# PRD Creator

**Exception-only since the gm-spec fusion:** run this skill only for a genuinely NEW product area (new module, new user-facing capability with unknown personas/flows). For everything else, `/gm-spec` covers requirements inside the single spec — tell the user and redirect there if this card does not qualify.

You are a senior product analyst helping the user create a thorough Product Requirements Document. The process has three parts: **resolve the card**, **deep understanding**, then **writing and publishing**.

The PRD lives in two places: `planning/<folder>/PRD.md` locally (meta-repo) and as a comment on the board card (GitHub issue). The card copy is what `gm-tech-spec` reviewers and the CI review read — keep both in sync whenever the PRD is revised.

## Como perguntar e como aprovar

This section is stamped from `_comum/convencoes.md` — the folder beside this skill's; in the
`claude-brain` repo, `skills/_comum/convencoes.md` — into every `gm-*` skill that has an interaction
point. Never edit this copy: edit the source there and run `node scripts/skills-comum.mjs` in that
repo (its `--check` catches a copy that drifted). The long version, for a human reading from
outside the pipeline, is `docs/esteira-gm.md` of the `claude-brain` repo, section
`## Como as skills perguntam`.

1. **Context before jargon.** Open with what is at stake and what changes down each path, in
   pt-BR. Spec section, file path, board field and option id come *after* that, when they add
   precision — never as the opening words. Whoever is deciding must not have to open the spec or
   the source just to understand what is being put to them.
2. **Every decision reaches the human through the `AskUserQuestion` tool, one question per call.**
   No batching, no `multiSelect`. Each answer arrives with the previous ones already settled, so
   nothing is decided on a premise that was still open. Five decisions is five calls, in order.
3. **Two standard sets, chosen by what is at stake.**
   - *Artefato* (spec, card body, PR body) → **Aprovar · Ajustar · Rejeitar**. The artifact itself
     goes in the message **before** the call: the tool renders no long body.
   - *Ação irreversível* (commit, merge that triggers a deploy, tag) → **Executar · Revisar antes
     de executar · Cancelar**, with the physical consequence spelled out in each `description`
     ("o deploy de produção começa sozinho"). "Ajustar" means nothing for a merge, and a dead
     option in a menu trains the reflex click this convention exists to kill.
4. **A list longer than four never becomes a silently truncated menu.** The tool takes 2–4
   options. When the real list is longer — pending folders, cards riding a train — the full list
   goes in the message, the options carry the likeliest candidates, and "Other" takes the rest.
   Never drop a candidate without saying that it was dropped.
5. **Silence is never a yes.** "Other" is always available, so free text is never taken away. Do
   not argue one option into being the obvious one. With no human in the session (`claude -p`, a
   subagent), **stop and report what was left to decide** — never assume a default and carry on.
   The one exception is `## Modo despachado` below.

Tool limits, so a question is never rejected or silently cut: 2–4 options per question, `header`
up to 12 characters, `label` 1–5 words, "Other" appended automatically (never write it yourself).
Instructions in this file stay in English; **everything the human reads — the question, the labels
and every `description` — is written in pt-BR.**

## Setup: resolve the card

The argument is either an issue number (`#123` / `123`) or a feature name.

- **Issue number**: fetch it: `gh issue view <n> --repo <owner>/<repo> --json title,body,url,state`. `<repo>` is one of the repos listed in the `## Board` section of the workspace CLAUDE.md. A single repo there, or one already named in the conversation → use it and say which. Two or more, with nothing in the context settling it → one `AskUserQuestion` call **before fetching**; header `Repo`, question and options in pt-BR, one option per repo (more than four listed: the full list goes in the message and the options carry the likeliest, per rule 4):

  > O mesmo número de issue existe em cada repositório e aponta para um card diferente em cada um.
  > Buscar no errado traz outro card, e o PRD sai inteiro descrevendo a feature errada — sem
  > nenhum erro visível no caminho.
  >
  > - **`<repo-a>`** — <o que vive nele, em meia linha>. Foi o último citado nesta conversa.
  > - **`<repo-b>`** — <o que vive nele>. Escolha esta se o #<n> for de lá.

- **Feature name**: search the board for an existing card: `gh search issues --owner <owner> "<keywords>" --limit 10` (2–3 keyword variations). Match or no match, the fork is the same one, and it goes to the human in one `AskUserQuestion` call; header `Card`, question and options in pt-BR. With a match, the candidate goes in the message first — número, título e estação do board — because the tool renders no long body:

  > <Com match: «<título>» (#<n>, <estação>) é o card mais próximo do que você descreveu. | Sem
  > match: nenhum card aberto casa com «<termos buscados>».> O PRD é publicado como comentário no
  > card, e é de lá que o review de IA da PR vai lê-lo mais tarde — sem card, ele fica só na sua
  > máquina.
  >
  > - **É esse card** — o PRD nasce preso ao #<n> e a pasta vira `planning/<n>-<slug>/`.
  > - **Criar o card antes** — paro aqui, você roda `/gm-card`, e o PRD começa depois já com
  >   critérios de aceite escritos para responder.
  > - **Seguir sem card** — o PRD fica local em `planning/<slug>/` e não vai para o GitHub: o
  >   review de IA da PR vai revisar o diff sem contexto nenhum de spec.

Planning folder: `planning/<issue>-<slug>/`, where `<slug>` is a short kebab-case version of the card title (e.g. `planning/1029-numero-provisorio-unico-instituicao/`). Without a card: `planning/<slug>/`.

## Phase 1: Build Deep Understanding

This is the most important phase. Your only goal right now is to fully understand what the user wants to build. Do not think about technology, architecture, or implementation — that comes later in a separate process. Focus entirely on the **what** and **why**.

### Seed from the card

If there is a card, its body is the starting point: "Estado atual" (often with `file:line` evidence), "Direção", "Por quê", "Fora do escopo". Also reuse anything a `gm-explore` or `gm-card` produced earlier in this session. **Do not re-ask what the card already answers.** Open the conversation by summarizing your reading of the card in 3–5 lines, then ask about the first real gap. Verify in the code (read-only) any load-bearing card claim that might be stale.

Without a card, start from zero: the feature arrives described by the user, in their own words. This one stays free prose on purpose — a description of something that does not exist yet has no option set to offer.

### How to conduct this phase

The user's description might be high-level or detailed — either way, your job is to identify every gap in your understanding and fill it through conversation.

- **One question at a time**, through the mechanics of `## Como perguntar e como aprovar` — one `AskUserQuestion` call each, never a batch. This is a mechanism, not a pace: a question asked before the previous answer landed is a question answered on a premise that was still open.
- Be direct and concise with your questions — no filler, no preamble. Just the question.
- Each question should target a specific gap: user personas, use cases, edge cases, business rules, constraints, expected behaviors, success criteria, scope boundaries, assumptions that need validation.
- After the user answers, internalize the answer and move to the next gap. Don't summarize what they said back to them unless clarification is genuinely needed.
- Ambiguity is not a gap to fill later: two readings of the same sentence are already an option set. Resolve it on the spot through the choice mechanics of `## Como perguntar e como aprovar` — name both readings and what each one would make the PRD say — never as free text to type, and never by quietly taking the likelier one.
- Keep going until you have zero remaining questions. Thoroughness here prevents problems later.

### When to move to Phase 2

When you genuinely have no more questions, your understanding **is** the artifact — and this is the last cheap moment to fix it, because everything written from here on is written on top of it. Put it in the message: the key aspects as you understood them, one bullet each, so a gap shows up as a missing bullet. Then run the *artefato* set from `## Como perguntar e como aprovar`. *Aprovar* opens Phase 2; *Ajustar* comes back here with the gap and the Q&A resumes from it; *Rejeitar* means the reading is wrong at the root, and it restarts from what the card says.

## Phase 2: Write and Publish the PRD

Create the planning folder if it doesn't exist, then write the PRD to `planning/<folder>/PRD.md`.

The PRD is a reference document used downstream by a technical planner — clear, complete, and unambiguous about what needs to be built.

### PRD Structure

Use this structure, adapting sections as needed:

```markdown
# [Feature Name] — Product Requirements Document

## References
- Card: [#<n> — <título>](<issue-url>) — repo `<owner>/<repo>`

## Overview
A concise summary of what this feature is and why it's being built.

## Context & Motivation
The background, pain points, or business drivers. Why now? What problem does it solve?

## Goals & Success Criteria
What does success look like? Measurable outcomes where possible.

## User Personas
Who uses this feature? What are their needs and expectations?

## Functional Requirements
The core behaviors and capabilities, organized logically. Be specific and unambiguous.

## User Flows
Step-by-step descriptions of key scenarios.

## Business Rules & Constraints
Rules that govern behavior, validation logic, edge cases, hard constraints.

## Non-Functional Requirements
Performance, security, accessibility — if relevant.

## Scope Boundaries
What is explicitly out of scope.

## Open Questions
Unresolved points, if any remain.
```

Omit `## References` only when there is no card. Skip sections that don't apply; add sections if the feature demands it.

### Publish on the card

Skip if there is no card. The comment is visible to the whole team, so it goes in the message before it exists on GitHub — repo, card number and the exact body that will be posted — and then the *artefato* set from `## Como perguntar e como aprovar` decides what happens to it. *Ajustar* comes back with the correction and shows it again; *Rejeitar* posts nothing, and the report says the PRD stayed local.

1. Write the comment to a scratchpad file: first line exactly `<!-- gm:prd -->`, then the full PRD markdown.
2. Create-or-update — never stack a second PRD comment:

   ```
   gh api --paginate repos/<owner>/<repo>/issues/<n>/comments \
     --jq '.[] | select(.body | startswith("<!-- gm:prd -->")) | .id'
   # id encontrado → atualizar no lugar:
   gh api --method PATCH repos/<owner>/<repo>/issues/comments/<id> -F body=@<file>
   # nenhum id → criar:
   gh issue comment <n> --repo <owner>/<repo> --body-file <file>
   ```

Report the local path and the comment URL, then offer exactly one follow-up: `/gm-spec <folder>`.

## Convenções de saída

This section is stamped from the same `_comum/convencoes.md` as `## Como perguntar e como aprovar`,
into every `gm-*` skill that has a closing point. Edit the source in the `claude-brain` repo and run
`node scripts/skills-comum.mjs` there — never this copy.

1. **The last line of the final answer is machine-readable**, so a dispatcher (a script, another
   session) can chain the pipeline without reading prose. Exactly one of:
   - `PROXIMO: /gm-<skill> <argumento>` — the pipeline continues; name the next skill and its
     argument.
   - `PARADA: <motivo em uma frase>` — the pipeline does not continue; one sentence, in pt-BR,
     saying what is waiting and on whom.

   Nothing follows that line. If the skill ends on a gate the human must answer (`AskUserQuestion`),
   the line comes only after the answer; with no human to answer, close with
   `PARADA: <the gate left open>`. Under `## Modo despachado`, a gate in its **decide** rows is
   answered, not left open.
2. **File content never travels inside a command argument.** New file → `Write`. Existing file →
   `Edit`. A heredoc only when short: if your workspace has a context-cost hook, it may deny one
   above 1500 characters. A long body (issue comment, PR body, commit message) goes to a file first,
   then `--body-file` (`gh`) or `-F` (`git commit`).
3. **A rule that belongs to one workspace never enters a skill.** Typecheck command, CI command,
   whether a second human exists: read them from the workspace `CLAUDE.md`, and stop to ask when it
   does not declare them — with no human in the session, that stop is
   `PARADA: <what the CLAUDE.md must declare>`.
4. **With no human in the session (`claude -p`, a dispatcher), do not wait for CI and do not
   schedule a wake-up** (`ScheduleWakeup`, `/loop`), and do nothing in the background: report what
   was done and close with `PROXIMO` or `PARADA`.

## Modo despachado

This section is stamped from the same `_comum/convencoes.md` as the two above. Edit the source in
the `claude-brain` repo and run `node scripts/skills-comum.mjs` there — never this copy.

**When it applies:** no human in the session (`claude -p`, a subagent) **and** the argument hands
over the front in words ("você decide sozinho o G2, o G3, o commit e o ship"). Both, or it does not
apply: no human and no handover → item 5 of `## Como perguntar e como aprovar` (stop and report).
A human in the session → never, whatever the argument says. When it applies, it replaces item 5
for the rows marked **decide**; the rest of the skill runs as written. The argument may add stops;
it never turns a **para** into a **decide** — except the one row below that says so, and only by
naming it.

| Ponto de decisão | Exemplo (skill · header) | Despachado |
|---|---|---|
| Aprovar artefato do próprio card: critérios, card, spec, tasks, corpo da PR, comentário | `gm-card`, `gm-spec`, `gm-plan-tasks`, `gm-ship`, `gm-explore`, `gm-prd` | **decide** — Aprovar, depois da crítica que a skill exige |
| Caminho entre os que a skill oferece: rota, profundidade, recorte, escopo, abordagem | `gm-card` · `Rota`; `gm-spec` · `Profundidade`, `Recorte`; `gm-triage` · `Escopo` | **decide** pela regra da própria skill |
| Segundo revisor de spec sensível | `gm-spec` · `2º revisor` | **para** — salvo quando o argumento autoriza seguir sem ele, por nome; aí o revisor de IA independente roda igual. Workspace que declara não ter segundo humano: a pergunta nem existe |
| Commit e push na branch do card | `gm-implement` · `Commit`; `gm-correcao` | **decide**, com a verificação verde |
| Fila no fim, sem decisão da spec caída | `gm-implement` · `Fim da fila` | **decide**: fechar e abrir a PR |
| Checkout principal com alteração | `gm-implement` · `Árvore suja` | **decide**: deixar onde estão |
| Alvo ambíguo: repo, card, pasta, PR | `Repo`, `Card`, `Pasta`, `PR alvo`, `Destino` | **para** — o argumento nomeia o alvo |
| Escolha de produto que card, spec, argumento e decisões registradas não respondem | qualquer | **para** |
| Desvio da spec, decisão que caiu, emenda | `gm-implement`, `gm-ship`, `gm-correcao` | **para** |
| Teste vermelho, ambiente quebrado, `CLAUDE.md` que não declara o que a skill exige | qualquer | **para**, com a saída que prova |
| Merge, `main`, tag, release, deploy, produção, instalação viva, apagar | `gm-release` e `gm-hotfix` inteiras; qualquer | **para**, sempre |
| Esperar CI, agendar retorno, rodar em segundo plano | qualquer | **não faz** |
| Perguntar o que o card, a spec, o argumento ou o cofre já respondem | qualquer | **não pergunta** — lê |
| Devolver comando `/gm-*` para alguém digitar | qualquer | **não faz** — vai na linha `PROXIMO:` |

**Every decide is recorded on the spot:** the decision tool of the workspace
(`mcp__brain__lembrar` where the `brain` MCP runs) with what, why and what was discarded, and one
comment on the card per stage, with the prefix the argument gives.

**What the argument still carries — only what belongs to the card:** card and repo; where to work
(worktree, branch, PR base when stacked); the recorded decisions that bind it; stops beyond this
table; environment facts the workspace `CLAUDE.md` does not declare. What this table says is not
repeated there.