Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

🔬 Processo RSE — Research, Strategy, Execution

O ciclo RSE é o fluxo obrigatório de contribuição. Ele é simples, escasso em formalidade, e não pula para código. Agentes de IA que trabalham no PAEBIRU devem segui-lo: a skill paebiru-developer operacionaliza o ciclo inteiro.

flowchart LR
    A[Issue /<br/>necessidade] --> R[Research<br/>O que existe?]
    R -->|gaps| S[Strategy<br/>Onde colocar?]
    S -->|plano| E[Execution<br/>Cirurgia + testes]
    E -->|falhou| R
    E -->|passou| P[PR +<br/>checklist]
    P --> M[Maintainer<br/>merge]
    M -->|regressão| R

1. Research

Pergunta-guia: “O que já existe, o que falta, e quem tentou isso antes?”

Atividades:

  1. Cite a fonte do problema. Issue? Runbook? RFC em DRAFT/PROPOSED? Bug? Postmortem? Sem fonte, a tarefa não é contribuição — é feature creep.
  2. Mapeie os Bounded Contexts afetados. Para cada um, abra a BC doc correspondente em architecture/bounded-contexts/. Se não existir, a tarefa é primeiro escrever a BC doc.
  3. Verifique o Dicionário canônico reference/dictionary.md para termos relevantes. Se um termo não estiver, adicione-o antes de propor código.
  4. Leia a skill relevante em .agents/skills/ — ou paebiru-architect se for transversal.
  5. Procure RFCs em formalização em rfc/README.md. Se a sua mudança intersecta um tópico, escreva a RFC primeiro ou espere a ratificação daquela.

Saída esperada: parágrafo de 5-10 linhas na descrição da issue ou do PR, respondendo:

  • Qual problema está sendo resolvido?
  • Quais BCs são afetados?
  • Quais dogmas estão em jogo (4 Dogmas)?
  • Quais termos do Dicionário precisam ser revisados/criados?
  • Quais RFCs estão relacionadas ou em formalização?

2. Strategy

Pergunta-guia: “Onde colocar a mudança sem costurar contextos?”

Atividades:

  1. Escolha a membrana certa. Se a mudança cruza dois BCs, você provavelmente está costurando — volte à fase 1 e reestruture. Em caso de dúvida, abra uma issue com a tag architect-help antes de prosseguir.
  2. Defina a interface (port) antes da implementação. Traits em crates/<bc>/src/ports/ são a fronteira. Se a interface pública muda, é RFC obrigatória (ver §7 do CONTRIBUTING).
  3. Liste os testes que vão cobrir a mudança. Mínimo:
    • 1 teste unitário por novo tipo/função pública;
    • 1 teste de integração se tocar actor/ ou adaptadores;
    • 1 teste property-based se tocar invariante (DVV, soma zero, Landauer, etc.);
    • 1 teste no_std se tocar Kernel/Math.
  4. Identifique o gate de qualidade (ver quality.md):
    • Conformidade (lint, fmt, audit)?
    • GALS & Domínio (test, cobertura)?
    • Verificação formal (TLA+/Lean 4)?
    • Embarcada (no_std build)?
  5. Documente o que pode dar errado. Liste 2-3 cenários de regressão e como o teste pega cada um.

Saída esperada: parágrafo de 5-10 linhas descrevendo:

  • Em que BC/crate a mudança entra.
  • Qual a nova interface (se houver).
  • Lista de testes a serem escritos.
  • Gate de qualidade aplicável.
  • Riscos e mitigações.

3. Execution

Pergunta-guia: “Como implementar de forma cirúrgica e validável?”

Atividades:

  1. Branches pequenos. Um branch por unidade lógica: feat/<bc>-<unidade>, fix/<bc>-<sintoma>, docs/<escopo>, rfc/<número>-<slug>.
  2. Commits atômicos. Um commit por mudança conceitual. Mensagem em imperativo, assunto ≤ 72 chars, corpo que responde por quê (não o quê).
  3. Validação local antes do push: 
    make check         # tipos
make lint          # clippy + fmt --check
make test          # suíte
make coverage      # ≥ 90 % de linhas
make pre-commit    # hooks locais
  4. Atualize o que mudou fora do código:
    • BC doc se a API pública mudou.
    • Dicionário se um termo novo entrou em uso.
    • Runbook se a mudança afeta operação.
    • CHANGELOG.md na seção Unreleased (categoria: Added/Changed/Fixed/Security/Removed).
  5. PR com checklist completo. Use o template. Preencha:
    • Ciclo RSE (1-2 linhas cada).
    • 4 Dogmas preservados (declaração explícita).
    • Cobertura antes/depois.
    • RFCs citadas (se aplicável).
    • Atribuição correta (DCO Signed-off-by).

Saída esperada: PR aberto com CI verde, revisores marcados, descrição completa.

4. Review & Merge

Quem revisa: 1 mantenedor + 1 peer do BC afetado. Quem aprova: mantenedor com permissão de merge. Merge strategy: squash and merge por padrão, rebase and merge para séries de 1-3 commits coesos.

Checklist do reviewer:

  • Código lê como a prosa do BC doc.
  • Não há costura entre BCs.
  • Não há Mutex/Arc<Mutex<>> cruzando fronteira.
  • Não há std::time::Instant no domínio.
  • Não há bloqueio dentro de loops de ator.
  • Não há novos warnings de cargo clippy.
  • Cobertura mantida (≥ 90 %).
  • BC doc / Dicionário / CHANGELOG atualizados.

5. Anti-padrões de processo

❌ Anti-padrão✅ Correção
“Vou só commitar isso rapidinho” sem RFCAbra issue → estratégia → execute
“Vou refatorar a BC vizinha pra ficar consistente”Refatore em PR separado, antes ou depois
“Vou adicionar essa dependência que resolve tudo”Avalie o Lockfile, o footprint no_std, e a licença
“Vou pular o pre-commit, o CI pega”CI não substitui pre-commit — corra local
“Vou usar IA para gerar o commit message inteiro”IA pode sugerir, você valida e assina
“Vou só atualizar a doc do BC, sem mexer no código”Ótimo — mas como PR separado, com peer de docs

6. Veja também