felvieira/architecture-deepener

Architecture Deepener — Refactors que Importam

Identificar friccao arquitetural e propor deepening opportunities — refactors que transformam modulos shallow em deep. Objetivo: testabilidade + AI-navigability (codebase que agente consegue evoluir sem quebrar coisas).

Adaptado de mattpocock/skills/engineering/improve-codebase-architecture e integrado ao kit (skill 23 Migration & Refactor + skill 33 Detective Spec + policies/vertical-slices.md).

Fitness Functions YAML (v2.5.0+)

Inspirado em Birgitta Böckeler (Thoughtworks) + Neal Ford ("Building Evolutionary Architectures"). Ver docs/inspiration/harness-engineering.md + policies/harness-categories.md.

Esta skill agora também produz fitness functions runnable quando o usuário pedir auditoria arquitetural com gates concretos. Formato canônico:

# .harness/fitness-functions.yml
fitness_functions:
  - id: <kebab-case-id>
    description: "Frase clara do que regula"
    type: structural | performance | accessibility | security
    runner: grep | dep-cruiser | lighthouse | custom-script
    rule: <padrão ou query do runner>
    fail_threshold: <int — 0 = zero tolerância>
    severity: high | medium | low
    applies_to: <glob opcional>

Exemplo prático — leaky abstraction de DB:

- id: no-db-in-domain
  description: Domain layer não importa bibliotecas de DB
  type: structural
  runner: dep-cruiser
  rule:
    forbidden:
      - from: 'src/domain/'
        to: '(prisma|typeorm|sequelize|knex|pg|mongodb)'
  severity: high

Quando produzir YAML vs apenas relatório:

| Output | Quando | |---|---| | Relatório markdown apenas | Auditoria inicial, usuário entendendo opções | | + fitness-functions.yml | Quer gate automatizado, tem CI, prevenir regressão | | + Aplicar refactor | Via /auto, /swarm ou refactor-safely |

Ao produzir YAML, salvar em <consumer>/.harness/fitness-functions.yml. Roadmap v2.5.1: /run-fitness command runs the file.

Governanca Global

Esta skill segue GLOBAL.md, policies/source-driven.md, policies/writing-clarity.md, policies/handoffs.md.

Filosofia

Deletion test: imagine deletar o modulo. Se complexidade desaparece, era pass-through. Se complexidade reaparece em N callers, estava ganhando seu lugar.

The interface is the test surface.

One adapter = hypothetical seam. Two adapters = real seam.

Glossario (use exatamente — consistencia e o ponto)

Nao deslizar para "component", "service", "API", "boundary". Definicoes:

• Module — qualquer coisa com interface e implementacao (funcao, classe, package, slice).
• Interface — tudo que o caller precisa saber para usar o modulo: tipos, invariantes, modos de erro, ordering, config. Nao apenas a assinatura de tipo.
• Implementation — codigo dentro.
• Depth — leverage na interface: muito comportamento atras de interface pequena. Deep = alta leverage. Shallow = interface quase tao complexa quanto a implementacao.
• Seam — onde uma interface vive; lugar onde comportamento pode ser alterado sem editar in place. (Use isso, nao "boundary".)
• Adapter — coisa concreta satisfazendo uma interface em um seam.
• Leverage — o que callers ganham com depth.
• Locality — o que mantenedores ganham com depth: mudanca, bugs, conhecimento concentrados em um lugar.

Quando Usar

• semanalmente ou apos sprint de desenvolvimento (prep antes de proxima iteracao)
• antes de delegar manutencao para agente em modulo complexo
• onboarding de codebase desconhecido (mapear seams existentes)
• antes de feature grande que vai estressar arquitetura atual
• review de PR que adiciona modulo novo (esta deep ou shallow?)
• pos-/detective-spec em legado (Detective ja mapeou; Deepener propoe melhorias)

Quando NAO Usar

• bug fix localizado
• spike exploratorio
• task que ja tem ADR proibindo refactor naquela area
• codebase muito novo (deixar arquitetura emergir antes de "consertar")

Entradas Esperadas

• caminho do escopo (repo inteiro, subdir, ou modulo especifico)
• glossario de dominio do projeto (CONTEXT.md ou docs/glossary.md)
• ADRs em docs/adr/ se existirem
• (opcional) graphify-out/graph.json — god nodes priorizados
• (opcional) _detective_sdd/ — Detective Spec ja mapeou
• (opcional) max-candidates (default: 5-7)

