haos-structural-refactor

Files (3)

• SKILL.md
• scan_structural_risk.py · scripts/
• test_scan_structural_risk.py · tests/

SKILL.md (first lines)

# HAOS Structural Refactor

Opere em `AUDIT` por padrao. Trate tamanho apenas como **sinal de triagem**: um
arquivo acima do teto e candidato a inspecao, **nao e prova de divida tecnica**.
Arquivo de 900 linhas coeso e com dono claro pode estar certo; arquivo de 200
linhas que mistura parsing, I/O e regra de negocio pode estar errado.

---

## 1. Quem executa (leia isto ANTES de qualquer coisa)

**O main nao roda o scanner.** No Claude Code o hook `main_guard.py` esta em
ENFORCE e bloqueia fisicamente o main de rodar `python`, `py`, `pwsh`, `npm` e de
editar arquivo de projeto. A allowlist do main e **so de leitura**.
`[verifiquei: CLAUDE.md §1 -> "ENFORCE ligado (ENFORCE_DEFAULT = True)", allowlist explicita de leitura pura]`

Portanto:

| Papel | O que faz |
|---|---|
| **Main** | Le (`Read`/`Grep`/`Glob`), define escopo e teto, **spawna o sub-agente que roda o scanner**, le o relatorio devolvido, prioriza e decide. |
| **Sub-agente do AUDIT** | Roda o scanner, inspeciona os candidatos no codigo real, devolve o relatorio. Read-only. |
| **Sub-agente do APPLY** | Escreve. So entra depois do gate. |

### Briefing pronto para colar no sub-agente do AUDIT

Resolva `<skill-dir>` como o diretorio que contem este `SKILL.md`, hoje
`<SEU_CAMINHO>/skills/haos-structural-refactor`. O comando:

```bash
py -3 "<SEU_CAMINHO>/skills/haos-structural-refactor/scripts/scan_structural_risk.py" "<root>" --max-lines 350 --format markdown
```

Variantes: `--format json` para consumo estruturado, `--output <arquivo>` para
gravar o relatorio (o script **recusa sobrescrever** arquivo existente). O scanner
nunca altera o que analisa e **nunca imprime o conteudo dos arquivos**, so caminho
e contagem.
`[verifiquei: py -3 scripts/scan_structural_risk.py --help -> exit 0, flags root/--max-lines/--format/--output]`

Escolha do tipo de sub-agente:

| Situacao | `subagent_type` | `model` |
|---|---|---|
| So rodar o scanner e devolver a tabela | `Explore` | `haiku` |
| Rodar o scanner **e** interpretar os candidatos no codigo | `haos:dev-backend` | `sonnet` |
| Julgar costura, contrato publico, risco de quebra | `Plan` ou `haos:dev-backend` | `opus` |

`model` e **obrigatorio** em todo `Agent`: o hook `model_guard.py` esta em
ENFORCE e bloqueia o spawn sem tier valido.

---

## 2. Preflight automatico (a skill entra sozinha)

Antes de **qualquer alteracao substancial em modulo ja existente** (refatorar,
acrescentar responsabilidade nova, mexer em arquivo que voce nao conhece), rode o
`AUDIT` no **menor escopo afetado**, nao no repo inteiro. Custo de segundos, evita
engordar um arquivo que ja passou do teto.

Nao e preciso o usuario pedir. Nao vale a pena para arquivo novo, script isolado
ou correcao de uma linha.

---

## 3. AUDIT

1. **Ground truth fresca:** estado do worktree (`git status`), manifests, estrutura
   e os comandos oficiais de teste do projeto. Preserve alteracao preexistente que
   voce nao criou.
2. **Rode o scanner** (via sub-agente, §1) e **inspecione cada candidato no codigo
   real**. Avalie mistura de responsabilidades, coesao, fan-in/fan-out, contratos
   publicos, estado compartilhado, cobertura de teste e historico de mudanca.
   **Nao conclua risco pela contagem de linhas isolada.**
3. **Baseline e validacoes:** carregue `haos-quality-gates` para fixar o baseline
   numerico e a escada de gates da stack antes de propor qualquer mexida.
4. **Ondas e ownership:** carregue `haos-execution-waves` para montar o plano por
   ondas com dono unico por arquivo, dependencias, artefato e evidencia.
5. **Grafo de codigo:** quando o impacto for transversal, houver contrato
   compartilhado ou a arquitetura for desconhecida, use os MCPs **nativos** desta
   casa em vez de qualquer indexador externo:

   | Pergunta | Ferramenta |
   |---|---|
   | Onde este simbolo e definido? | `mcp__gbrain__code_def` |
   | Quem chama isto (raio de impacto direto)? | `mcp__gbrain__code_callers` |
   | O que isto chama? | `mcp__gbrain__code_callees` |
   | Raio de impacto transitivo, por profundidade | `mcp__gbrain__code_blast` |
   | Toda mencao literal (rename, deprecacao) | `mcp__gbrain__code_refs` |
   | Cadeia de execucao ate o efeito colateral | `mcp__gbrain__code_flow` |

   **Confirme no codigo toda relacao que o grafo apontar.** O grafo orienta a
   busca; ele nao substitui a leitura. **Nao instale Graphify** e nao leia indice
   de outro runtime.
   Atencao: MCP so existe para o **main**. Sub-agente nao enxerga MCP | se o AUDIT
   precisa do grafo, quem consulta e o main, e ele passa o resultado no briefing.

6. **Entregue** candidatos priorizados, evidencias, costuras naturais, plano por
   ondas, testes previstos e risco residual. Permaneca **read-only**.

### Costuras naturais

Fronteira de dominio, adaptador de I/O, parsing, validacao, persistencia,
apresentacao e componente com estado independente. **Extraia por essas fronteiras.**
Nao divida so para baixar um numero: corte arbitrario troca um arquivo grande por
tres arquivos acoplados, que e pior.

---

## 4. APPLY

Entre em `APPLY` **somente quando o usuario pedir implementacao**. Refatoracao
ampla, transversal ou com varios modulos exige primeiro baseline e plano e, depois,
**OK explicito do dono** no gate apresentado antes da primeira escrita.

1. Revalide ground truth e baseline **imediatamente antes** de editar.
2. Preserve API publica, comportamento observavel e compatibilidade, salvo mudanca
   de contrato explicitamente aprovada.
3. **Delegue.** O main nao escreve. Owner e `haos:dev-backend`, `haos:dev-frontend`
   ou `haos:devops`, com write-set explicito.

From simtransforma/HAOS-CC-Model, MIT.

More from simtransforma/HAOS-CC-Model