Gm Release

---
name: gm-release
description: Cut the release train from the team board (the team board declared in the workspace CLAUDE.md) — read the validated queue (🚂 Release, plus cards closed while in 🧪 Validação em Dev), reconcile it against what is actually merged in dev, classify the train as trivial or sensitive (migrations / data treatment), open the dev→main PR, tag with calver, publish dual release notes, run the BLOCKING post-deploy verification for sensitive cards, move the cards to ✅ Produção and produce the list of requesters to notify. Use on the weekly train day, or whenever promoting dev to production.
disable-model-invocation: true
model: claude-opus-5-5
argument-hint: [vazio para o trem de hoje | dry-run]
---

# Release — o trem

Mission: turn release from a rare, scary event into a **Tuesday routine** — named, verified and communicated. A merge without a name is the reason nobody can answer "o que subiu quando"; a tag and a changelog answer it for free, forever.

## 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.**

## Hard rules

- **The queue is what was validated; the diff is what actually ships.** Reconcile the two before anything else. Work merged into `dev` that never passed 🧪 Validação em Dev rides the same train — surface it, never let it board silently.
- **A sensitive train does not promote on hope.** Migration or data treatment → it needs the release
  environment (a copy of prod). Whether one exists, and how to run the payload against it, is read
  from the workspace `CLAUDE.md` (`## Convenções da esteira`, item *Ambiente de ensaio*); none
  declared → no pretending: stop and put the three ways out to the human as a choice — the question
  is written out in `## Phase 3 — Ensaio`, and that is the only place this decision is taken — then
  **record the chosen one in the release notes**.
- **Verification is blocking** for every card whose spec has a `## Verificação pós-deploy`. Red → the release is not done; it is an incident.
- Merging into `main` deploys production immediately (`deploy.yml`, `yarn deploy -p`) and applies Prisma migrations on container boot. There is no manual step between merge and production.
- Nothing is merged, tagged or published unless the human chose it, and every one of those choices arrives by the mechanics of `## Como perguntar e como aprovar`: the *ação irreversível* set for the merge and the tag, the *artefato* set for the PR body and the release notes, hand-written options for everything else. Never as free text for the human to type.
- `dry-run` argument → run every read-only step, print the whole plan (payload, notes, notification list), change nothing.
- Answer in pt-BR.

## Board reference — vem do workspace, nunca deste arquivo

As coordenadas do board (**project**, **owner**, **project-id**, field-ids, option-ids) e a lista de
**repos** estao na secao `## Board` do `CLAUDE.md` do workspace atual, ja carregado no seu contexto.
Use aquelas — nunca IDs escritos aqui ou lembrados de outra sessao.

**Se o CLAUDE.md do workspace nao tiver a secao `## Board`, pare e peca ao usuario.** Nao descubra
board sozinho e nao assuma o da Notoria: escrever card no board errado e pior que nao escrever.

Placeholders usados adiante: `<owner>`, `<project>`, `<project-id>`, `<repo>`, `<field:Nome>` (o
field-id do campo) e `<opt:Campo=Valor>` (o option-id da opcao).

## Phase 1 — Read the queue and reconcile with reality

1. The train's queue, plus the column right before it (that is where caronas usually have a name):

   ```
   gh project item-list <project> --owner <owner> --limit 200 --format json \
     --jq '.items[] | select(.status=="🚂 Release" or .status=="🧪 Validação em Dev")
           | {n:.content.number, repo:.content.repository, status, rota, titulo:.title}'
   ```

   (`item-list` keys are the lowercased field titles: `status`, `rota`, `tipo`, `severidade`, `classe`, `módulo`, plus `id` and `content`. A field that was never set is simply absent.)

2. Actual payload (inside the module repo):

   ```
   git fetch origin
   git log --oneline origin/main..origin/dev | wc -l
   gh pr list --repo <owner>/<repo> --base dev --state merged --limit 100 \
     --json number,title,mergedAt,body --jq '.[] | select(.mergedAt > "<data-da-última-tag-ou-corte>")'
   ```