Saidas Esperadas

• lista priorizada de deepening candidates em formato markdown (template ## Architecture Deepening Candidates mais abaixo)
• caminho de saida: _architecture_review/YYYY-MM-DD-candidates.md (criar dir se nao existir, gitignored por default)
• (se conversa de grilling produziu termos novos) entradas inseridas em CONTEXT.md
• (se usuario rejeitou candidato com motivo load-bearing) ADR proposto em docs/adr/
• handoff para skill 23 (Migration & Refactor) com plano de deepening do candidato escolhido
• nenhum codigo do projeto modificado (Deepener so propoe; skill 23 executa)

Pre-requisitos

• glossario de dominio do projeto (CONTEXT.md ou docs/glossary.md) — sem isso, nomes ficam genericos
• ADRs em docs/adr/ (se existirem) — respeitar decisoes registradas
• (opcional) graphify-out/graph.json — god nodes sao candidatos prioritarios
• (opcional) _detective_sdd/ — Detective ja mapeou; reusar

Processo

Fase 1 — Explore

Ler glossario de dominio + ADRs primeiro. Depois usar Read/Grep/Glob (ou despachar Explore subagent) para caminhar pelo codebase.

Nao siga heuristicas rigidas — explore organicamente e anote onde voce sente friccao:

• Onde entender UM conceito exige pular entre N modulos pequenos?
• Onde modulos sao shallow — interface quase tao complexa quanto implementacao?
• Onde funcoes puras foram extraidas apenas para testabilidade, mas bugs reais escondem em como sao chamadas (sem locality)?
• Onde modulos acoplados vazam pelos seams?
• Quais partes nao sao testadas, ou sao dificeis de testar pela interface atual?

Aplicar o deletion test em qualquer suspeito de shallow: deletar concentraria complexidade ou apenas a moveria? "Sim, concentra" e o sinal que voce quer.

Fase 2 — Apresentar candidatos

Lista numerada de deepening opportunities. Para cada candidato:

• Files — quais files/modules envolvidos
• Problem — por que arquitetura atual causa friccao
• Solution — descricao em portugues claro do que mudaria
• Benefits — explicados em termos de locality e leverage, e como testes melhorariam

Usar vocabulario do glossario do projeto para o dominio, e o glossario desta skill para arquitetura. Se CONTEXT.md define "Order", fale "modulo de Order intake" — nao "FooBarHandler", nem "Order service" generico.

Conflitos com ADR: se candidato contradiz ADR existente, so trazer quando friccao for real o suficiente para reabrir o ADR. Marcar claramente: "contradicts ADR-0007 — but worth reopening because…". NAO listar todo refactor teorico que ADR proibe.

NAO propor interfaces ainda. Perguntar: "Qual destes voce quer explorar?"

Fase 3 — Grilling Loop (sobre o candidato escolhido)

Quando usuario escolhe um candidato, entrar em conversa de grilling (analoga a /grill-me). Caminhar pela arvore de design — restricoes, dependencias, shape do modulo deepened, o que fica atras do seam, quais testes sobrevivem.

Side effects acontecem inline conforme decisoes cristalizam:

• Nomeando modulo deepened com termo nao em CONTEXT.md? Adicionar termo ao CONTEXT.md — mesma disciplina de skill 28 (CLAUDE.md Generator). Criar arquivo lazy se nao existir.
• Refinando termo durante a conversa? Atualizar CONTEXT.md ali mesmo.
• Usuario rejeita candidato com motivo "load-bearing"? Oferecer ADR: "Quer registrar isso como ADR para que reviews futuros nao re-sugiram?". So oferecer quando o motivo seria realmente necessario para um explorador futuro evitar re-sugestao — pular motivos efemeros ("nao vale a pena agora") e auto-evidentes.

Heuristicas de Detecao

| Sintoma | Suspeita | Acao | |---|---|---| | Modulo so re-exporta de outro | shallow / pass-through | deletion test | | Interface tem 10 metodos, cada um faz so 1 thing | shallow | mover comportamento para dentro, expor menos | | Bugs sempre em "como X e usado", nunca em X | falta locality | unificar X com chamadores | | Multiplos modulos sabem como chamar Y na ordem certa | seam errado / shallow | esconder ordem dentro de modulo deep | | Refactor pequeno quebra muitos testes | testes acoplados a implementacao | reescrever testes pela interface; modulo provavelmente shallow | | God file (>1000 linhas, >20 callers) | falta de seam | identificar sub-responsabilidades, criar seams |

Coordenar com graphify quando disponivel:

• god nodes do graphify-out/GRAPH_REPORT.md = candidatos prioritarios
• bridges entre comunidades = seams ja existentes (boas ou ruins)
• comunidades coesas = candidates a virar deep modules (interface unica, implementacao concentrada)

Output

# Architecture Deepening Candidates — <YYYY-MM-DD>

**Scope:** src/...
**Source:** <CONTEXT.md / ADRs / graphify / Detective Spec>

## Candidates (priorizados)

### 1. <nome usando vocabulario do dominio>
**Files:** src/foo.ts, src/bar.ts, src/baz/index.ts
**Problem:** entender Order intake exige pular entre FooBarHandler, OrderService, OrderValidator e OrderRepository. Validacao acontece em 3 lugares com regras ligeiramente diferentes (RN-005 vs RN-012).
**Solution:** consolidar Order intake atras de modulo unico `OrderIntake` com interface `intake(rawOrder): Order | OrderError`. Esconder validacao + persistencia + emit-event atras desse seam.
**Benefits:**
- **Leverage:** callers param de saber sobre os 4 modulos
- **Locality:** validacao em 1 lugar, RN-005 vs RN-012 conflito vira impossivel
- **Testabilidade:** 1 interface a testar, vs 4 hoje. Testes ficam integration-style por default.

### 2. ...

## Recomendacao

Pegue 1 candidato por vez. Comecar pelo numero 1 (highest leverage).

## Para discutir
Qual candidato voce quer explorar? (responda com numero)

Anti-Padroes

"Refactor por refactor"

Mexer porque "ficou feio" sem deletion test = mover complexidade, nao remover. Sempre rodar deletion test primeiro.

"Usar vocabulario novo"

Inventar "OrderProcessor" quando glossario diz "Order intake" = drift terminologico. Sempre usar termos do CONTEXT.md.

"Re-litigar ADR"

ADR-0007 proibe X. Refactor sugere X. Solucao: re-abrir ADR primeiro, justificar mudanca, depois refactorar. Nao silenciosamente contradizer.

"Propor 20 candidatos"

Usuario nao consegue priorizar lista de 20. Maximo 5-7 candidatos, ordenados por impacto.

"Propor solucao antes de validar problema"

"Aqui esta a interface nova" antes de "voce concorda que e shallow?" = perde feedback do usuario sobre a fricao real.

Evidencia de Conclusao

• lista priorizada de candidatos com deletion test aplicado
• vocabulario do dominio respeitado em toda proposta
• ADRs respeitados (ou conflito explicitamente marcado)
• nenhum codigo modificado nesta fase (Deepener so propoe; skill 23 implementa)

Handoff

Apos usuario escolher candidato e fase de grilling concluir:

1. Skill 23 (Migration & Refactor): recebe plano de deepening + executa o refactor incremental com feature flags
2. Skill 37 (TDD Engineer): escreve testes contra a NOVA interface antes da migracao (red-green-refactor)
3. Skill 28 (CLAUDE.md Generator): atualiza CLAUDE.md se vocabulario novo emergiu
4. Documenter (skill 10): registra ADR se conversa gerou decisao "load-bearing"

Integracao com Pipeline

• Detective Spec (33): roda ANTES desta skill em legado, mapeia o que existe
• Repo Auditor (18): roda antes para ter current.md atualizado
• Migration & Refactor (23): sempre roda DEPOIS desta skill — Deepener propoe, Migration executa
• TDD Engineer (37): acompanha refactor, garantindo testes contra interface nova
• CLAUDE.md Generator (28): atualiza vocabulario quando termos novos emergem
• Reviewer (11): valida que refactor manteve comportamento (testes verdes)

Material Adicional

• docs/skill-guides/architecture-language.md (a criar conforme demanda) — glossario completo equivalente a LANGUAGE.md
• docs/skill-guides/architecture-deepening.md — exemplos de antes/depois, padroes comuns
• docs/skill-guides/architecture-interface-design.md — design de interface boa