aiox-core 5.0.2 → 5.0.3

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

@@ -0,0 +1,161 @@
+# AN_KE_005 - Determinism First
+
+**Type:** Method Selection Heuristic
+**Phase:** Any (Implementation)
+**Agent:** @oalanicolas
+**Pattern:** Code > LLM
+**Source:** CLAUDE.md - "Determinism First"
+
+## Purpose
+
+Priorizar soluções determinísticas sobre soluções baseadas em LLM. LLM só quando criatividade é genuinamente necessária.
+
+## Core Principle
+
+> "Script/código determinístico ← SEMPRE preferir"
+> "LLM como último recurso ← Só quando criatividade é necessária"
+> — CLAUDE.md Methodology
+
+## Prioritization Ladder
+
+```yaml
+priority_order:
+  1:
+    name: "Script/código determinístico"
+    when: "Lógica pode ser codificada"
+    cost: "$0, 100% reproduzível"
+    example: "Regex, loops, conditionals"
+
+  2:
+    name: "Query SQL direta"
+    when: "Dados estruturados"
+    cost: "$0, auditável"
+    example: "SELECT, JOIN, aggregations"
+
+  3:
+    name: "Regex/pattern matching"
+    when: "Texto com padrão previsível"
+    cost: "$0, reproduzível"
+    example: "Extract IDs, validate formats"
+
+  4:
+    name: "LLM"
+    when: "Criatividade genuinamente necessária"
+    cost: "$$, não-determinístico"
+    example: "Generate copy, summarize, creative writing"
+```
+
+## Configuration
+
+```yaml
+AN_KE_005:
+  name: "Determinism First"
+  phase: "any"
+  agent: "@oalanicolas"
+
+  decision_tree:
+    - question: "Pode ser codificado com lógica simples?"
+      if_yes: "Use código determinístico"
+      if_no: "Continue"
+
+    - question: "Dados estão em banco estruturado?"
+      if_yes: "Use SQL query"
+      if_no: "Continue"
+
+    - question: "Texto tem padrão previsível?"
+      if_yes: "Use regex/pattern matching"
+      if_no: "Continue"
+
+    - question: "Requer criatividade ou julgamento subjetivo?"
+      if_yes: "Use LLM (justified)"
+      if_no: "Reavaliar - provavelmente não precisa de LLM"
+
+  veto_conditions:
+    - condition: "llm_when_code_suffices"
+      action: "VETO - Use deterministic solution"
+      maps_to: "AN_VC_007"
+
+  cost_comparison:
+    deterministic:
+      token_cost: 0
+      reproducibility: 100%
+      auditability: "Full"
+    llm:
+      token_cost: "500-5000 per call"
+      reproducibility: "~70-90%"
+      auditability: "Limited"
+```
+
+## Decision Matrix
+
+| Task Type | Deterministic? | Recommended Approach |
+|-----------|----------------|---------------------|
+| Extract ID from text | Yes | Regex |
+| Validate email format | Yes | Regex |
+| Sum/aggregate data | Yes | SQL |
+| Filter by criteria | Yes | SQL/code |
+| Generate creative copy | No | LLM |
+| Summarize long text | No | LLM |
+| Answer open question | No | LLM |
+| Transform data format | Yes | Code |
+
+## ETL First Sub-Pattern
+
+```yaml
+etl_first:
+  principle: "NEVER use WebFetch when ETL fetch-page.js can do the job"
+
+  comparison:
+    etl_fetch:
+      command: "node infrastructure/services/etl/bin/fetch-page.js <url>"
+      cost: "$0"
+      output: "Clean markdown"
+    web_fetch:
+      cost: "~500-2K tokens/page"
+      when: "ONLY when LLM reasoning needed IN the fetch step"
+
+  flow: "WebSearch (find URLs) → fetch-page.js (get content) → LLM (only if needed)"
+```
+
+## Validation Questions
+
+1. "Pode ser feito com código simples?"
+2. "Pode ser uma query SQL?"
+3. "Pode ser um regex?"
+4. "Criatividade é GENUINAMENTE necessária?"
+5. "Justifiquei o uso de LLM?"
+
+## Anti-Patterns
+
+```yaml
+anti_patterns:
+  - name: "LLM for Everything"
+    symptom: "Usar LLM pra tarefas que código resolve"
+    cost: "Tokens desperdiçados, resultados inconsistentes"
+    fix: "Perguntar 'Pode ser código?' primeiro"
+
+  - name: "WebFetch for Reading"
+    symptom: "Usar WebFetch só pra ler página"
+    cost: "500-2K tokens por página"
+    fix: "Usar fetch-page.js via Bash"
+
+  - name: "Prompt Engineering over Code"
+    symptom: "Prompt elaborado pra tarefa determinística"
+    cost: "Fragilidade, não-reprodutibilidade"
+    fix: "Código > prompt sempre que possível"
+```
+
+## Performance Metrics
+
+```yaml
+performance:
+  token_savings: "60-80% when following ladder"
+  reproducibility_improvement: "70% → 100% for deterministic"
+  debugging_time_reduction: "~50% (deterministic is traceable)"
+```
+
+---
+
+**Pattern Compliance:** Code > LLM
+**Veto Mapping:** AN_VC_007 (LLM When Code Suffices)
+**Integration:** All implementation phases

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

