grimoire-framework 1.0.0

package/.grimoire/development/data/decision-heuristics-framework.md

@@ -0,0 +1,622 @@
+# Decision Heuristics Framework
+
+> **Version:** 1.0.0
+> **Source:** grimoire 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:
+
+```text
+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:
+
+```text
+┌─────────────────────────────────────────┐
+│  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-architect` | 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-architect
+      IF (unclear which specialist)
+        THEN use @squad-architect (will delegate)
+
+    FALLBACK:
+      When in doubt → @squad-architect 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-architect'
+    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'
+```
+
+---
+
+_grimoire Decision Heuristics Framework v1.1_
+_Updated: Specialist Selection Heuristic added_
+