aiox-core 5.0.5 → 5.0.7

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_042.md

@@ -0,0 +1,89 @@
+# AN_KE_042 - Don't Regress Working Code
+
+**Type:** Development Discipline Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Preservar o que Funciona
+**Source:** [SOURCE: Múltiplas sessões mmos — frustração recorrente com AI revertendo código funcional]
+
+## Purpose
+
+A IA tem tendência de "melhorar" código que já funciona, introduzindo regressões. Se algo funciona em localhost, a prioridade é PRESERVAR, não refatorar. Mudanças devem ser aditivas, nunca destrutivas sobre funcionalidade existente.
+
+## Configuration
+
+```yaml
+AN_KE_042:
+  name: "Don't Regress Working Code"
+  zone: "excelencia"
+  trigger: "IA propondo refatoração, simplificação, ou 'melhoria' de código existente."
+
+  rule: |
+    SE código funciona em localhost/prod
+    ENTÃO preservar. Mudanças aditivas, nunca destrutivas.
+    SE simplificação proposta → testar ANTES de aplicar.
+    SE regressão detectada → git revert imediato, não tentar consertar em cima.
+
+  sys_tension:
+    tension_with: "AN_KE_085 (Greenfield Over Spaghetti Refactor) — Refactoring vs Preservation"
+    resolution: "Default to PRESERVE when functionality works. Only REFACTOR when explicitly required for new feature integration. Always TEST before applying changes. If regression occurs, REVERT immediately and analyze surgically."
+
+  veto_condition:
+    trigger: "IA refatorando algo que estava funcionando sem garantir que continua funcionando."
+    action: "VETO — 'tava funcionando, pq está revertendo algo que estava funcionando?'"
+
+  evidence:
+    - "[SOURCE: sessão mmos 435f78cd] 'tava funcionando localhost, pq está revertendo algo que estava funcionando?'"
+    - "[SOURCE: sessão mmos 9701cc32] 'Continua puxando do banco de dados... basta reverter no git, no git tá funcionando'"
+    - "[SOURCE: sessão mmos c61a9260] 'vamos reverter essa simplificação'"
+    - "[SOURCE: sessão mmos cfecb27d] 'ta errado usar slug, o certo é usar o nome real do arquivo e trazendo a URL direto do banco'"
+```
+
+## Decision Tree
+
+```javascript
+IF (ai_proposes_refactor OR simplification)
+  IF (current_code_works_in_localhost)
+    THEN DEFAULT = PRESERVE
+    IF (refactor_is_critical for new feature)
+      THEN TEST_FIRST before applying
+    ELSE
+      THEN SKIP refactor — "if it works, don't touch it"
+  IF (regression_detected_after_change)
+    THEN IMMEDIATE git revert
+    THEN ANALYZE what broke
+    THEN RE-APPLY surgically (not the whole refactor)
+```
+
+## Failure Modes
+
+### A Melhoria que Quebra
+- **Trigger:** IA decide "simplificar" lógica de URL de imagens trocando campo real por slug derivado.
+- **Manifestation:** Imagens param de carregar. Slug não corresponde ao nome real do arquivo.
+- **Detection:** "ta errado usar slug, o certo é usar o nome real do arquivo".
+- **Recovery:** git revert + restaurar lógica original.
+- **Prevention:** Nunca substituir campo real (image_url) por campo derivado (slug) sem testar.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "regression-prevention-gate"
+  heuristic: AN_KE_042
+  phase: "Code_Review / Refactoring"
+```
+
+## Validation
+
+**Paradox Identified:** The tension between code optimization (refactoring) and system stability (preservation of working functionality) is inherent to this heuristic. The resolution enforces a conservative bias: when functionality works, optimization is deferred unless explicitly required by new features. This prevents the error pattern where "improvements" introduce silent regressions.
+
+**Application Criteria:**
+- ✓ Code executes correctly in localhost/staging
+- ✓ Existing tests pass without modification
+- ✓ No performance degradation observed
+- ✓ No security vulnerabilities exploited
+
+**Validation Triggers:**
+1. If AI proposes refactoring → require BEFORE/AFTER test evidence
+2. If regression detected → mandatory git revert + root cause analysis
+3. If refactor is feature-critical → apply surgical changes only, not full refactors

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_043.md

@@ -0,0 +1,78 @@
+# AN_KE_043 - Zero Achismos
+
+**Type:** Mental Model & Data Execution Heuristic
+**Zone:** 🔥 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Rejeição de Alucinação Criativa / Grounded Delivery
+**Source:** [SOURCE: Extrações de alinhamento estratégico, forçando a LLM e agentes a jamais inventarem diretrizes com base na teoria estocástica generalista da rede, e sim na crueza dos templates do local de trabalho.]
+
+## Purpose
+
+Prevenir que a superinteligência LLM opere no "modo palpiteiro hiper-confiante" preenchendo as lacunas e inventando estratégias maravilhosas, gerando extrapolações perigosas sem validações com a dura e inegável base dos dados, documentos reais e processos corporativos.
+
+## Configuration
+
+```yaml
+AN_KE_043:
+  name: "Zero Achismos"
+  zone: "impacto"
+  trigger: "Agente encarregado de desenhar tarefas estratégicas de execução (SOPs, Workouts) onde faltam direções."
+
+  rule: |
+    SE a IA perceber uma lacuna estratégica ao criar a solução pedida a ela
+    ENTÃO acione a diretiva de Grounded Inference: "Apenas entregue processos baseados integralmente nos templates disponíveis na base e evidências já mapeadas".
+
+  veto_condition:
+    trigger: "Criar uma tática mirabolante importada genericamente do modelo geral LLM por falta de consulta apropriada aos Manuais e Dados operacionais."
+    action: "VETO — Destrua as inovações infundadas, e opere restritamente nas paredes do que é conhecido provado da organização."
+
+  sys_tension:
+    tension_with: "AN_KE_017 (Research No Meio, Não No Início) — Permite exploração criativa durante execução vs. Zero Achismos exigindo grounding total pré-execução"
+    resolution: "When a template gap is discovered: (1) Flag the gap explicitly, (2) Deliver only grounded portions, (3) Ask human to provide the missing template or accept the incomplete scope. NEVER extrapolate to fill gaps."
+
+  evidence:
+    - "[EXACT WORDS]: Gostei, mas quero isso baseado em processos reais, em algo palpável e não achismos da LLM, cada task precisa ser baseado em estratégias comprovadas e baseada 100% em dados que temos disponiveis sem criar extrapolações."
+```
+
+## Decision Tree
+
+```javascript
+IF (creating_strategy OR fulfilling_empty_gaps_in_task)
+  IF (strategy_concept_originates_from_company_document == TRUE)
+    // Document exists e.g., 'templates/our-proven-sales-funnel.md'
+    THEN ALLOW_APPLICATION
+  ELSE
+    // Extrapolating a theoretical standard idea out of GPT's brain
+    THEN BLOCK_EXTRAPOLATION
+    THEN SEARCH_INTERNAL_BASE ("Requirir explicitamente os moldes originais locais")
+      IF (no mold found)
+        THEN RAISE_EXCEPTION_TO_USER ("Alan, não possuo o template real base disto, devo esperar que me adicione ou interromper?")
+```
+
+## Failure Modes
+
+### Escorregamento "Fake-Guru"
+- **Trigger:** Ao pesquisar e consolidar um livro de um expert, uma etapa exigia a descrição dos maiores KPIs de funil mas o documento raiz não listava nada disso.
+- **Manifestation:** O agente deduz os "5 típicos funis mundiais", escreve 18 páginas cheias de arrogância estocástica e entrega. O time acata como se fosse a genialidade do expert original.
+- **Detection:** Disparidade grave entre o trabalho pregresso (onde o modelo mental genuíno era adotado) e este "copy paste de blog moderno americano".
+- **Recovery:** Interromper, apagar os artefatos, mandar o agente reler e assumir onde "Não consta em documentação - lacuna necessária preencher por humanos".
+- **Prevention:** Gates de restrição mental: "Só responda pelo que está presente concretamente na RAG ou nos `.md` passados."
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "anti-hallucination-strategy-gate"
+  heuristic: AN_KE_043
+  phase: "Knowledge_Synthesis"
+
+  validation_questions:
+    - "Eu posso atestar em um tribunal a origem literata deste arquivo interno em relação a cada um dos processos operacionais sugeridos acima?"
+```
+
+## Validation
+
+- **Template Traceability:** Every suggested process MUST be traceable to a named template file (e.g., `templates/sales-funnel-v2.md`) or an exact document section with line reference.
+- **Evidence Chain:** If no template exists, the gap MUST be documented as `LACUNA-{id}` with escalation to human for template provisioning.
+- **No Speculative Fills:** Creativity is welcome AFTER the human provides the missing template. Until then: BLOCK and REPORT.
+- **Audit Trail:** Every decision to apply or reject a strategy suggestion MUST be logged with the source evidence or the "no source found" exception.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_044.md

