Geração e Manutenção de Roadmaps

Geração de roadmaps

Um roadmap é um plano que a próxima pessoa pode pegar e executar sem depender da conversa que o produziu. Ele diz o que o projeto está tentando alcançar, em que ordem, como qualquer um saberá que cada parte está concluída e quais perguntas ainda estão em aberto. Ele fica no repositório, ao lado do código que descreve, para ser revisado e versionado como todo o resto.

Um roadmap registra decisões. Ele não as toma. Quando algo não foi decidido, o roadmap diz isso.

Regras do repositório vêm primeiro

Antes de escrever qualquer coisa, procure as convenções do próprio repositório: AGENTS.md, CLAUDE.md, CONTRIBUTING.md, um esquema de docs ou wiki e qualquer roadmap existente. Eles decidem onde os roadmaps vão, quais metadados carregam, como as issues são vinculadas e quais verificações executar. Onde entrarem em conflito com esta skill, eles vencem. Siga o formato de um roadmap existente em vez de introduzir um segundo.

Fluxo de trabalho

1. Defina a solicitação

Descubra qual destes o usuário deseja, pois cada um exige uma quantidade diferente de trabalho:

• Novo roadmap: para um projeto, uma funcionalidade, uma migração, um esforço de teste, etc.
• Atualização: adicionar ou alterar itens, reordenar fases, registrar uma decisão.
• Reconciliação: alinhar um roadmap existente com o que realmente foi entregue.
• Revisão: ler um roadmap e relatar lacunas, sem reescrevê-lo.

2. Reúna evidências antes de perguntar

Leia o que o projeto já sabe: o código e testes relevantes, issues abertas e fechadas recentemente, PRs mesclados e abertos, documentação existente e o histórico de commits da área. Anote o que existe hoje, o que já está em andamento e o que já foi tentado antes.

Tudo que você puder aprender dessa forma, não pergunte ao usuário.

3. Pergunte sobre as decisões que exigem julgamento

Um roadmap é tão bom quanto as decisões por trás dele, e a maioria delas cabe ao usuário. Pergunte em rodadas curtas, em vez de uma longa lista, e explique por que uma pergunta é importante quando a troca não for óbvia. Bons tópicos:

• Objetivo: qual resultado torna esse esforço válido, e como alguém saberá que foi atingido?
• Escopo: o que está explicitamente fora? O que não pode mudar (APIs, formatos de dados, comportamento)?
• Restrições: prazos, releases, pessoas, orçamento, plataformas.
• Prioridades: se apenas metade disso for entregue, qual metade?
• Risco: o que é menos compreendido, e deve ser tratado primeiro?
• Pronto: quais testes, métricas ou revisões contam como prova?

Ofereça uma recomendação quando as evidências apoiarem uma. Sempre deixe o usuário responder "ainda não decidido". Essa resposta vai em Decisões em aberto, não em um palpite.

Para uma atualização pequena, pule direto para a escrita. Para um novo roadmap, espere duas ou três rodadas.

4. Escolha uma estrutura

• Um arquivo (ROADMAP.md, ou um nome que se ajuste ao repositório) para a maioria dos roadmaps.
• Um diretório (roadmaps/<slug>/README.md mais páginas de apoio) somente quando o plano precisar de material de suporte extenso, como notas de pesquisa, um esboço de design ou matrizes de teste, que enterrariam os itens de trabalho. A página principal ainda mantém todos os IDs dos itens de trabalho.

5. Escreva-o

Use o template abaixo. Regras que o mantêm útil ao longo do tempo:

• IDs estáveis. Dê a cada item de trabalho um ID como R-001. Nunca renumerar e nunca reutilizar um ID. Trabalho abandonado permanece no arquivo, marcado como dropped (abandonado), com o motivo.
• Fases têm critérios de saída. Cada fase diz o que é verdade quando ela é concluída. Ordene as fases primeiro por dependência, depois por risco, depois por valor.
• Critérios de aceitação são verificáveis. Escreva critérios que alguém possa verificar: um teste que passe, um comando que tenha sucesso, um número mensurável. Evite palavras como "robusto", "melhorado" e "limpo".
• Dependências são explícitas. Liste-as por ID. Destaque qualquer coisa fora do controle da equipe, como outro repositório, um fornecedor ou uma decisão.
• Vincule evidências por URL completo ou caminho relativo ao repositório, para que os links sobrevivam a cópias em outros lugares.
• Descreva o plano, não a reunião. Presente, estado atual. O histórico vai no changelog.