3. **Reconcile and report the three sets, explicitly:**
   - cards **validated** (in 🚂 Release, or closed while in 🧪 Validação em Dev — `/gm-ship` and
     `/gm-correcao` close a validated card without moving it) **and** in the diff → the intended train;
   - validated cards **without** code in the diff → not ready, take them off the train;
   - code in the diff **without** a validated card → *carona*: unvalidated work riding along. The
     **full** list goes in the message first — card by card, or commit by commit when there is no
     card, saying what each one touches — and then the decision is taken **one carona at a time**:
     one `AskUserQuestion` call per item, header `Carona <k>/<N>` (`Carona 2/5` — the tool caps
     `header` at 12 characters, so keep the counter numeric), question and options in pt-BR:

     > Isto entrou no payload sem ninguém ter conferido em ambiente nenhum que funciona: não passou
     > por 🧪 Validação em Dev e mesmo assim já está na `dev`. É `<PR/commit>` — <o que é> — e toca
     > <o quê>.
     >
     > - **Aceitar a carona** — sobe junto no trem de hoje e sai anunciada nas release notes, com o
     >   registro de que subiu sem validação. Se quebrar em produção, quebra sem ninguém ter conferido.
     > - **Segurar o trem** — nada sobe hoje, nem os cards validados: eles esperam esta carona ser
     >   validada ou revertida da `dev`.
     > - **Reverter da `dev`** — a carona sai do payload (`git revert` na `dev`) e o resto do trem
     >   parte hoje. O trabalho revertido volta para quem o escreveu; não se perde.

     This is what rule 4 of `## Como perguntar e como aprovar` exists for: N caronas never get cut
     down to fit one menu of four. The list stays whole in the message, the loop gets longer instead
     of wider, and `multiSelect` is out by rule 2 — a batch would settle the fifth carona while
     nobody had yet looked at the first.

   With production far behind `dev`, the third set is the normal case, not the exception. Never omit it.

## Phase 2 — Classify the train

**Sensitive** if the payload contains any of:

```
git diff --name-only origin/main...origin/dev -- 'prisma/migrations/**' | sort -u
git diff --name-only origin/main...origin/dev | grep -iE 'scripts/|seed|backfill|tratamento' | sort -u
git diff --stat origin/main...origin/dev -- 'prisma/schema.prisma'
```

…or any card in the train whose spec declares a migration, a data treatment, or a `## Verificação pós-deploy` that is not `N/A`.

**Trivial** = none of the above. Trivial promotes straight through.

For a sensitive train, list every migration by name and say what each does — a train carrying accumulated migrations against a 10 GB table is the difference between a Tuesday and an outage.

## Phase 3 — Ensaio (sensitive trains only)

A **release environment** is a copy of production where the accumulated migrations and the data treatment run before they count, with acceptance queries comparing faturamento before and after; only what passes gets promoted. The workspace `CLAUDE.md` says whether one exists and how to run the payload against it (`## Convenções da esteira`, item *Ambiente de ensaio*). **Declared:** run it as declared, put the result under `### Ensaio` in the release notes, and a red result holds the train. **Not declared, or declared `não`:** do not pretend it happened. Stop: name every migration and data treatment in the payload in the message — what each one does, against which table, how much data — and then one `AskUserQuestion` call, header `Ensaio` (the tool caps `header` at 12 characters), question and options in pt-BR:

> Este trem carrega <as migrations/tratamentos, pelo nome>, e este workspace não declara — ou declara
> que não há — um ambiente de ensaio, a cópia de produção onde isto rodaria antes de valer. Não há
> como provar hoje como a migration se comporta contra o dado real; o que você escolhe aqui é o que
> fazer sem essa prova.
>
> - **Segurar o trem** — nada sobe; os cards ficam em 🚂 Release até um ambiente de ensaio ser
>   declarado no `CLAUDE.md` do workspace. É o caminho correto quando o trem toca faturamento ou
>   reescreve dado.
> - **Partir o trem** — a parte trivial sobe hoje por uma branch `release/<data>` (cherry-pick a
>   partir de `origin/main`; o `pr-branch-check` aceita `release/*` em `main`) e os cards sensíveis
>   ficam parados. Sobe menos, e o que sobe não carrega migration.
> - **Promover assumindo o risco** — a migration roda direto em produção, sobre dado que ninguém
>   testou antes. Exige rollback ensaiado de antemão, e fica registrado por escrito que subiu assim.

