Contributing - SOT Product Governance Guide¶

1. Objetivo¶

Este arquivo e o guia central de uso e evolucao do SOT.

O SOT existe para manter estrategia, arquitetura, planejamento e rastreabilidade de produto em um unico repositorio, reduzindo dependencia de ferramentas externas para coordenacao entre gestao e implementacao.

2. Regra principal¶

Toda mudanca no SOT altera a governanca do produto.

Por isso, toda PR no SOT deve ter: - no minimo 2 aprovacoes de gestores - rastreabilidade explicita entre intencao, artefato e impacto - historico de mudanca claro via commits semanticos

3. Estrutura canonica do repositorio¶

docs/: documentacao para humanos e publicacao via MkDocs.
agents/: agents e skills por funcao e componente.
plan/: governanca de planejamento segmentavel por dominio/subdominio e por fase (dev e ops).
product-definition/: referencia de metodo e entregaveis para discovery, inception e handoff para implementacao.

3.1 Uso por papel¶

PO/PM: usa product-definition, agents/plan e plan/* para planejar e acompanhar.
Arquiteto/Lider de desenvolvimento: registra direcao tecnica em docs/* e ADRs em plan/adr/*.
Engenharia: executa backlog com base em plan/dev/sprints/* e artefatos de dominio.
Operacoes/Plataforma: registra rotina e mudancas em plan/ops/sprints/*.

3.2 Diagramas Mermaid desacoplados¶

Arquivos Mermaid ficam em docs/diagrams/*.
Paginas markdown fazem referencia por include (--8<--) para evitar diagramas longos inline.
Edicao visual pode ser feita em editores externos, mantendo o arquivo fonte versionado no SOT.

3.3 Segmentacao de planejamento por contexto¶

O planejamento pode ser separado por dominio/subdominio e por fase (dev e ops).
Exemplo: AuthN e AuthZ podem manter trilhas independentes de planejamento.
Times diferentes podem atuar nesses contextos em paralelo ou em janelas distintas.
Estrutura sugerida quando necessario:
plan/dev/<dominio>/<subdominio>/...
plan/ops/<dominio>/<subdominio>/...

4. Fluxo SDLC do produto¶

Fluxo padrao esperado: 1. SOW 2. Discovery 3. Inception 4. Implementacao 5. Operacao e melhoria continua

4.1 Outputs minimos por fase¶

SOW: documento de contexto inicial ou referencia contratual usada como entrada do discovery
Discovery: product-definition/discovery/problem-overview.md, product-definition/discovery/problem-domain-map.md, product-definition/discovery/process-map.md, product-definition/discovery/glossary.md
Inception: product-definition/inception/inputs-from-discovery.md, product-definition/inception/handoff-to-implementation.md, plan/project_definitions.md, ADRs iniciais
Implementacao: plan/dev[/<dominio>/<subdominio>]/sprints/<YYYY-Www>.md + links para issue/PR
Operacao: plan/ops[/<dominio>/<subdominio>]/sprints/<YYYY-Www>.md + evidencias operacionais

5. Rastreabilidade obrigatoria¶

IDs padrao: - EPIC-<dominio>-NNN - ADR-<dominio>-NNN - STORY-<dominio>-YYYYWW-NN - TASK-<dominio>-YYYYWW-NN - OPSTASK-<dominio>-YYYYWW-NN - OPSINC-<dominio>-YYYYWW-NN (quando aplicavel)

Relacoes minimas: - STORY -> sprint dev + issue + ADR (quando houver) - TASK -> STORY + issue/PR + evidencia de validacao - OPSTASK -> sprint ops + ambiente + evidencia operacional

6. Regras de mudanca e aprovacao¶

Toda PR no SOT exige 2 gestores aprovando.
Toda mudanca arquitetural relevante exige ADR no SOT.
Toda sprint atualizada deve refletir status real de issues/PRs.
Nenhuma mudanca relevante de produto deve ficar fora do SOT.

Observacao: a regra de aprovacao deve ser reforcada por CODEOWNERS e branch protection no provedor Git.

7. Padrao de contribuicao¶

7.1 Commits¶

Usar Conventional Commits: - feat: nova capacidade - fix: correcao - docs: ajuste documental - refactor: reorganizacao sem mudanca funcional - chore: manutencao

7.2 Pull Requests¶

Toda PR deve: - referenciar IDs e artefatos impactados - declarar impacto em governanca - incluir evidencia de validacao (quando aplicavel) - cumprir checklist do template de PR

8. Organizacao por dominio/subdominio¶

Times devem se organizar por dominio/subdominio.

Cada subdominio e composto por componentes implementados em repositorios independentes, mantidos ao lado do SOT no workspace local. O SOT atua como elo de coesao e integracao entre os componentes.

9. Planejamento por sprint e analise de evolucao¶

Sprint planning e fechamento devem ficar em arquivos datados.
Lead time e taxa de mudanca podem ser avaliados por diff entre sprints.
Agentes de planejamento podem automatizar consolidacao de status, riscos e desvios.
Dominios/subdominios podem evoluir em ritmos diferentes, com times distintos em dev e ops.

10. Agents e skills como aceleradores¶

agents/dev: diretrizes e skills de implementacao por componente.
agents/ops: diretrizes e skills de operacao por ambiente.
agents/plan: diretrizes e skills de planejamento/arquitetura.

11. Checklist minimo de PR no SOT¶

[ ] Mudanca vinculada a fase do SDLC e a artefatos corretos.
[ ] IDs de rastreabilidade aplicados.
[ ] Links para issue/PR de implementacao (ou justificativa quando nao houver).
[ ] Sprint/ADR atualizada quando aplicavel.
[ ] Impacto em governanca descrito.
[ ] Duas aprovacoes de gestores registradas.

12. Seguranca e escopo¶

Este SOT cobre AuthN/AuthZ e pode ser replicado para outros produtos.
Informacoes sensiveis devem ser minimizadas e classificadas.
Codigo fonte continua nos repositorios de componentes; o SOT guarda direcao e rastreabilidade.