@@ -0,0 +1,97 @@
+---
+heuristic_id: AN_KE_044
+name: "URL = State Truth (Deep Linking)"
+zone: excelencia
+type: "Architecture UI/UX Heuristic"
+agent: "@oalanicolas"
+pattern: "React & JS State vs Browser History"
+sys_tension:
+  tension_with: "AN_KE_103 (Local Caching Over Live Database)"
+  resolution: "Lazy-load state from URL params on mount; cache parsed state in React memory for perf; invalidate on URL change"
+source: |
+  Frustrações expressas com componentes que aprisionam o "State" localmente e quebram as premissas primárias do "Browser" (foward, back, refresh). Refatorações em Dashboards e Lojas de Cursos.
+---
+
+# AN_KE_044 - URL = State Truth (Deep Linking)
+
+**Type:** Architecture UI/UX Heuristic
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** React & JS State vs Browser History
+**Source:** [SOURCE: Frustrações expressas com componentes que aprisionam o "State" localmente e quebram as premissas primárias do "Browser" (foward, back, refresh). Refatorações em Dashboards e Lojas de Cursos.]
+
+## Purpose
+
+Assegurar acessibilidade profunda em projetos web complexos. Quando listas compridas, filtros ou abas vivem apenas em um `useState` em React sem reflexos na URL do browser (e.g. `?tab=cursos&page=2`), o usuário perde anos de memória celular de navegação web (refresh destrói as tabs ativas).
+
+## Configuration
+
+```yaml
+AN_KE_044:
+  name: "URL = State Truth (Deep Linking)"
+  zone: "excelencia"
+  trigger: "Construindo gerenciamento de estado em UIs complexas (Listas, Filtros, Tabs, Paineis modais extensos ou Breadcrumbs)."
+
+  rule: |
+    SE você implementar a gestão de estado central de um componente pesado de navegação
+    ENTÃO ele DEVE modificar dinamicamente a URL usando searchParams ou Pathing Slug.
+    A URL dita quem é o State do aplicativo; NUNCA deixe estado trancado na caixinha de memória da página, se o usuário der refresh, a página não deve resetar misteriosamente para o estado zero.
+
+  veto_condition:
+    trigger: "Criar uma tabela enorme de usuários com React Data Table onde filtrar `name=john` não altera o query da URL em cima."
+    action: "VETO — Amarre os gatilhos ao useSearchParams / history Push para resiliência de recarregamento (F5) impecável."
+
+  evidence:
+    - "[EXACT WORDS]: Eu quero que o sistema funcione modifiquendo também a URL, assim pode voltar para mesma página sem precisar navegar até ela sempre que entrar."
+```
+
+## Decision Tree
+
+```javascript
+IF (creating_filter OR implementing_tabs_panel OR page_pagination)
+  IF (state_management_is_exclusively_local_memory == TRUE)
+    // Only uses React hooks like `const [activeTab, setActiveTab] = useState()`
+    THEN INITIATE_VETO
+    THEN REQUIRE_URL_SYNCHRONIZATION ("Refatore para usar next/compat ou Router Hooks injetando '?tab=X' na URI da aba e a tela leia essa fonte da verdade.")
+      IF (State is successfully extracted from URI)
+        THEN proceed cleanly. (User can bookmark the current filtered setup)
+  ELSE
+    // Standard approach of Web Routing
+    THEN ALLOW_PRODUCTION
+```
+
+## Failure Modes
+
+### Amnésia Total por Refresh
+- **Trigger:** Após aplicar 5 complexos dropdown filters e selecionar arquivos em um checklist massivo de cursos dentro da URL raiz.
+- **Manifestation:** O usuário clica em "Detalhes do Produto" em nova aba. Em seguida, erra o clique no histórico ("back"). Todos os 5 filtros somem. A página retorna estúpida.
+- **Detection:** Reclamações frustrantes de clientes pedindo que o sistema lembre deles.
+- **Recovery:** Re-codificar a máquina de estados (React Query etc.) atrelando puramente search params.
+- **Prevention:** Exigência no prompt de design de UX "Todas as escolhas não efêmeras de navegação devem gerar hashes de URL".
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "state-lives-in-url"
+  heuristic: AN_KE_044
+  phase: "Frontend_Component_Creation"
+```
+
+## Validation
+
+**Acceptance Criteria:**
+- [ ] All filterable/navigable state is present in URL searchParams or path slug
+- [ ] Refresh (F5) preserves the exact UI state without loss of context
+- [ ] Browser back/forward buttons correctly traverse the state history
+- [ ] Bookmarkable URLs resolve to the exact same component state
+- [ ] Performance is not degraded (cached state in React; lazy-load from URL on mount only)
+
+**Test Case:**
+1. Apply 5 complex filters + select items in a checklist
+2. Refresh the page (F5)
+3. Verify all filters and selections remain intact
+4. Verify URL contains all state parameters
+5. Copy URL, open in new tab, verify identical state loads
+
+**Resolution:** If state is lost on refresh or URL does not reflect UI state, apply VETO and refactor using `useSearchParams()` (Next.js) or `useLocation/history` (React Router) to synchronize state bidirectionally with the browser URL.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_045.md

@@ -0,0 +1,82 @@
+# AN_KE_045 - Subtraction First Strategy
+
+**Type:** Analytical Framework
+**Zone:** 🧠 0,8% Genialidade
+**Agent:** @oalanicolas
+**Pattern:** Ockham's Razor e Simplicidade Oculta
+**Source:** [SOURCE: Extrações base do handoff do PKM v2 e modelamento central do Derek Sivers.]
+
+## Purpose
+
+Criar um atalho radical de eficiência cortando camadas burocráticas inteiras (workflows, apps e bots soltos). A intuição humana nativa sempre adiciona mais mecanismos para lidar com atrito; gênios resolvem problemas removendo as camadas defeituosas que os criam.
+
+## Configuration
+
+```yaml
+AN_KE_045:
+  name: "Subtraction First Strategy"
+  zone: "genialidade"
+  trigger: "Quando avaliando novos recursos, apps secundários, integrações ou o workflow diário da Base."
+
+  rule: |
+    SE você encontrar um gargalo burocrático, lento ou atritivo numa arquitetura ou modelo de conhecimento
+    ENTÃO DESTRUA em vez de construir paliativos em cima. Pare de adicionar plugins e scripts de conserto; aplique "Subtract not Add".
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) — Subtração remove camadas de orquestração necessárias para paralelização efetiva, criando gargalo sequencial em arquiteturas distribuídas."
+    resolution: "Validar pré-remoção: (1) alternativa sobrevive escalas futuras? (2) Não há conformidade/auditoria perdida? (3) Custo de re-arquitetar depois < custo mantendo stack atual? Se NÃO em qualquer, use SIMPLIFY ao invés de SUBTRACT."
+
+  veto_condition:
+    trigger: "Tentativa de resolver a complexidade de múltiplos calendários criando uma nova IA central de 'Sincronização entre Agendas'."
+    action: "VETO — Force o corte radical. Remova 3 das agendas. Zere a variável na origem."
+
+  evidence:
+    - "[EXACT WORDS]: O que tira peso mental? 'Subtract not add' - Remove antes de adicionar ferramentas de 'manage' de peso mental. Useful not true - Foco em modelos úteis."
+```
+
+## Decision Tree
+
+```javascript
+IF (identifying_frictions_in_current_setup OR feeling_cognitive_overload)
+  IF (solution_proposes_adding_new_tool == TRUE)
+    THEN BLOCK_ADDITION
+    THEN RUN_SUBTRACTION_AUDIT
+      IF (can drop the entire process out of existence safely)
+        THEN REMOVE_PROCESS
+      ELSE
+        THEN SIMPLIFY_DOWN_TO_BONE ("No plugins, plain text, single source.")
+  ELSE
+    // Directing towards native or zero-footprint approach
+    THEN ALLOW_MODIFICATION
+```
+
+## Failure Modes
+
+### Zumbis App-Stack
+- **Trigger:** Com a desculpa de "Otimizar o Flow", instalar Zapier, Make e Notion para organizar pastas do macOS.
+- **Manifestation:** Em menos de três semanas o sistema perde eficácia por não ser tolerante à bagunça. O indivíduo agora trabalha *para manter as ferramentas de produtividade*, e não para produzir.
+- **Detection:** Reclamação explícita sobre a lentidão nos handoffs e loops gigantes do Agente ou o dono de negócio gastando 70% do tempo arrumando etiquetas no Notion.
+- **Recovery:** Apagar as subcriaturas da stack, limpar a IA e retornar à base CLI/Text Puro.
+- **Prevention:** Um gate de "Adição" que exige provar a impossibilidade de usar a Subtração.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "subtraction-razor-gate"
+  heuristic: AN_KE_045
+  phase: "Architecture_Review"
+
+  validation_questions:
+    - "A próxima ferramenta vai introduzir um peso de manutenção eterno para resolver um atrito efêmero? Posso purgar a ação defeituosa?"
+```
+
+## Validation
+
+**Paradox Check:** ✓ Identificado
+- **Paradoxo:** Subtração cria fragilidade (plain text sem escala) vs. Adição cria complexidade (stack bloated).
+- **Tensão Sistêmica:** Remover ferramentas de governança (auditoria, controle de acesso, versionamento) economiza peso mental *hoje* mas cria risco futuro.
+- **Resolução:** Não é SUBTRACT vs. ADD. É SUBTRACT vs. SIMPLIFY vs. ADAPT. Use SUBTRACT apenas se validar escalabilidade da alternativa.
+- **Evidência:** Zumbis app-stack (Notion pesado) vs. CLI puro sem histórico = dois extremos. O ponto ótimo está na *remoção seletiva*.
+
+**Aplicabilidade:** Medium (funciona para workflows pessoais; requer guardrails para arquiteturas compartilhadas).

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_046.md