@@ -0,0 +1,166 @@
+# AN_KE_006 - Verification First
+
+**Type:** Debugging Heuristic
+**Phase:** Any (Validation)
+**Agent:** @oalanicolas
+**Pattern:** Physical > Theory
+**Source:** CLAUDE.md - "VERIFY PHYSICALLY BEFORE THEORIZING"
+
+## Purpose
+
+Verificar fisicamente ANTES de teorizar. Elimina horas de debugging por suposições erradas.
+
+## Core Principle
+
+> "GOLDEN RULE: VERIFY PHYSICALLY BEFORE THEORIZING"
+> — CLAUDE.md Debugging First Principles
+
+Suposição é o pai de todos os bugs.
+
+## Verification Checklist
+
+```yaml
+verification_order:
+  1:
+    question: "📁 File exists where code expects?"
+    command: "ls -la /exact/path/"
+    common_issue: "Path typo, wrong directory"
+
+  2:
+    question: "🌐 Server serves it?"
+    command: "curl -I http://localhost:PORT/path"
+    common_issue: "Server not running, wrong port"
+
+  3:
+    question: "👂 User repeated input 2x?"
+    action: "STOP, do EXACTLY what they said"
+    common_issue: "Misunderstood requirement"
+
+  4:
+    question: "✅ Tested with hard refresh?"
+    command: "Cmd+Shift+R (clear cache)"
+    common_issue: "Browser cache, stale assets"
+
+  5:
+    question: "🔍 Checked actual error message?"
+    action: "Read FULL error, not just first line"
+    common_issue: "Root cause buried in stack trace"
+```
+
+## Configuration
+
+```yaml
+AN_KE_006:
+  name: "Verification First"
+  phase: "any"
+  agent: "@oalanicolas"
+
+  principle: "Physical verification BEFORE theoretical debugging"
+
+  verification_commands:
+    file_exists: "ls -la {path}"
+    server_responds: "curl -I {url}"
+    process_running: "ps aux | grep {process}"
+    port_listening: "lsof -i :{port}"
+    env_set: "echo ${VAR_NAME}"
+    db_connected: "psql -c 'SELECT 1'"
+
+  decision_tree:
+    - step: "Verify physical state"
+      before: "ANY theoretical debugging"
+    - step: "If physical state wrong"
+      action: "Fix physical state first"
+    - step: "If physical state correct"
+      action: "Then investigate logic"
+
+  veto_conditions:
+    - condition: "debug_without_verification"
+      action: "VETO - Verify physically first"
+      maps_to: "AN_VC_007"
+    - condition: "assume_without_checking"
+      action: "VETO - Check, don't assume"
+      maps_to: "AN_VC_007"
+```
+
+## Decision Tree
+
+```
+BEFORE any debugging:
+
+1. ls -la {path}
+   IF file doesn't exist → FIX PATH
+   IF file exists → CONTINUE
+
+2. curl -I {url}
+   IF server doesn't respond → FIX SERVER
+   IF server responds → CONTINUE
+
+3. Check if user repeated 2x
+   IF yes → STOP, do EXACTLY what they said
+   IF no → CONTINUE
+
+4. Hard refresh (Cmd+Shift+R)
+   IF problem disappears → WAS CACHE
+   IF problem persists → CONTINUE
+
+5. NOW investigate logic
+```
+
+## Common Verification Scenarios
+
+| Symptom | First Check | Common Cause |
+|---------|-------------|--------------|
+| "File not found" | `ls -la` | Wrong path, typo |
+| "Connection refused" | `curl -I` | Server not running |
+| "Not working" (vague) | Ask user to repeat | Misunderstood requirement |
+| "Still showing old" | Hard refresh | Browser cache |
+| "Env var undefined" | `echo $VAR` | Not exported, wrong shell |
+| "DB error" | `psql -c 'SELECT 1'` | Connection, credentials |
+
+## Anti-Patterns
+
+```yaml
+anti_patterns:
+  - name: "Theory First"
+    symptom: "Debuggar código antes de verificar se arquivo existe"
+    cost: "Horas perdidas em suposição errada"
+    fix: "ls -la PRIMEIRO"
+
+  - name: "Assume Server Running"
+    symptom: "Testar endpoint sem verificar se servidor tá up"
+    cost: "Confusão, false debugging"
+    fix: "curl -I PRIMEIRO"
+
+  - name: "Ignore User Repetition"
+    symptom: "Usuário repetiu 2x e você continuou no caminho errado"
+    cost: "Retrabalho, frustração"
+    fix: "STOP, releia, faça EXATAMENTE o que pediu"
+
+  - name: "Skip Cache Clear"
+    symptom: "Assume que mudança não funcionou sem hard refresh"
+    cost: "False negatives"
+    fix: "Cmd+Shift+R SEMPRE após mudança de frontend"
+```
+
+## Validation Questions
+
+1. "Verifiquei fisicamente que o arquivo existe?"
+2. "Verifiquei que o servidor responde?"
+3. "Usuário repetiu algo 2x?"
+4. "Fiz hard refresh?"
+5. "Li o erro COMPLETO?"
+
+## Performance Metrics
+
+```yaml
+performance:
+  debugging_time_saved: "~60% when following order"
+  false_assumptions_caught: "~80%"
+  user_frustration_reduced: "High (stop ignoring 2x)"
+```
+
+---
+
+**Pattern Compliance:** Physical > Theory
+**Veto Mapping:** AN_VC_007 (Debug Without Verification)
+**Integration:** All debugging/validation scenarios

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