*Promover assumindo o risco* → the sentence goes verbatim into the release notes and into every
affected card: `promovido sem ensaio em ambiente release — decisão registrada na PR do trem #<pr> em
<AAAA-MM-DD>`. It names the PR and the date, not a person: a choice hands back a label and no
identity, and the train PR carries the identity better anyway — whoever approved and merged it is
recorded by GitHub, checkable months later, which a name typed into release notes never is.

Never argue one option into being the obvious one. When the train touches data or faturamento, say
in the message that holding or splitting is what this skill recommends — as information, before the
call, never as pressure inside it.

## Phase 4 — Open the train PR

```
gh pr create --repo <owner>/<repo> --base main --head dev --title "release v<AAAA.MM.DD>" --body-file <file>
```

```markdown
## Trem v<AAAA.MM.DD>

### Cards validados
- #<n> — <título> (<módulo>)

### Carona (sem card validado)
- <PR/commit> — <o que é> — decisão: <segurar | reverter da dev | aceito, sem validação>

### Migrations
- <nome-da-migration> — <o que faz> — <destrutiva? janela de risco?>
- (ou "nenhuma")

### Ensaio
[resultado no ambiente release · ou "não ensaiado — <opção escolhida na fase 3>"]

### Verificação pós-deploy (bloqueante)
- #<n> — <query/checagem tirada da spec do card>
```

The body is the artifact, and it is the only place where what ships today is written down: it goes **whole** in the message — the tool renders no long body — and the decision comes back through the *artefato* set from `## Como perguntar e como aprovar`. *Aprovar* → open the PR with that body, exactly as shown. *Ajustar* → fix what the human named (a carona missing from the list, a migration described as harmless when it is not) and present it again. *Rejeitar* → no PR, and the train does not leave the station today. Check CI green (`gh pr checks`) before proposing the merge — and remember that a red check does not physically block the merge in these repos, so a green CI is **your** responsibility to confirm. With no human in the session, CI pending or red is never waited out and never merged over: the PR stays open and the session closes with `PARADA: CI pendente na PR do trem`.

## Phase 5 — Merge, deploy, verify

1. The merge is this skill's point of no return, so it goes to the human by the *ação irreversível* set from `## Como perguntar e como aprovar`: header `Merge` (12-character cap), options in pt-BR, and the physical consequence written into each `description` — never a bare verb.

   > - **Mergear e subir** — o faturamento passa a rodar este código em minutos: o merge em `main`
   >   dispara o `deploy.yml` sozinho e as migrations rodam no boot do contêiner. **Não existe passo
   >   manual entre o merge e produção**, e desfazer é outro deploy, não um botão.
   > - **Revisar antes de mergear** — nada é mergeado agora; volto com o que você apontar (o diff de
   >   uma migration, o payload, o resultado do CI) e pergunto de novo.
   > - **Cancelar** — nada sobe. A PR do trem fica aberta, os cards seguem em 🚂 Release, e o
   >   trem parte outro dia.

   Only *Mergear e subir* continues to step 2.
2. Follow it: `gh run list --repo <owner>/<repo> --branch main --limit 3` and the deploy job's logs.
3. **Smoke, always:** the API answers, the web loads, migrations applied (compare the latest `prisma/migrations` folder against `_prisma_migrations` in the prod database).
4. **Blocking verification, for every sensitive card:** run the `## Verificação pós-deploy` query from its spec against production and paste the output as a comment on the card.
   - Red → **stop the closing ritual**: no tag, no notes, no card moved to ✅ Produção. The code is
     already in production by now, so the question is not whether to act but which way out — what the
     query returned goes in the message, against what the spec expected, and then one
     `AskUserQuestion` call, header `Verificação`, question and options in pt-BR:

     > A verificação pós-deploy do card #<n> voltou vermelha: <o que a query devolveu> contra <o que
     > a spec esperava>. O código já está em produção e <o dado está sendo afetado agora / o estrago
     > está parado>.
     >
     > - **Reverter o merge** — produção volta ao código anterior em minutos (`git revert` do merge
     >   commit + redeploy). Migration já aplicada **não** volta com ele: se ela reescreveu dado,
     >   reverter o código deixa o dado como está.
     > - **Consertar para frente** — o código fica no ar e a correção sobe por cima, por
     >   `/gm-hotfix` (branch `release/hotfix-*` direto em `main`). Mais lento que reverter, e é o
     >   único caminho quando o estrago está no dado.
     > - **Medir antes de escolher** — nada é feito ainda; sigo investigando e volto com o
     >   diagnóstico. Só cabe se o dado não está sendo corrompido enquanto você espera.

     A red verification is an incident, never a card silently reopened: whatever is chosen goes as a
     comment on the card, with the query output, before this session ends.

