aiox-core 5.0.2 → 5.0.4

package/pro/squads/squad-creator-pro/data/decision-heuristics-framework.md

@@ -0,0 +1,620 @@
+# Decision Heuristics Framework
+
+> **Version:** 1.0.0
+> **Source:** AIOS Quality Standards
+
+Framework for creating decision heuristics that validate choices at workflow checkpoints.
+
+---
+
+## 1. Heuristic Anatomy
+
+Every decision heuristic must have this structure:
+
+```yaml
+heuristic:
+  id: "{PREFIX}_{AREA}_{NUMBER}"  # e.g., "QA_STR_001"
+  name: "Human-readable name"
+  type: "Decision Heuristic"
+  phase: 1-N                      # Which workflow phase
+  agent: "@squad:agent-name"      # Which agent applies it
+
+  # Weighted criteria
+  weights:
+    criterion_1: 0.9              # 0.0 to 1.0
+    criterion_2: 0.8
+    criterion_3: 0.7
+
+  # Minimum thresholds for pass
+  thresholds:
+    criterion_1: 0.8              # Must score >= this
+    criterion_2: 0.7
+    criterion_3: null             # Context-dependent
+
+  # Conditions that BLOCK progress
+  veto_conditions:
+    - condition: "criterion_1 < 0.7"
+      action: "VETO - Return to previous phase"
+    - condition: "critical_check = false"
+      action: "VETO - Cannot proceed"
+
+  # What to do when veto triggers
+  feedback_on_failure:
+    - "Specific remediation step 1"
+    - "Specific remediation step 2"
+
+  # Output decision
+  output:
+    type: "decision"
+    values: ["APPROVE", "REVIEW", "VETO"]
+```
+
+---
+
+## 2. Decision Tree Structure
+
+Every heuristic needs a decision tree:
+
+```
+PRIMARY BRANCH (highest priority):
+  IF (critical_condition_violated)
+    THEN VETO → immediate action
+
+SECONDARY BRANCH:
+  ELSE IF (important_condition < threshold)
+    THEN REVIEW → requires justification
+
+TERTIARY BRANCH:
+  ELSE IF (optional_condition < threshold)
+    THEN APPROVE with conditions
+
+TERMINATION: Define when to stop evaluating
+FALLBACK: What to do in edge cases
+```
+
+---
+
+## 3. Standard Heuristic Templates
+
+### 3.1 Strategic Alignment Heuristic
+
+**Purpose:** Validate that actions align with vision/goals.
+
+```yaml
+strategic_alignment:
+  id: "{PREFIX}_STR_001"
+  name: "Strategic Alignment Check"
+  phase: "early (architecture/planning)"
+
+  weights:
+    vision_clarity: 0.9
+    goal_alignment: 0.8
+    resource_efficiency: 0.7
+
+  thresholds:
+    vision_clarity: 0.8
+    goal_alignment: 0.7
+    resource_efficiency: 0.5
+
+  veto_conditions:
+    - condition: "vision_clarity < 0.7"
+      action: "VETO - Vision unclear, return to Discovery"
+
+  decision_tree: |
+    IF (action directly enables vision)
+      THEN priority = HIGH → APPROVE
+    ELSE IF (action creates optionality towards vision)
+      THEN priority = MEDIUM → APPROVE with conditions
+    ELSE IF (action does not serve vision)
+      THEN REVIEW - requires justification
+    TERMINATION: Action contradicts vision
+```
+
+### 3.2 Coherence Scan Heuristic
+
+**Purpose:** Validate executor/resource fit.
+
+```yaml
+coherence_scan:
+  id: "{PREFIX}_COH_001"
+  name: "Coherence Validation"
+  phase: "mid (executor assignment)"
+
+  weights:
+    consistency: 1.0           # VETO power
+    system_fit: 0.8
+    capability: 0.3
+
+  thresholds:
+    consistency: 0.7           # Must be coherent
+    system_fit: 0.7
+    capability: null           # Context-dependent
+
+  veto_conditions:
+    - condition: "consistency < 0.7"
+      action: "VETO - Reassign executor"
+    - condition: "detected_incoherence = true"
+      action: "VETO - Trust violation"
+
+  decision_tree: |
+    PRIMARY:
+      IF (consistency == 'Incoherent')
+        THEN REJECT immediately → VETO
+    SECONDARY:
+      ELSE IF (system_fit < 0.7)
+        THEN FLAG for observation → REVIEW
+    TERTIARY:
+      ELSE IF (capability < required)
+        THEN Consider training → REVIEW with conditions
+```
+
+### 3.3 Automation Decision Heuristic
+
+**Purpose:** Decide when to automate vs keep manual.
+
+```yaml
+automation_decision:
+  id: "{PREFIX}_AUT_001"
+  name: "Automation Tipping Point"
+  phase: "mid (workflow design)"
+
+  weights:
+    frequency: 0.7
+    impact: 0.9
+    automatability: 0.8
+    guardrails_present: 1.0    # VETO power
+
+  thresholds:
+    frequency: "2x per month"
+    impact: 0.6
+    automatability: 0.5
+    standardization: 0.7
+
+  veto_conditions:
+    - condition: "guardrails_missing = true"
+      action: "VETO - Define safety guardrails first"
+
+  decision_tree: |
+    IF (automatability > 0.5 AND guardrails_present)
+      THEN AUTOMATE
+    ELSE IF (impact > 0.6)
+      THEN KEEP_MANUAL (needs human judgment)
+    ELSE IF (frequency < 1x/month AND impact < 0.5)
+      THEN ELIMINATE
+    CONSTRAINT: NEVER automate without guardrails
+
+  automation_rules:
+    - trigger: "Task repeated 2+ times"
+      action: "Document and automate"
+    - trigger: "Task repeated 3+ times without automation"
+      assessment: "Design failure - immediate remediation"
+    - trigger: "Any automation"
+      requirement: "Must have guardrails, logs, manual escape"
+```
+
+---
+
+## 4. Evaluation Criteria Table
+
+Standard format for documenting criteria:
+
+| Criterion | Weight | Threshold | VETO Power | Description |
+|-----------|--------|-----------|------------|-------------|
+| criterion_1 | 0.9 | ≥0.8 | YES | What it measures |
+| criterion_2 | 0.8 | ≥0.7 | NO | What it measures |
+| criterion_3 | 0.7 | Context | NO | What it measures |
+
+---
+
+## 5. Failure Modes Documentation
+
+Every heuristic should document failure modes:
+
+```yaml
+failure_modes:
+  - name: "False Positive"
+    trigger: "What causes false approval"
+    manifestation: "What happens when it fails"
+    detection: "How to detect the failure"
+    recovery: "How to fix it"
+    prevention: "How to prevent it"
+
+  - name: "False Negative"
+    trigger: "What causes false rejection"
+    manifestation: "What happens"
+    detection: "How to detect"
+    recovery: "How to fix"
+    prevention: "How to prevent"
+```
+
+---
+
+## 6. Checkpoint Integration
+
+Heuristics integrate with workflow checkpoints:
+
+```yaml
+checkpoint:
+  id: "checkpoint-name"
+  heuristic: "{PREFIX}_{AREA}_{NUMBER}"
+  phase: N
+
+  criteria:
+    - metric: "metric_name"
+      threshold: 0.8
+      operator: ">="
+    - metric: "another_metric"
+      threshold: 0.7
+      operator: ">="
+
+  veto_conditions:
+    - condition: "condition_expression"
+      action: "HALT - Reason"
+
+  validation_questions:
+    - "Question to verify criterion 1?"
+    - "Question to verify criterion 2?"
+
+  pass_action: "Proceed to Phase N+1"
+  fail_action: "Return to Phase N-1 with feedback"
+```
+
+---
+
+## 7. Performance Metrics
+
+Track heuristic performance:
+
+```yaml
+performance:
+  decision_speed: "Time to make decision"
+  accuracy_rate: "Percentage of correct decisions"
+  confidence_level: "Confidence in decisions"
+  resource_efficiency: "0-10 scale"
+  context_sensitivity: "0-10 scale"
+```
+
+---
+
+## 8. Creating Custom Heuristics
+
+### Step 1: Identify the Decision Point
+
+- What decision needs to be made?
+- At which workflow phase?
+- Who/what makes the decision?
+
+### Step 2: Define Criteria
+
+- What factors matter?
+- How important is each (weights)?
+- What's the minimum acceptable (thresholds)?
+
+### Step 3: Define Veto Conditions
+
+- What absolutely cannot happen?
+- What triggers immediate rejection?
+
+### Step 4: Build Decision Tree
+
+- Primary branch (highest priority)
+- Secondary branches
+- Termination conditions
+- Fallback behavior
+
+### Step 5: Document Failure Modes
+
+- What could go wrong?
+- How to detect and recover?
+
+### Step 6: Integrate with Checkpoint
+
+- Which checkpoint uses this?
+- What validation questions?
+
+---
+
+## 9. Quality Gate Pattern
+
+Heuristics work within quality gates:
+
+```
+┌─────────────────────────────────────────┐
+│  QUALITY GATE                           │
+├─────────────────────────────────────────┤
+│  1. Evaluate criteria against thresholds│
+│  2. Check veto conditions               │
+│  3. Apply decision tree                 │
+│  4. Output: APPROVE | REVIEW | VETO     │
+└─────────────────────────────────────────┘
+          │
+          ▼
+┌─────────────────────────────────────────┐
+│  IF APPROVE: Proceed to next phase      │
+│  IF REVIEW: Human intervention needed   │
+│  IF VETO: Return to previous phase      │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 10. Scope Complexity Heuristic (PRD Gate)
+
+**Purpose:** Decide if scope is too large for direct squad creation → requires PRD with Epics/Stories.
+
+### 10.1 The Problem
+
+Large-scope squads created "on the fly" result in:
+- Incomplete coverage (workflows missed)
+- Poor prioritization (no roadmap)
+- Technical debt (rushing to create many agents)
+- Lost context (too much to track in conversation)
+
+### 10.2 Scope Complexity Decision
+
+```yaml
+scope_complexity_heuristic:
+  id: "SC_SCP_001"
+  name: "Scope Complexity Gate"
+  phase: "phase_0 (Discovery)"
+  blocking: true
+
+  thresholds:
+    workflows_mapped: 10       # >= 10 workflows = PRD required
+    agents_needed: 8           # >= 8 agents = PRD required
+    domain_precedent: false    # No similar squad exists = higher risk
+
+  decision_tree: |
+    PRIMARY CHECK - Workflow Count:
+      IF (workflows_mapped >= 10)
+        THEN → STOP: "Escopo grande demais para criação direta"
+               → ACTION: Create PRD with Epics/Stories
+               → VETO: Cannot proceed with direct squad creation
+
+    SECONDARY CHECK - Agent Count:
+      ELSE IF (agents_needed >= 8)
+        THEN → STOP: "Muitos agents para criar sem roadmap"
+               → ACTION: Create PRD with phased implementation
+               → VETO: Cannot proceed without planning
+
+    TERTIARY CHECK - Domain Precedent:
+      ELSE IF (no_similar_squad AND workflows >= 5)
+        THEN → WARNING: "Domínio novo sem precedente"
+               → RECOMMEND: Consider PRD for risk mitigation
+               → ALLOW: User can override
+
+    DEFAULT:
+      ELSE → PROCEED with direct squad creation
+
+  veto_conditions:
+    - condition: "workflows_mapped >= 10"
+      action: "VETO - PRD obrigatório"
+      message: |
+        ❌ ESCOPO GRANDE DEMAIS
+
+        Mapeei {n} workflows. Isso é complexo demais para criar diretamente.
+
+        AÇÃO NECESSÁRIA:
+        1. Criar PRD em docs/projects/{domain}/prd.md
+        2. Dividir em Epics (ex: "Tier 0 - Onboarding", "Tier 1 - Execução")
+        3. Criar Stories por Epic
+        4. Implementar por fases
+
+        Quer que eu crie o PRD agora?
+
+    - condition: "agents_needed >= 8"
+      action: "VETO - Roadmap obrigatório"
+      message: "Precisa de roadmap de implementação para {n} agents"
+
+  rationale: |
+    PRD para squads grandes garante:
+    - Todos os workflows são documentados antes de começar
+    - Dependências entre agents são mapeadas
+    - Priorização clara (o que criar primeiro)
+    - Checkpoints de validação por Epic
+    - Possibilidade de implementação incremental
+```
+
+### 10.3 PRD Structure for Large Squads
+
+```yaml
+prd_structure:
+  location: "docs/projects/{domain}/prd.md"
+
+  required_sections:
+    - overview: "O que o squad faz, para quem"
+    - workflows_mapped: "Lista completa de workflows (tabela)"
+    - agents_architecture: "Tier distribution, handoffs"
+    - epics: "Agrupamento lógico de trabalho"
+    - success_criteria: "Como medir se está pronto"
+
+  epic_structure:
+    - epic_1: "Infraestrutura e Orquestrador"
+    - epic_2: "Tier 0 - Diagnóstico/Onboarding"
+    - epic_3: "Tier 1 - Execução Core"
+    - epic_4: "Tier 2 - Comunicação/Consultoria"
+    - epic_5: "Tier 3 - Especialistas"
+    - epic_6: "Integração e Automação"
+
+  story_format: |
+    ## Story: {título}
+
+    **Como** {persona}
+    **Quero** {funcionalidade}
+    **Para** {benefício}
+
+    ### Acceptance Criteria
+    - [ ] {criterio_1}
+    - [ ] {criterio_2}
+
+    ### Tasks
+    - [ ] Criar agent {name}
+    - [ ] Implementar workflow {name}
+    - [ ] Validar contra checklist
+```
+
+### 10.4 Examples
+
+```yaml
+examples:
+  triggers_prd:
+    - scenario: "Squad Contabilidade MEI/Simples"
+      workflows: 54
+      agents: 14
+      decision: "VETO - PRD obrigatório"
+      reason: "54 workflows >> 10 threshold"
+
+    - scenario: "Squad Legal Completo"
+      workflows: 25
+      agents: 12
+      decision: "VETO - PRD obrigatório"
+      reason: "25 workflows + 12 agents"
+
+  direct_creation:
+    - scenario: "Squad de Email Marketing"
+      workflows: 6
+      agents: 4
+      decision: "PROCEED - Criação direta"
+      reason: "6 workflows < 10 threshold"
+
+    - scenario: "Squad de Headlines"
+      workflows: 3
+      agents: 2
+      decision: "PROCEED - Criação direta"
+      reason: "Escopo pequeno e focado"
+```
+
+---
+
+## 11. Specialist Selection Heuristic
+
+**Purpose:** Decide which specialist agent to invoke for mind cloning and squad creation.
+
+### 10.1 Available Specialists
+
+| Specialist | Domain | Activation |
+|------------|--------|------------|
+| `@oalanicolas` | Mind cloning, DNA extraction, source curation | `/squad-creator @oalanicolas` |
+| `@pedro-valerio` | Processes, tasks, checklists, automation | `/squad-creator @pedro-valerio` |
+| `@squad-chief` | General squad creation, orchestration | `/squad-creator` (default) |
+
+### 10.2 Decision Matrix
+
+```yaml
+specialist_selection:
+  id: "SC_SPE_001"
+  name: "Specialist Selection Heuristic"
+  phase: "early (before starting work)"
+
+  decision_tree: |
+    PRIMARY - Mind Cloning Tasks:
+      IF (task involves extracting DNA, voice, thinking patterns)
+        THEN invoke @oalanicolas
+      IF (task involves source curation or quality assessment)
+        THEN invoke @oalanicolas
+      IF (task involves validating clone fidelity)
+        THEN invoke @oalanicolas
+
+    SECONDARY - Process Tasks:
+      IF (task involves creating/auditing workflows)
+        THEN invoke @pedro-valerio
+      IF (task involves defining veto conditions or guardrails)
+        THEN invoke @pedro-valerio
+      IF (task involves checklist creation or validation)
+        THEN invoke @pedro-valerio
+      IF (task involves automation decisions)
+        THEN invoke @pedro-valerio
+
+    TERTIARY - General Tasks:
+      IF (task is general squad creation)
+        THEN use @squad-chief
+      IF (unclear which specialist)
+        THEN use @squad-chief (will delegate)
+
+    FALLBACK:
+      When in doubt → @squad-chief orchestrates
+
+  keywords:
+    oalanicolas:
+      - "DNA", "voice", "thinking", "clone", "mind"
+      - "source", "curadoria", "material"
+      - "personality", "communication style"
+      - "8 layers", "DNA Mental"
+      - "fidelity", "authenticity"
+
+    pedro_valerio:
+      - "process", "workflow", "task"
+      - "checklist", "validation", "audit"
+      - "automation", "guardrail", "veto"
+      - "SOP", "procedure", "efficiency"
+      - "impossible to fail", "block wrong paths"
+```
+
+### 10.3 Handoff Protocol
+
+```yaml
+handoff_rules:
+  squad_architect_to_oalanicolas:
+    trigger: "Mind cloning phase reached"
+    context_passed:
+      - mind_name
+      - domain
+      - sources_path (if exists)
+    expected_output:
+      - voice_dna (YAML block)
+      - thinking_dna (YAML block)
+      - source_quality_report
+
+  squad_architect_to_pedro_valerio:
+    trigger: "Process/workflow design phase reached"
+    context_passed:
+      - workflow_files
+      - task_files
+      - checklist_files
+    expected_output:
+      - audit_report
+      - veto_conditions
+      - automation_recommendations
+
+  oalanicolas_to_pedro_valerio:
+    trigger: "DNA extracted, need process validation"
+    context_passed:
+      - extracted_dna
+      - agent_file
+    expected_output:
+      - process_validation
+      - quality_gates
+
+  pedro_valerio_to_oalanicolas:
+    trigger: "Process ready, need mind integration"
+    context_passed:
+      - validated_process
+      - integration_points
+    expected_output:
+      - mind_integration_plan
+```
+
+### 10.4 Anti-Patterns
+
+```yaml
+anti_patterns:
+  - name: "Wrong Specialist"
+    trigger: "Using @pedro-valerio for voice extraction"
+    why_bad: "Process expert, not mind cloning expert"
+    correction: "Use @oalanicolas for DNA extraction"
+
+  - name: "Skipping Specialists"
+    trigger: "Trying to do everything with @squad-chief"
+    why_bad: "Loses depth of specialized expertise"
+    correction: "Delegate to specialists for their domains"
+
+  - name: "No Handoff Context"
+    trigger: "Switching specialists without context"
+    why_bad: "Loses continuity, duplicates work"
+    correction: "Always pass context per handoff_rules"
+```
+
+---
+
+*AIOS Decision Heuristics Framework v1.1*
+*Updated: Specialist Selection Heuristic added*