@@ -0,0 +1,190 @@
+# AN_KE_007 - REUSE > CREATE
+
+**Type:** Creation Heuristic
+**Phase:** 0 (Discovery)
+**Agent:** @oalanicolas
+**Pattern:** Check Existing First
+**Source:** CLAUDE.md - "Check squads/ and existing components before creating new"
+
+## Purpose
+
+SEMPRE verificar se algo similar existe antes de criar novo. Evita duplicação, mantém consistência, aproveita trabalho validado.
+
+## Core Principle
+
+> "Check squads/ and existing components before creating new"
+> "Create from scratch when similar exists" → NEVER
+> — CLAUDE.md Alan's Personal Rules
+
+## Search Locations
+
+```yaml
+search_order:
+  1:
+    location: "squads/"
+    what: "Similar agents, tasks, workflows"
+    command: "find squads/ -name '*{keyword}*'"
+
+  2:
+    location: ".claude/agents/"
+    what: "Existing agent definitions"
+    command: "ls .claude/agents/*.md"
+
+  3:
+    location: ".claude/skills/"
+    what: "Existing skills"
+    command: "find .claude/skills/ -name 'SKILL.md'"
+
+  4:
+    location: "app/components/"
+    what: "UI components"
+    command: "find app/components/ -name '*.tsx'"
+
+  5:
+    location: "docs/"
+    what: "Documentation, templates"
+    command: "find docs/ -name '*{keyword}*'"
+```
+
+## Configuration
+
+```yaml
+AN_KE_007:
+  name: "REUSE > CREATE"
+  phase: 0
+  agent: "@oalanicolas"
+
+  decision_matrix:
+    - similarity: ">= 80%"
+      action: "REUSE - Use existing directly"
+      justification_required: false
+
+    - similarity: "50-79%"
+      action: "ADAPT - Fork and modify existing"
+      justification_required: true
+
+    - similarity: "20-49%"
+      action: "REFERENCE - Use as template/inspiration"
+      justification_required: true
+
+    - similarity: "< 20%"
+      action: "CREATE - New, but document why"
+      justification_required: true
+
+  veto_conditions:
+    - condition: "create_without_search"
+      action: "VETO - Search first"
+      maps_to: "AN_VC_006"
+    - condition: "create_when_80_percent_exists"
+      action: "VETO - Use existing"
+      maps_to: "AN_VC_006"
+
+  output:
+    type: "decision"
+    values: ["REUSE", "ADAPT", "REFERENCE", "CREATE"]
+```
+
+## Decision Tree
+
+```
+STEP 1: Search all locations
+  → Document findings
+
+STEP 2: Calculate similarity
+  IF >= 80% similar exists
+    THEN REUSE → Use existing, don't create
+
+  ELSE IF 50-79% similar exists
+    THEN ADAPT → Fork existing, modify
+    REQUIRE justification for changes
+
+  ELSE IF 20-49% similar exists
+    THEN REFERENCE → Use as template
+    REQUIRE justification for new approach
+
+  ELSE IF < 20% similar exists
+    THEN CREATE → New creation justified
+    REQUIRE documentation of search performed
+
+TERMINATION: Always document search + decision
+```
+
+## Similarity Assessment
+
+| Aspect | Weight | How to Assess |
+|--------|--------|---------------|
+| Purpose/intent | 0.3 | Same goal? |
+| Structure | 0.2 | Same architecture? |
+| Components | 0.2 | Same building blocks? |
+| Interface | 0.15 | Same inputs/outputs? |
+| Domain | 0.15 | Same context? |
+
+## Before Creating Anything
+
+```yaml
+checklist:
+  - question: "Does something similar exist in squads/?"
+    action: "find squads/ -name '*keyword*'"
+
+  - question: "Does an agent already do this?"
+    action: "grep -r 'purpose' .claude/agents/*.md"
+
+  - question: "Is there a skill for this?"
+    action: "find .claude/skills/ -name 'SKILL.md' | xargs grep keyword"
+
+  - question: "Is there a component for this?"
+    action: "find app/components/ -name '*.tsx' | xargs grep keyword"
+
+  - question: "Did I document what I found?"
+    action: "List findings before proposing"
+```
+
+## Anti-Patterns
+
+```yaml
+anti_patterns:
+  - name: "NIH Syndrome (Not Invented Here)"
+    symptom: "Criar novo quando existente funciona"
+    cost: "Duplicação, inconsistência, manutenção"
+    fix: "REUSE existing unless genuinely inadequate"
+
+  - name: "Shallow Search"
+    symptom: "Olhou só um lugar e disse 'não existe'"
+    cost: "Duplicação por ignorância"
+    fix: "Search ALL locations in checklist"
+
+  - name: "Create First, Search Later"
+    symptom: "Descobrir existente depois de criar"
+    cost: "Trabalho jogado fora"
+    fix: "ALWAYS search before proposing creation"
+
+  - name: "Over-Customization"
+    symptom: "Adaptar muito quando existente serve"
+    cost: "Fork desnecessário, manutenção dupla"
+    fix: "Prefer REUSE over ADAPT when possible"
+```
+
+## Validation Questions
+
+1. "Pesquisei em squads/?"
+2. "Pesquisei em .claude/agents/?"
+3. "Pesquisei em .claude/skills/?"
+4. "Pesquisei em app/components/?"
+5. "Documentei o que encontrei?"
+6. "Justifiquei a decisão?"
+
+## Performance Metrics
+
+```yaml
+performance:
+  search_time: "5-10 min"
+  duplication_avoided: "~60% of proposals use existing"
+  consistency_improvement: "High (same patterns reused)"
+  maintenance_reduction: "~40% (fewer unique implementations)"
+```
+
+---
+
+**Pattern Compliance:** REUSE > CREATE
+**Veto Mapping:** AN_VC_006 (Create Without Discovery)
+**Integration:** Phase 0 of any creation workflow

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

