meta-cognitive-reasoning

What this skill does

# Meta-Cognitive Reasoning

This skill provides disciplined reasoning frameworks for avoiding cognitive failures in analysis, reviews, and decision-making. It enforces evidence-based conclusions, multiple hypothesis generation, and systematic verification.

## When to Use This Skill

- Before making claims about code, systems, or versions
- When conducting code reviews or architectural assessments
- When debugging issues with multiple possible causes
- When encountering unfamiliar patterns or versions
- When making recommendations that could have significant impact
- When pattern matching triggers immediate conclusions
- When analyzing documentation or specifications
- During any task requiring rigorous analytical reasoning

## What This Skill Does

1. **Evidence-Based Reasoning**: Enforces showing evidence before interpretation
2. **Multiple Hypothesis Generation**: Prevents premature commitment to single explanation
3. **Temporal Knowledge Verification**: Handles knowledge cutoff limitations
4. **Cognitive Failure Prevention**: Recognizes and prevents common reasoning errors
5. **Self-Correction Protocol**: Provides framework for transparent error correction
6. **Scope Discipline**: Allocates cognitive effort appropriately

## Core Principles

### 1. Evidence-Based Reasoning Protocol

**Universal Rule: Never conclude without proof**

```
MANDATORY SEQUENCE:
1. Show tool output FIRST
2. Quote specific evidence
3. THEN interpret
```

**Forbidden Phrases:**

- "I assume"
- "typically means"
- "appears to"
- "Tests pass" (without output)
- "Meets standards" (without evidence)

**Required Phrases:**

- "Command shows: 'actual output' - interpretation"
- "Line N: 'code snippet' - meaning"
- "Let me verify..." -> tool output -> interpretation

### 2. Multiple Working Hypotheses

**When identical observations can arise from different mechanisms with opposite implications - investigate before concluding.**

**Three-Layer Reasoning Model:**

```
Layer 1: OBSERVATION (What do I see?)
Layer 2: MECHANISM (How/why does this exist?)
Layer 3: ASSESSMENT (Is this good/bad/critical?)

FAILURE: Jump from Layer 1 -> Layer 3 (skip mechanism)
CORRECT: Layer 1 -> Layer 2 (investigate) -> Layer 3 (assess with context)
```

**Decision Framework:**

1. **Recognize multiple hypotheses exist**
   - What mechanisms could produce this observation?
   - Which mechanisms have opposite implications?

2. **Generate competing hypotheses explicitly**
   - Hypothesis A: [mechanism] -> [implication]
   - Hypothesis B: [different mechanism] -> [opposite implication]

3. **Identify discriminating evidence**
   - What single observation would prove/disprove each?

4. **Gather discriminating evidence**
   - Run the specific test that distinguishes hypotheses

5. **Assess with mechanism context**
   - Same observation + different mechanism = different assessment

### 3. Temporal Knowledge Currency

**Training data has a timestamp; absence of knowledge ≠ evidence of absence**

**Critical Context Check:**

```
Before making claims about what exists:
1. What is my knowledge cutoff date?
2. What is today's date?
3. How much time has elapsed?
4. Could versions/features beyond my training exist?
```

**High Risk Domains (always verify):**

- Package versions (npm, pip, maven)
- Framework versions (React, Vue, Django)
- Language versions (Python, Node, Go)
- Cloud service features (AWS, GCP, Azure)
- API versions and tool versions

**Anti-Patterns:**

- "Version X doesn't exist" (without verification)
- "Latest is Y" (based on stale training data)
- "CRITICAL/BLOCKER" without evidence

### 4. Self-Correction Protocol

**When discovering errors in previous output:**

```
STEP 1: ACKNOWLEDGE EXPLICITLY
- Lead with "CRITICAL CORRECTION"
- Make it impossible to miss

STEP 2: STATE PREVIOUS CLAIM
- Quote exact wrong statement

STEP 3: PROVIDE EVIDENCE
- Show what proves the correction

STEP 4: EXPLAIN ERROR CAUSE
- Root cause: temporal gap? assumption?

STEP 5: CLEAR ACTION
- "NO CHANGE NEEDED" or "Revert suggestion"
```

### 5. Cognitive Resource Allocation

**Parsimony Principle:**

- Choose simplest approach that satisfies requirements
- Simple verification first, complexity only when simple fails

**Scope Discipline:**

- Allocate resources to actual requirements, not hypothetical ones
- "Was this explicitly requested?"

**Information Economy:**

- Reuse established facts
- Re-verify when context changes

**Atomicity Principle:**

- Each action should have one clear purpose
- If description requires "and" between distinct purposes, split it
- Benefits: clearer failure diagnosis, easier progress tracking, better evidence attribution

### 6. Systematic Completion Discipline

**Never declare success until ALL requirements verified**

**High-Risk Scenarios for Premature Completion:**

- Multi-step tasks with many quality gates
- After successfully fixing major issues (cognitive reward triggers)
- When tools show many errors (avoidance temptation)
- Near end of session (completion pressure)

**Completion Protocol:**

1. Break requirements into explicit checkpoints
2. Complete each gate fully before proceeding
3. Show evidence at each checkpoint
4. Resist "good enough" shortcuts

**Warning Signs:**

- Thinking "good enough" instead of checking all requirements
- Applying blanket solutions without individual analysis
- Skipping systematic verification
- Declaring success while evidence shows otherwise

### 7. Individual Analysis Over Batch Processing

**Core Principle: Every item deserves individual attention**

**Apply to:**

- Error messages (read each one individually)
- Review items (analyze each line/file)
- Decisions (don't apply blanket rules)
- Suppressions (justify each one specifically)

**Anti-Patterns:**

- Bulk categorization without reading details
- Blanket solutions applied without context
- Batch processing of unique situations

### 8. Semantic vs Literal Analysis

**Look for conceptual overlap, not just text/pattern duplication**

**Key Questions:**

- What is the actual PURPOSE here?
- Does this serve a functional need or just match a pattern?
- What would be LOST if I removed/changed this?
- Is this the same CONCEPT expressed differently?

**Applications:**

- Documentation: Identify semantic duplication across hierarchy levels
- Code review: Understand intent before suggesting changes
- Optimization: Analyze actual necessity before improving

## How to Use

### Verify Before Claiming

```
Verify that package X version Y exists before recommending changes
```

```
Check if this file structure is symlinks or duplicates before recommending consolidation
```

### Generate Multiple Hypotheses

```
The tests are failing with timeout errors. What are the possible mechanisms?
```

```
These three files have identical content. What could explain this?
```

### Conduct Evidence-Based Review

```
Review this code and show evidence for every claim
```

## Reasoning Workflows

### Verification Workflow

When encountering unfamiliar versions/features:

1. **Recognize uncertainty**: "I don't recall X from training"
2. **Form hypotheses**: A) doesn't exist, B) exists but new, C) is current
3. **Verify before concluding**: Check authoritative source
4. **Show evidence, then interpret**: Command output -> conclusion

### Assessment Workflow

When analyzing code, architecture, or configurations:

1. **Observe**: What do I see?
2. **Investigate mechanism**: HOW does this exist?
3. **Then assess**: Based on mechanism, is this good/bad?

### Review Workflow

For code reviews, documentation reviews, or any analysis:

1. **Clarify scope**: Ask before assuming
2. **Show evidence for every claim**: File:line:code
3. **Generate hypotheses before concluding**
4. **Distinguish mechanism from observation**
5. **Reserve strong language for verified issues**

## Cognitive Failure Patterns

### Pattern 1: Scanning Instead of Reading

- Missing obvious issues while finding minor ones
- Prevention: Read every line/e