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
2. What mechanisms could produce this observation?
3. Which mechanisms have opposite implications?

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

1. Identify discriminating evidence
2. What single observation would prove/disprove each?

1. Gather discriminating evidence
2. Run the specific test that distinguishes hypotheses

1. Assess with mechanism context
2. 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/er