@@ -0,0 +1,191 @@
+# AN_KE_008 - Pattern Recognition (2x Rule)
+
+**Type:** Learning Heuristic
+**Phase:** Any (Continuous)
+**Agent:** @oalanicolas
+**Pattern:** Repetition = Rule
+**Source:** CLAUDE.md - "Se Disse 2x → Vira Regra"
+
+## Purpose
+
+Identificar padrões através de repetição. Se algo foi corrigido/dito 2x, é um padrão que precisa virar regra documentada.
+
+## Core Principle
+
+> "Se Disse 2x → Vira Regra"
+> "Correção repetida = regra faltando no CLAUDE.md"
+> "Ação: Adicionar imediatamente após identificar padrão"
+> — CLAUDE.md META-RULES
+
+## The 2x Rule
+
+```yaml
+rule:
+  trigger: "User corrects/repeats same thing twice"
+  meaning: "Pattern identified, rule needed"
+  action: "Document as rule IMMEDIATELY"
+
+  examples:
+    - correction: "Não use mock data" (2x)
+      rule_created: "NEVER: Use mock data when real data exists"
+
+    - correction: "Verifique se existe" (2x)
+      rule_created: "ALWAYS: Check squads/ before creating new"
+
+    - correction: "Não delete sem perguntar" (2x)
+      rule_created: "NEVER: Delete without asking first"
+```
+
+## Configuration
+
+```yaml
+AN_KE_008:
+  name: "Pattern Recognition (2x Rule)"
+  phase: "continuous"
+  agent: "@oalanicolas"
+
+  detection:
+    trigger: "same_correction_twice"
+    confidence: "100% - if corrected 2x, it's a pattern"
+
+  action_pipeline:
+    - step: 1
+      action: "Recognize repetition"
+      question: "User said/corrected this before?"
+
+    - step: 2
+      action: "Extract pattern"
+      question: "What is the underlying rule?"
+
+    - step: 3
+      action: "Document immediately"
+      location: "CLAUDE.md or relevant config"
+
+    - step: 4
+      action: "Confirm with user"
+      question: "Added rule X. Correct?"
+
+  veto_conditions:
+    - condition: "ignore_repeated_correction"
+      action: "VETO - Document as rule now"
+      maps_to: "AN_VC_008"
+```
+
+## Pattern Categories
+
+| Category | Example Trigger | Rule Format |
+|----------|-----------------|-------------|
+| NEVER | "Don't do X" (2x) | NEVER: X |
+| ALWAYS | "Always do Y" (2x) | ALWAYS: Y |
+| IF/THEN | "When Z, do W" (2x) | IF Z → THEN W |
+| PRIORITY | "A before B" (2x) | PRIORITY: A > B |
+| VETO | "Stop if X" (2x) | VETO: X → STOP |
+
+## Decision Tree
+
+```
+ON receiving feedback/correction:
+
+1. Check: "Did user say/correct this before?"
+   IF no → Note it, continue
+   IF yes → PATTERN DETECTED
+
+2. On pattern detection:
+   → STOP current work
+   → Extract the rule
+   → Document IMMEDIATELY
+   → Confirm with user
+   → Continue with rule applied
+
+3. Rule documentation format:
+   - Clear trigger
+   - Specific action
+   - Category (NEVER/ALWAYS/IF-THEN/PRIORITY/VETO)
+```
+
+## Extraction Template
+
+```yaml
+pattern_extraction:
+  observation: "User said/corrected X twice"
+
+  analysis:
+    what_was_wrong: ""
+    what_should_happen: ""
+    underlying_principle: ""
+
+  rule_format:
+    category: "NEVER | ALWAYS | IF-THEN | PRIORITY | VETO"
+    trigger: "When this happens..."
+    action: "Do this..."
+
+  documentation:
+    location: "CLAUDE.md section"
+    format: "| Phrase | Meaning | Action |"
+```
+
+## Anti-Patterns
+
+```yaml
+anti_patterns:
+  - name: "Ignore Repetition"
+    symptom: "User corrigiu 2x e você não documentou"
+    cost: "Vai errar de novo, frustração"
+    fix: "STOP, document rule, then continue"
+
+  - name: "Vague Rule"
+    symptom: "Documentar regra genérica demais"
+    cost: "Não previne o erro específico"
+    fix: "Be specific: trigger + action"
+
+  - name: "Delay Documentation"
+    symptom: "Pensar 'vou documentar depois'"
+    cost: "Esquece, erra de novo"
+    fix: "Document IMMEDIATELY"
+
+  - name: "Wrong Location"
+    symptom: "Documentar em lugar que ninguém lê"
+    cost: "Regra existe mas não é aplicada"
+    fix: "CLAUDE.md or relevant active config"
+```
+
+## Validation Questions
+
+1. "User já disse isso antes?"
+2. "Se sim, qual é o padrão?"
+3. "Documentei a regra?"
+4. "Regra está em lugar visível?"
+5. "Confirmei com user?"
+
+## Performance Metrics
+
+```yaml
+performance:
+  pattern_detection_rate: "100% for 2x occurrences"
+  documentation_speed: "< 5 min after detection"
+  error_recurrence: "~0% after rule documented"
+  user_satisfaction: "High (feeling heard)"
+```
+
+## Integration with CLAUDE.md
+
+```yaml
+integration:
+  target_sections:
+    - "### NEVER" (for prohibited patterns)
+    - "### ALWAYS" (for required patterns)
+    - "### IF HE SAYS → IT MEANS" (for interpretation patterns)
+    - "### PRIORITIES" (for ordering patterns)
+
+  format_examples:
+    never: "- Never do X when Y"
+    always: "- Always do A before B"
+    if_then: "| Phrase | Meaning | Action |"
+    priority: "1. X → 2. Y → 3. Z"
+```
+
+---
+
+**Pattern Compliance:** Repetition = Rule
+**Veto Mapping:** AN_VC_008 (Ignore Repeated Correction)
+**Integration:** Continuous learning across all phases