Plataforma - Auditoria Final de Docs¶
Objetivo¶
Consolidar a leitura do estado atual da documentação restante do auraxis-platform
após as ondas de limpeza, separando o que deve ser:
- mantido como fonte canônica ativa;
- consolidado antes de nova remoção;
- removido apenas em ondas futuras, com validação adicional.
O objetivo desta auditoria não é apagar mais arquivos imediatamente. O foco é fechar critérios de governança para que as próximas limpezas não atinjam docs operacionais, automações, runtime de agentes ou superfícies de leitura úteis.
Resumo executivo¶
| Grupo | Situação | Recomendação |
|---|---|---|
.context operacional canônica |
saudável | manter |
| runbooks de release/deploy | saudáveis | manter |
| docs de runtime agêntico atuais | ativas e úteis | manter |
| docs conceituais antigas de arquitetura/processo | parcialmente redundantes | consolidar antes de remover |
docs curadas em docs/wiki/ |
saudáveis | manter e expandir |
Critério de decisão¶
Uma doc só deve permanecer no baseline ativo se cumprir pelo menos um destes papéis:
- ser fonte canônica de operação ou governança;
- ser fonte curada de leitura para stakeholders, produto, arquitetura ou onboarding;
- ser consumida, diretamente ou indiretamente, por scripts, checks ou runbooks ativos.
Se um .md não cumprir nenhum desses papéis, ele deve ser:
- absorvido em GitHub Projects, MkDocs/Wiki ou runbook canônico;
- ou removido do baseline ativo.
Grupo A — manter¶
.context canônica ativa¶
| Arquivo | Motivo para manter |
|---|---|
.context/00_overview.md |
overview rápido do repositório |
.context/05_handoff.md |
trilha operacional recente |
.context/06_context_index.md |
índice canônico |
.context/07_steering_global.md |
steering principal |
.context/08_agent_contract.md |
contrato operacional dos agentes |
.context/10_product_operating_model.md |
modelo operacional de produto |
.context/11_repo_map.md |
mapa dos repositórios |
.context/12_quality_security_baseline.md |
baseline de qualidade e segurança |
.context/13_release_governance.md |
governança de release |
.context/15_workflow_conventions.md |
convenções de fluxo |
.context/16_contract_compatibility_policy.md |
política de contratos |
.context/17_discovery_framework.md |
framework de discovery |
.context/18_feedback_loop.md |
ciclo de feedback por bloco |
.context/19_context_maintenance.md |
política de manutenção do contexto |
.context/20_decision_log.md |
histórico canônico de decisões |
.context/23_definition_of_done.md |
DoD canônico |
.context/25_quality_security_playbook.md |
playbook operacional canônico |
.context/31_feature_flag_lifecycle.md |
fonte única de lifecycle/bootstrap de feature flags |
.context/39_github_projects_runbook.md |
runbook do board |
.context/41_definition_of_ready.md |
DoR canônico |
.context/44_public_release_readiness_checklist.md |
readiness operacional |
.context/45_aws_ssm_remote_access_playbook.md |
onboarding de acesso remoto |
.context/48_active_docs_manifest.md |
manifesto de docs ativas |
.context/49_bootstrap_parity_playbook.md |
paridade local/CI |
.context/50_release_orchestration_runbook.md |
runbook canônico de release |
.context/52_frontend_deploy_baseline_runbook.md |
runbook canônico de deploy frontend |
.context/53_agent_runtime_diagnostics.md |
runbook/diagnóstico ativo do runtime |
.context/54_public_release_operational_runbook.md |
operação de publicação pública |
.context/56_g2_legal_minimum_pack.md |
pacote jurídico mínimo canônico |
.context/57_agent_runtime_refactor_plan.md |
plano canônico do runtime agêntico |
.context/58_crewai_reduction_execution.md |
plano canônico de redução do CrewAI |
.context/59_agent_runtime_pilot_pack.md |
pacote do piloto determinístico |
.context/60_docs_portal_runbook.md |
runbook do portal de docs |
docs/wiki/ curada¶
| Arquivo | Motivo para manter |
|---|---|
docs/wiki/README.md |
índice do portal |
docs/wiki/MVP-1-*.md |
superfície curada do MVP 1 |
docs/wiki/MVP-2-Empresas.md |
superfície curada do MVP 2 Empresas |
docs/wiki/Plataforma-Scripts.md |
catálogo humano dos scripts |
docs/wiki/Plataforma-Scripts-Matriz-de-Uso.md |
matriz canônica de uso/remoção |
Grupo B — consolidar antes de remover¶
| Arquivo | Estado atual | Destino recomendado |
|---|---|---|
.context/01_status_atual.md |
parcialmente redundante e já marcado como descontinuado | absorver em 00_overview.md + handoff recente |
.context/02_backlog_next.md |
útil, mas concorre com GitHub Projects | reduzir até virar só backlog executivo/resumo |
.context/24_frontend_quality_gaps.md |
dívida histórica ainda útil | consolidar em docs/wiki/MVP-1-*.md ou em risk log específico |
.context/24_rollback_runbook.md |
útil, mas concorre com runbooks de release | absorver em .context/50_release_orchestration_runbook.md |
.context/26_frontend_architecture.md |
ainda útil, mas volumoso | absorver gradualmente em wiki técnica |
.context/30_design_reference.md |
ainda útil | consolidar com .context/40_design_system.md |
.context/33_release_cut_policy.md |
útil, mas pequeno | absorver em .context/50_release_orchestration_runbook.md |
.context/42_kpi_tree_v1.md |
útil para leitura executiva | migrar para wiki de produto/estratégia |
.context/46_dependency_update_automation_plan.md |
ainda útil | consolidar depois em runbook de dependências |
Grupo C — remover depois (não agora)¶
| Arquivo | Motivo para segurar agora | Condição para futura remoção |
|---|---|---|
.context/04_agent_playbook.md |
onboarding curto ainda útil | quando 08_agent_contract.md absorver completamente o uso restante |
.context/40_design_system.md |
ainda é referência densa de design | depois de migrar para wiki/design docs mais curados |
.context/42_kpi_tree_v1.md |
útil para stakeholders | depois de virar página curada no portal |
.context/46_dependency_update_automation_plan.md |
processo ainda vivo | depois de consolidar em runbook único |
Grupo D — não tocar agora¶
| Grupo | Motivo |
|---|---|
runtime agêntico (53, 57, 58, 59) |
ainda em evolução; remover/consolidar agora pode degradar onboarding e manutenção |
release/deploy (45, 50, 52, 54, 56, 60) |
ainda são runbooks canônicos com uso operacional real |
contrato/governança (07, 08, 15, 16, 17, 18, 19, 23, 39) |
formam o núcleo operacional do repositório |
Oportunidades de melhoria¶
| Oportunidade | Ganho |
|---|---|
| mover arquitetura frontend para a wiki técnica em ondas pequenas | alto |
reduzir 02_backlog_next.md para um backlog executivo curto |
alto |
| consolidar release/rollback/cut policy em um único runbook | médio/alto |
| transformar KPI tree em página curada da wiki | médio |
| consolidar design reference + design system | médio |
Riscos e ameaças¶
| Risco | Impacto | Mitigação |
|---|---|---|
| remover doc ainda usada por automação | alto | só remover após busca de referência e smoke checks |
| apagar contexto útil dos agentes durante refactor | alto | manter docs do runtime até estabilização |
| voltar a criar docs concorrentes | alto | reforçar GitHub Projects + MkDocs/Wiki como superfícies primárias |
| migrar conteúdo conceitual sem curadoria | médio | consolidar por tema, não por volume |
Próximas ondas recomendadas¶
| Ordem | Tema | Estratégia |
|---|---|---|
| 1 | backlog/status executivo | reduzir 01 e 02 |
| 2 | frontend | consolidar 24, 26, 32, 36 |
| 3 | release | consolidar 24_rollback, 33, 46 |
| 4 | design/KPI | migrar 30, 40, 42 para wiki curada |
Decisão operacional¶
Até nova revisão, o projeto segue com esta política:
- GitHub Projects: fonte primária de execução;
docs/wiki/+ MkDocs/Wiki: fonte primária de leitura curada;.context: apenas o que for canônico e operacional.