6. Verifique-o

Antes de entregar:

• Cada item tem um ID, um status e pelo menos um critério de aceitação.
• Cada dependência aponta para um ID que existe.
• Nenhuma fase depende de uma fase posterior.
• Toda pergunta não decidida está em Decisões em aberto, não escondida em um item.
• Os links funcionam e os caminhos dos arquivos existem.
• As verificações de formatação e documentação do repositório passam.
• O changelog tem uma entrada para esta alteração.

7. Relate

Diga ao usuário o que você criou ou alterou, as decisões que registrou e as perguntas que ainda estão em aberto.

Reconciliando um roadmap com a realidade

Roadmaps se desviam à medida que o trabalho é entregue. Para reconciliar um:

1. Liste os itens que não estão como done (concluído) ou dropped (abandonado).
2. Para cada um, procure PRs mesclados, issues fechadas e código que satisfaça seus critérios de aceitação.
3. Marque um item como done somente quando cada critério for atendido. Vincule a evidência.
4. Se o trabalho foi entregue de forma diferente do plano, atualize o item para dizer o que realmente aconteceu e anote a diferença no changelog.
5. Adicione qualquer novo trabalho que você descobrir como novos itens com novos IDs.
6. Resuma as alterações para o usuário. Pergunte antes de abandonar algo.

Revisando um roadmap

Quando solicitado apenas a revisar, não reescreva. Relate, do mais importante ao menos:

• metas ou fases sem como saber quando estão concluídas;
• itens com critérios de aceitação vagos;
• dependências ausentes ou circulares;
• decisões apresentadas como resolvidas que as evidências não suportam;
• itens que o código ou rastreador de issues mostra como já concluídos ou não mais relevantes;
• riscos ausentes: as partes mais difíceis ou menos compreendidas agendadas para o final.

Template

# Roadmap de <Projeto ou funcionalidade>

**Objetivo:** <o resultado, em uma ou duas frases>
**Status:** <rascunho | ativo | concluído | substituído>
**Última atualização:** <AAAA-MM-DD>

## Contexto

Por que este trabalho importa agora, o que existe hoje e links para as evidências.

## Escopo

- **Dentro:** …
- **Fora:** …
- **Não pode mudar:** …

## Legenda de status

| Status         | Significado                                        |
| -------------- | -------------------------------------------------- |
| `planned`      | Acordado, não iniciado                             |
| `in-progress`  | Alguém está trabalhando nisso                      |
| `blocked`      | Aguardando dependência ou decisão (diga qual)      |
| `done`         | Todos os critérios de aceitação atendidos, com evidência |
| `dropped`      | Não será feito (diga por que)                      |

## Fase 1: <nome>

**Critérios de saída:** <o que é verdade quando esta fase é concluída>

### R-001: <título curto>

- **Status:** planned
- **Por que:** <o problema que isso resolve>
- **Critérios de aceitação:**
  - [ ] <declaração verificável>
- **Depende de:** <IDs, ou "nenhuma">
- **Evidência:** <links para issue, PR ou arquivo>

## Fase 2: <nome>

…

## Decisões em aberto

| ID    | Pergunta | Opções | Bloqueia | Responsável |
| ----- | -------- | ------ | -------- | ----------- |
| D-001 | …        | …      | R-004    | …           |

## Riscos

| Risco | Probabilidade | Impacto | Mitigação |
| ----- | ------------- | ------- | --------- |

## Changelog

- <AAAA-MM-DD>: <o que mudou e por que>

Remova seções que não se aplicam. Um roadmap pequeno pode ser apenas um objetivo, uma fase e um changelog.

Não faça

• Inventar uma decisão porque o roadmap parece incompleto sem ela.
• Inflar o plano com itens genéricos ("adicionar documentação", "melhorar testes") que não têm resultado específico.
• Renumerar itens ou excluir os abandonados.
• Marcar trabalho como done apenas pelo título de um PR sem verificar os critérios.
• Copiar todo o conteúdo de um roadmap para issues, ou o contrário. Vincule em vez disso.