aiox-core 5.0.3 → 5.0.5

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

@@ -1,620 +0,0 @@
-# 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*