meta-cognitive-reasoning

# 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/error individually

### Pattern 2: Pattern Matching Without Context

- Applying solutions without understanding problems
- Prevention: Analyze actual purpose before applying templates

### Pattern 3: Assumption-Based Conclusions

- Guessing instead of verifying
- Prevention: Evidence-based verification required

### Pattern 4: Premature Success Declaration

- "Task complete" ≠ "Requirements verified"
- Prevention: Show tool output proving completion

### Pattern 5: Temporal Knowledge Decay

- Confusing "I don't know" with "doesn't exist"
- Prevention: Verify version/feature currency

### Pattern 6: Overconfidence Cascade

```
False premise: "X doesn't exist" (unverified)
    ↓
Amplified: "This is CRITICAL/BLOCKER"
    ↓
Harmful: "Change X to older version Y"
    ↓
Impact: Downgrade from newer to older

BREAK THE CASCADE: Verify the premise first
```

## Examples

### Example 1: Version Verification

**Situation**: Reviewing code that uses `certifi==2025.10.5`

**Wrong Approach:**

```markdown
CRITICAL: Version 2025.10.5 doesn't exist!
Action: Change to 2024.x.x
```

**Correct Approach:**

```markdown
Let me verify this version exists...

$ grep -A 3 'name = "certifi"' uv.lock
name = "certifi"
version = "2025.10.5"
source = { registry = "https://pypi.org/simple" }

Evidence shows version EXISTS on PyPI.
Action: NO CHANGE NEEDED - version is valid.
```

### Example 2: File Structure Analysis

**Observation**: Three files with identical 1494-line content

- specs/AGENTS.md
- specs/CLAUDE.md
- specs/GEMINI.md

**Wrong Approach:**

```markdown
CRITICAL: File duplication - consolidate to single file
```

**Correct Approach:**

```markdown
Competing hypotheses:
A: Duplicated copies -> CRITICAL: Consolidate
B: Symlinks to single source -> EXCELLENT: Keep

Gathering discriminating evidence:
$ ls -la specs/
lrwxrwxrwx CLAUDE.md -> AGENTS.md
lrwxrwxrwx GEMINI.md -> AGENTS.md

Mechanism: Symlinks (Hypothesis B confirmed)
Assessment: EXCELLENT architecture - agent-specific entry points with single source of truth
Action: Keep as-is
```

### Example 3: Test Failure Analysis

**Observation**: 5 tests failing with "connection timeout"

**Hypotheses:**

- A: Single dependency down (fix one thing)
- B: Multiple independent timeouts (fix five things)
- C: Test infrastructure issue (fix setup)
- D: Environment config missing (fix config)

**Investigation:**

- Check test dependencies
- Check error timestamps (simultaneous vs sequential)
- Run tests in isolation

**Then conclude based on evidence.**

## Anti-Patterns

```
DO NOT:
- "File X doesn't exist" without: ls X
- "Function not used" without: grep -r "function_name"
- "Version invalid" without: checking registry/lockfile
- "Tests fail" without: running tests
- "CRITICAL/BLOCKER" without verification
- Use strong language without evidence
- Skip mechanism investigation
- Pattern match to first familiar case

DO:
- Show grep/ls/find output BEFORE claiming
- Quote actual lines: "file.py:123: 'code here' - issue"
- Check lockfiles for resolved versions
- Run available tools and show output
- Reserve strong language for evidence-proven issues
- "Let me verify..." -> tool output -> interpretation
- Generate multiple hypotheses before gathering evidence
- Distinguish observation from mechanism
```

## Clarifying Questions

**Before proceeding with complex tasks, ask:**

1. What is the primary goal/context?
2. What scope is expected (simple fix vs comprehensive)?
3. What are the success criteria?
4. What constraints exist?

**For reviews specifically:**

- Scope: All changed files or specific ones?
- Depth: Quick feedback or comprehensive analysis?
- Focus: Implementation quality, standards, or both?
- Output: List of issues or prioritized roadmap?

## Task Management Patterns

### Review Request Interpretation

**Universal Rule: ALL reviews are comprehensive unless explicitly scoped**

**Never assume limited scope based on:**

- Recent conversation topics
- Previously completed partial work
- Specific words that seem to narrow scope
- Apparent simplicity of request

**Always include:**

- All applicable quality gates
- Evidence for every claim
- Complete verification of requirements
- Systematic coverage (not spot-checking)

### Context Analysis Decision Framework

**Universal Process:**

1. **Analyze actual purpose** (don't assume from patterns)
2. **Check consistency** with actual usage
3. **Verify with evidence** (read/test to confirm)
4. **Ask before acting** when uncertain

**Recognition Pattern:**

```
WRONG: "Other components do X, so this needs X"
RIGHT: "Let me analyze if this component actually needs X for its purpose"
```

## Related Use Cases

- Code reviews requiring evidence-based claims
- Version verification before recommendations
- Architectural assessments
- Debugging with multiple possible causes
- Documentation analysis
- Security audits
- Performance investigations
- Any analysis requiring rigorous reasoning