## Phase 6 — Tag and notes

Dual notes, both generated from the cards — one document, two audiences:

```markdown
## O que muda para você
- <em linguagem de hospital: o que o faturista vai notar na tela, sem jargão técnico>

## Técnico
- #<n> — <título> — <PR>
- Migrations: <nomes ou "nenhuma">
- Verificação: <resultado>
- Ensaio: <resultado ou a decisão registrada>
```

1. **The notes are the artifact, and the only one on this rail that reaches outside the team** —
   the "o que muda para você" half is what the hospital reads. They go **whole** in the message,
   both halves as they will be published, and the decision comes back through the *artefato* set
   from `## Como perguntar e como aprovar`. *Ajustar* → rewrite what the human named (a card
   described in jargon, a migration called harmless, a carona missing from the list) and show them
   again. *Rejeitar* → nothing is tagged and nothing is published; the merge already happened, so
   say plainly that production is running code that has no release name yet.
2. Then the tag and the publication — public, and the last irreversible step of the train — go to
   the human by the *ação irreversível* set from `## Como perguntar e como aprovar`: header `Tag`,
   options in pt-BR, and the physical consequence written into each `description`.

   > - **Publicar a release** — a tag `v<AAAA.MM.DD>` é empurrada para o GitHub e a release fica
   >   pública com estas notas. É ela que responde "o que subiu quando" daqui em diante, e quem
   >   pediu cada card vai ser avisado citando este nome. Apagar depois exige mexer em tag pública.
   > - **Revisar antes de publicar** — nada é empurrado; volto com o que você apontar (a lista de
   >   cards, o texto de hospital, o calver do dia) e pergunto de novo.
   > - **Cancelar** — nada é publicado. O código já está em produção sem nome: os cards ficam em
   >   🚂 Release, ninguém é avisado, e a próxima release herda este payload sem registro de que
   >   ele subiu hoje.

   Only *Publicar a release* runs the commands below.

```
git checkout main && git pull
git tag -l 'v*' | tail -5                      # tag do dia já existe? sufixe .1, .2
git tag -a v<AAAA.MM.DD> -m "release v<AAAA.MM.DD>"
git push origin v<AAAA.MM.DD>
gh release create v<AAAA.MM.DD> --repo <owner>/<repo> --title "v<AAAA.MM.DD>" --notes-file <file>
```

Use calver (`v<AAAA.MM.DD>`) from the real date — read it with `date +%Y.%m.%d`, never assume.

## Phase 7 — Close the board

For each card in the train:

```
gh project item-edit --project-id <project-id> --id <item-id> \
  --field-id <field:Status> --single-select-option-id <opt:Status=Producao>   # Status=✅ Produção
gh project item-edit --project-id <project-id> --id <item-id> \
  --field-id <field:Release> --text "v<AAAA.MM.DD>"
gh issue close <n> --repo <owner>/<repo> --reason completed \
  --comment "Subiu em produção na v<AAAA.MM.DD> — <link da release>. Verificação: <resultado>."
```

Cards held back stay in 🚂 Release with a comment saying why and what they are waiting for. A card parked without a stated reason is exactly the metadata rot that made 39 cards unreadable.

## Phase 8 — Notify the requesters

Read `## Origem` from each shipped card and produce the list — person, channel, and the sentence to send:

```
<nome> (<canal>) — "seu chamado #<n> (<título curto>) saiu na v<AAAA.MM.DD>"
```

Hand the list to the user; sending is theirs. This is the loop that makes triage's mandatory origin field worth its cost — and the last thing between "we shipped it" and the requester knowing.

## Report

Tag, release URL, PR, verification output, cards closed, cards held, notification list. Offer exactly one follow-up: "quer registrar o que ficou de fora como carga do próximo trem?"

## 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.