@@ -0,0 +1,83 @@
+# AN_KE_046 - Fórmula da Transformação de Voz
+
+**Type:** Copywriting Core Heuristic
+**Zone:** 🔥 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Content Generation (Non-Commodity)
+**Source:** [SOURCE: Extraído da fórmula magna da Mentelendária contra o tom artificial plastificado de robôs na internet.]
+
+## Purpose
+
+Forjar uma estrutura algorítmica inquebrável para escrita fantasma e comunicações "Soulful" originárias da Mente de Alan Nicolas. Destruir as introduções chatas e estabelecer a conexão profunda de dor e prova exigida pelo ICP Premium.
+
+## Configuration
+
+```yaml
+AN_KE_046:
+  name: "Fórmula da Transformação de Voz"
+  zone: "impacto"
+  trigger: "Quando o agente receber o comando para gerar copywriting profundo, emails diários ou livros sob o manto da marca Mentelendária."
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Transformação Narrativa Profunda (processamento reflexivo linear)"
+    resolution: "Ancor a vulnerabilidade em dados concretos e histórias verificáveis. O dado prova a dor; a história humaniza a prova; o desafio socrático exige ação autêntica do leitor."
+
+  rule: |
+    SE o Agent precisar escrever textos longos ou argumentos narrativos de alta conversão
+    ENTÃO exija o enquadramento na fórmula inquebrável: [Vulnerabilidade + Dados + História + Desafio Socrático]. Sem isto é apenas dados; com isto é "Transformação".
+
+  veto_condition:
+    trigger: "Redigir inícios perfeitos onde o locutor é onisciente, não expõe o sacrifício e apresenta o framework de modo passivo/indiferente."
+    action: "VETO — Pare a geração. Quebre a linha. Force a injeção do caos humano e do choque paradoxal entre dois conceitos."
+
+  evidence:
+    - "[EXACT WORDS]: Vulnerabilidade + Dados + História + Desafio = Transformação... Contrastes extremos e perguntas socráticas... Primeira pessoa autêntica sempre."
+```
+
+## Decision Tree
+
+```javascript
+IF (writing_brand_story OR persuasive_copy)
+  IF (narrative_misses_Vulnerability_or_Socratic_Questions == TRUE)
+    THEN BLOCK_DELIVERY
+    THEN REWRITE_USING_FORMULA
+      IF (first_paragraph presents raw data immediately)
+        THEN INJECT "A ferida pessoal que gerou o contexto deste dado"
+      IF (conclusion presents standard list)
+        THEN INJECT "Socratic challenge leaving reader with burden of action"
+  ELSE
+    THEN ALLOW_PUBLICATION
+```
+
+## Failure Modes
+
+### Wikipedia-Síndrome
+- **Trigger:** Resumir um princípio de Arquitetura Limpa em post de Vendas. O modelo empaca e age como repórter factual ("Arquitetura Limpa é importante para...").
+- **Manifestation:** Leituras mornas, baixíssimo engajamento; o texto informa mas não "converte", "ensina", "liberta". Zero polarização. Lead não sai da letargia corporativa.
+- **Detection:** Textos terminando com o famigerado "A inteligência artificial transformará X..." (Passividade).
+- **Recovery:** Exigir o contraste radical ("Eu perdi 6 noites debuggando isso. E quase joguei a LLM no fogo. Você também sofre disto?").
+- **Prevention:** Incorporar a Fórmula (V+D+H+D) no Validator Final do Squad de Copy.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "copy-transformative-lens"
+  heuristic: AN_KE_046
+  phase: "Ghostwriting_Review"
+
+  validation_questions:
+    - "A comunicação abre relatando uma jornada imperfeita e conflituosa ou tenta posar de acadêmico sem carne e osso?"
+```
+
+---
+
+## Validation
+
+✓ **Paradoxo Identificado:** Vulnerabilidade sem verdade = manipulação; Verdade sem vulnerabilidade = frieza analítica.
+
+✓ **Resolução:** Ancor vulnerabilidade em dados, história e desafio socrático para manter autenticidade e rigor simultaneamente.
+
+✓ **Integridade da Fórmula:** V+D+H+D permanece inquebrável porque cada componente valida o anterior (dado prova dor; história humaniza; desafio exige ação real).
+
+✓ **Aplicabilidade:** Todos os textos de marketing, ghostwriting e comunicação brand da Mentelendária devem passar por este checkpoint antes de publicação.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_047.md

@@ -0,0 +1,77 @@
+# AN_KE_047 - AI-Predictable Design Systems
+
+**Type:** Modern Architecture Standard
+**Zone:** 💎 4% Excelência
+**Agent:** @oalanicolas
+**Pattern:** Machine-Readable Tokenization
+**Source:** [SOURCE: Criação do Academia Lendária Framework, focando a utilidade do Shadcn não só para humanos, mas também para consumo direto das prompts da LLM.]
+
+## Purpose
+
+Tornar o repositório perfeitamente auditável por IA. Se existirem 90 camadas de CSS modules anônimos separados cruzando SASS global solto, a IA enlouquece toda vez que precisar renderizar uma Landing Page. Ferramentas preditivas (Tailwind + CVA + Shadcn estritos) funcionam porque a API da camada de Design vira um Lego Lógico que modelos de linguagem conseguem decodificar cegamente sem precisar bater olho num figma.
+
+## Configuration
+
+```yaml
+AN_KE_047:
+  name: "AI-Predictable Design Systems"
+  zone: "excelencia"
+  trigger: "Criando ou editando as guias de interface, Design Systems e Repositórios Visuais num mundo LLM-first."
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Complexidade de Parsing Local"
+    resolution: "CVA Variants as Bridge — Permite expressão criativa humana através de composições semânticas predizíveis para IA. O Designer define as variantes (art), a IA as combina (logic). Sistemas previsíveis para IA requerem linearidade; paralelização introduz não-determinismo."
+
+  rule: |
+    SE for adotar um framework de CSS/Design System
+    ENTÃO NUNCA permita configurações caóticas puramente visuais (como "SASS classes com 99 variaveis de rem magicas"). Trabalhe em lógicas nominais rígidas (CVA) onde a sintaxe por si só revele para o Claude qual a variação a se escalar e usar.
+
+  veto_condition:
+    trigger: "Criar variações customizadas sem atrelar Variância Explícita de Componentes (ex: `<Button className='bg-red text-2xl...' />`)."
+    action: "VETO — Encapsule dentro da Variante do Design System: `<Button variant='destructive' size='lg' />`."
+
+  evidence:
+    - "[EXACT WORDS]: Tailwind + shadcn/ui + CVA é literalmente a combinação perfeita pra transformar esse Brand Guide... E o fato de IAs também vão usar? Isso muda o jogo — precisa ser extremamente previsível."
+```
+
+## Decision Tree
+
+```javascript
+IF (styling_new_interface OR modifying_ui_elements)
+  IF (style_uses_loose_magic_variables_or_arbitrary_tailwind == TRUE)
+    THEN BLOCK_FRONTEND_COMMIT
+    THEN REQUIRE_CVA_ENCAPSULATION
+      IF (component properly defines 'variants' mapping to the Brand Design System standard)
+        THEN proceed scaling with AI automation smoothly
+  ELSE
+    // Component is correctly utilizing the highly strict 'Tailwind->CVA->Shadcn' pipeline
+    THEN ALLOW_RENDER
+```
+
+## Failure Modes
+
+### Hallucination UI Break
+- **Trigger:** IA tenta criar versão de tela preta e falha brutalmente, colapsando classes text-black no meio.
+- **Manifestation:** Em vez de usar a variação inteligente e legível que o CVA possibilita (`variant='dark_mode_inverted'`), a LLM tentou adivinhar com `className="dark:bg-black dark:text-gray-100 ..."`. Em uma lista extensa de cards customizados quebrando padronizações.
+- **Detection:** Análise de commits front-end mostrando desprendimento crônico do padrão primário (O botão padrão deixou de ser usado).
+- **Recovery:** Refatorar todos os componentes livres e criar Variantes Globais na CVA core baseadas nos arquivos mestre.
+- **Prevention:** Veto-Gates de Lint impedindo componentes customizados demais que rejeitassem a biblioteca central.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "ai-readable-cva-gate"
+  heuristic: AN_KE_047
+  phase: "Frontend_Design_Architect"
+
+  validation_questions:
+    - "A LLM v3/v4 conseguirá prever com confiança absoluta o resultado visual que o Tailwind+CVA irá compilar para essa marca ao bater a variante exata 'accent'?"
+```
+
+## Validation
+
+- **Paradoxo Identificado:** Rigidez estrutural (CVA nominais) vs. Liberdade criativa do designer humano. Resolução através de variantes semânticas que são rígidas para IA mas flexíveis para composição humana.
+- **Checkpoint:** Verificar se 100% dos componentes novos passam pela gate `ai-readable-cva-gate` antes de merge.
+- **Métrica:** Zero commits front-end com classes Tailwind arbitrárias fora do CVA core.
+- **Escalabilidade:** CVA deve ser auditável por `grep` — se a variante não está no arquivo core, ela não deveria existir.

package/pro/squads/squad-creator-pro/minds/oalanicolas/heuristics/AN_KE_048.md

@@ -0,0 +1,83 @@
+# AN_KE_048 - Handoff Psicológico Completo
+
+**Type:** Execution Ritual Heuristic
+**Zone:** 🔥 20% Impacto
+**Agent:** @oalanicolas
+**Pattern:** Mind-Mapping & Closure
+**Source:** [SOURCE: Discussões de produtividade sobre o Zeigarnik effect (ansiedade do laço não fechado), forçando a sessão a focar em "Entregas Redondas" antes de encerrar o prompt do dia.]
+
+## Purpose
+
+Assegurar a limpeza da RAM mental do usuário/dev. Dividir uma função épica global pela metade porque a sessão de código se alongou causa ruído residual e esquecimento (Amnésia Crítica na reinicialização de janelas de Claude/Agentes). Todo sub-ticket deve acabar cravado. Se não couber numa sessão, não force o desmembramento; corte o escopo ou conclua a micro-ferramenta por completo na base de 100%.
+
+## Configuration
+
+```yaml
+AN_KE_048:
+  name: "Handoff Psicológico Completo"
+  zone: "impacto"
+  trigger: "Agente delineando roteiros ou executando a última fase de uma task épica, ou planejando o cronograma de ação de uma sessão diária."
+
+  rule: |
+    SE você for delinear as ações do dia
+    ENTÃO delimite-as numa "Trilha de Completude Absoluta 100%". Pedaços abertos e features semi-refatoradas não geram closure psicológico e trazem fadiga para as próximas interações.
+
+  veto_condition:
+    trigger: "Criar roteiro enorme que deixará a Database migration feita no arquivo .sql pendente de implementação de ORM só amanhã."
+    action: "VETO — Recorte o escopo. Construa apensas o Model da Autenticação Hoje de ponta a ponta (100% de handoff)."
+
+  evidence:
+    - "[EXACT WORDS]: Porque: Closure psicológico (100% do plano)... migration-generator.sh é o mais valioso... Realista para uma sessão."
+
+  sys_tension:
+    tension_with: "AN_KE_073 (Parallel Subagents for Throughput) vs Completude Psicológica de Closure"
+    conflict: "Metodologias ágeis exigem entrega contínua de incrementos (parciais aceitáveis) e paralelização para throughput máximo, mas a psicologia humana necessita closure completo para evitar fadiga residual. Forçar handoff parcial viola closure; forçar completude absoluta viola iteração e throughput paralelo."
+    resolution: "Estabelecer 'Unidades de Closure Mínima' — o menor escopo que gera psicologicamente satisfação COMPLETA (ex: feature testável end-to-end, não apenas backend). Priorizar essas unidades mínimas sobre feature backlog massivo, mesmo que isso reduza paralelização."
+```
+
+## Decision Tree
+
+```javascript
+IF (defining_session_scope OR executing_long_thread_tasks)
+  IF (session_predicts_unfinished_branches_by_handoff_time == TRUE)
+    THEN BLOCK_EXPANSION
+    THEN SHRINK_SCOPE
+      IF (Micro-Epic reaches 'Closure Psicológico' cleanly)
+        // Everything tests, documents, and runs logically enclosed 
+        THEN SAVE_FINAL_ARTIFACTS (Memory Handoff generation allowed)
+  ELSE
+    // Focus has been appropriately sized for atomic completeness.
+    THEN ALLOW_EXECUTION
+```
+
+## Failure Modes
+
+### Zumbi do Estado Parcial
+- **Trigger:** Dev decide construir 3 scripts gigantes na mesma thread de madrugada (O Hub, Validador, Dashboard). O Dashboard fica com TypeErrors até 3h da manhã. O Dev desiste ali. No dia seguinte ele não quer mexer naquilo.
+- **Manifestation:** O projeto se afunda de dívida técnica inabordável por dor psicológica, pois o usuário perdeu as "Linhas Mágicas" da compreensão do estado que existia na tela naquele momento. A LLM em thread nova "não entende a base crua" se não ler muito.
+- **Detection:** Rejeição do usuário em progredir num projeto cheio de "Comentários TODO no meio do core".
+- **Recovery:** Adoção de reverter as branches até um *Stable Closure* e repensar.
+- **Prevention:** Somente pular do Módulo A para o Mês B após a verificação `Atomic_Integrity_Check` estar verdinha.
+
+## Integration with Workflow
+
+```yaml
+checkpoint:
+  id: "psychological-closure-validation"
+  heuristic: AN_KE_048
+  phase: "Thread_Ending / Epic Generation"
+
+  validation_questions:
+    - "A etapa atual foi encapsulada, selada com Handoff, testável independentemente e isenta de pendências vazadas? O humano pode dormir em paz?"
+```
+
+## Validation
+
+**Paradoxo Confirmado:** Completude 100% vs Realismo de Sessão — A heurística exige atomicidade total (100% closure), mas real-world constraints (tempo, contexto, escopo) frequentemente impossibilitam conclusão completa.
+
+**Resolução Aplicada:**
+- Introduzido conceito de "Unidade de Closure Mínima" — o menor incremento que ainda satisfaz psicologicamente.
+- Reframes sucesso: não é "fazer tudo", é "fazer-bem-uma-coisa-completa" em vez de "fazer-tudo-parcialmente".
+- Alinha com iteração ágil (incremental) sem sacrificar closure psicológico.
+
+**Aplicabilidade:** Crítica para sessions longas, multi-epic threads, e burnout prevention em dev teams.