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:

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

Correct Approach:

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:

CRITICAL: File duplication - consolidate to single file

Correct Approach:

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

Detailed Meta-Cognitive Frameworks

This reference provides expanded decision frameworks for complex reasoning scenarios.

Defensive Programming Skepticism

Recognition Pattern: Justifying code with "it's idempotent/safe/defensive" without proving the problem exists

Decision Framework:

When encountering "just in case" code:

1. What SPECIFIC problem does this solve?
   Not "might prevent X" - does X actually occur here?

2. Can that problem occur in THIS context?
   Evidence: Can I trigger the failure scenario?

3. Is defense solving real problem or imagined one?
   Real: Problem documented/observed/testable
   Imagined: "Could happen" without evidence

4. What's the cost of the defense?
   Complexity, performance, maintenance burden

When Defensive Code IS Appropriate:

• Trust boundaries (external input, API boundaries)
• Error recovery (network failures, timeouts)
• Resource availability (external dependencies)
• Race conditions (concurrent access, locking)
• Actual observed failures (documented/reproducible)

When Defensive Code IS NOT Appropriate:

• "Could happen" without evidence
• Patterns copied without context analysis
• Already handled by framework/tool
• Problem cannot occur given invariants

Problem-First vs Solution-First Thinking

Recognition Pattern: Reaching for "better tools" instead of questioning the need

Decision Framework:

1. Question First: Why does this problem exist? 2. Consider Prevention: Can we avoid creating the problem? 3. Benchmark Elimination: Is prevention faster than optimization? 4. Resist Pattern Matching: Does this case really need the standard solution?

Thinking Pattern:

WRONG: "How do I make X faster?"
RIGHT: "Why do I need X at all?"

WRONG: "Better post-processing tools"
RIGHT: "Smarter construction to avoid post-processing"

Structured Roadmap for Complex Multi-Issue Tasks

When to Use: Analysis identifies 10+ issues across different severity levels

Roadmap Structure:

## Critical Issues (Blockers)
[Issues that prevent merge/deployment/completion]
- Explicit: will cause failure if not fixed
- Evidence-based: shown with file:line:evidence

## High-Priority Issues
[Significant quality/security/correctness concerns]
- Important but not blocking
- Should address before considering done

## Medium Priority
[Improvements that enhance quality]
- Nice-to-have refactorings
- Documentation gaps

## Low Priority / Future
[Future optimizations, minor suggestions]
- Can be deferred
- Track but don't block on

## Summary & Recommendations
**Blockers for completion:** [Explicit checklist]
**Suggested next steps:** [Clear action items]

Reader vs Writer Optimization

Recognition Pattern: Proposing changes that make writing easier at expense of reading

Decision Framework:

1. IDENTIFY the activities
   - Reading/using the artifact
   - Writing/updating the artifact

2. MEASURE frequency
   - How often is this read/used?
   - How often is this written/updated?

3. CALCULATE costs
   - Cost per read (context switching, searching)
   - Cost per write (updating multiple places)

4. COMPUTE total cost over time
   - Total read cost: Read_cost x Read_frequency
   - Total write cost: Write_cost x Write_frequency

5. OPTIMIZE for higher total cost
   - If Total_read >> Total_write -> Optimize for reader
   - If Total_write >> Total_read -> Optimize for writer

When Writer Optimization IS Appropriate:

• Content changes frequently (volatile)
• Many writers, few readers
• Consistency is critical
• Write cost is very high

When Reader Optimization IS Appropriate:

• Content is stable (rare updates)
• Many readers, few writers
• Cognitive flow matters
• Read cost compounds over time

Organizational Structure Debates

Recognition Pattern: Multiple valid proposals, no convergence, debate feels unresolvable

Core Insight: Structure debates are rarely about structure - they're about unstated architectural philosophy differences

Decision Framework:

STEP 1: RECOGNIZE DEEPER QUESTIONS
Not "Where should files go?"
But: "What assumptions drive each proposal?"

STEP 2: SURFACE UNSTATED ASSUMPTIONS
Option A assumes: Polyglot future
Option B assumes: Current scope
Option C assumes: Application boundaries

STEP 3: FACILITATE ALIGNMENT ON PHILOSOPHY
Ask clarifying questions:
- "Is this a monorepo or single-project?"
- "Will we add other languages?"
- "What's the 6-12 month growth plan?"

STEP 4: STRUCTURE FOLLOWS PHILOSOPHY
Once philosophy aligned, structure becomes obvious

STEP 5: DOCUMENT DECISION AND RATIONALE
"We chose X because [philosophy]"

Mid-Task Feedback Integration

When user provides mid-task feedback:

1. Pause and reassess - Don't compartmentalize feedback 2. Extract underlying principle - What broader lesson applies? 3. Apply throughout task - Not just to immediate item 4. Show integration - Demonstrate corrected understanding

Documentation Quality Detection

Core Principle: Documentation should justify existence by adding non-obvious information

Universal Decision Framework:

For each piece of documentation, ask in order:

1. Does it explain WHY, not WHAT?
   KEEP: "Single-threaded to avoid race conditions"
   DELETE: "Single-threaded implementation"

2. Does it provide non-obvious context?
   KEEP: "Must be called before initialize() due to DI order"
   DELETE: "Configuration class" when class is named Config

3. Does it explain business rules, constraints, or edge cases?
   KEEP: "Returns null for suspended users per GDPR requirements"
   DELETE: "Returns user or null"

4. Does it explain technical mechanisms or gotchas?
   KEEP: "Uses weak references to prevent memory leaks"
   DELETE: "Uses weak references"

5. Would a new team member lose important information?
   KEEP: "CRITICAL: Must acquire lock before modifying"
   DELETE: "Acquires lock" (obvious from code)

If all answers are NO -> Documentation is useless

Multi-Level Documentation Structure

Recognition Pattern: Reviewing parent-child documentation hierarchy

Usage-First Decision Framework:

1. WHO is the actual user?
   - AI agent loading specific context
   - Human reader navigating hierarchy

2. WHAT is the usage pattern?
   - Top-down: Read root -> specialize
   - Current-and-up: Load specific -> reference general
   - Reference: Search/jump to specific concept

3. WHAT is being "duplicated"?
   - Literal repetition (consolidate)
   - Contextual adaptation (keep separated)

4. WHAT is the cost tradeoff?
   - Context switching cost (every use)
   - Maintenance burden (rare updates)

5. WHAT is the document TYPE?
   - Code: optimize for DRY
   - Cognitive framework: optimize for flow
   - API reference: optimize for lookup

Critical Distinction:

DUPLICATION (consolidate):
Same principle, same examples, same commands
Different location only

CONTEXTUAL ADAPTATION (keep separate):
Same principle core concept
Different domain-specific recognition patterns
Different decision frameworks
Different verification commands

Session Artifact Detection

Recognition Pattern: References to specific PRs, issues, incidents in universal documentation

Decision Framework:

1. EVALUATE function
   - Does the example work without the reference?
   - Is the reference needed for verification?

2. ASSESS accessibility
   - Can future readers access the artifact?
   - Or is it just a reference number?

3. DETERMINE priority
   - Does removing it significantly improve universality?
   - Or is the example already clear?

4. CALIBRATE effort vs impact
   - How much work to refactor?
   - How much clarity gained?

Priority Calibration:

HIGH priority to remove:
- Reference required for example to make sense
- Blocks understanding without external artifact

LOW priority (optional polish):
- Example is self-contained and clear
- Reference adds traceability but not needed for comprehension

Real-Time Assumption Correction

Recognition: When user feedback challenges your approach

Correct Response Protocol:

1. PAUSE immediately - Stop current approach, don't just acknowledge 2. Extract the principle - What assumption was incorrect? 3. Apply consistently - Update ALL similar decisions in current task 4. Demonstrate integration - Show you've corrected the understanding

Anti-Pattern:

WRONG: Continue with original plan while acknowledging feedback
RIGHT: Revert approach based on corrected understanding

Key Insight: User feedback often reveals fundamental approach errors affecting entire task, not just minor adjustments

Systematic Completion Discipline (Extended)

Structured Roadmap for Complex Multi-Issue Tasks:

When analysis identifies 10+ issues across different severity levels, use this structure:

## Critical Issues (Blockers)
[Issues that prevent merge/deployment/completion]
- Explicit: will cause failure if not fixed
- Evidence-based: shown with file:line:evidence

## High-Priority Issues
[Significant quality/security/correctness concerns]
- Important but not blocking
- Should address before considering done

## Medium Priority
[Improvements that enhance quality]
- Nice-to-have refactorings
- Documentation gaps

## Low Priority / Future
[Future optimizations, minor suggestions]
- Can be deferred
- Track but don't block on

## Summary & Recommendations
**Blockers for completion:** [Explicit checklist]
**Suggested next steps:** [Clear action items]

Benefits:

• Prevents overwhelm (clear priorities vs undifferentiated list)
• Enables parallel work (different people tackle different priorities)
• Clear completion criteria (what MUST be done vs nice-to-have)
• Progress tracking (check off completed items)

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"

Application Examples:

• Before adding error handling: Does this error path actually occur?
• Before adding validation: Is input already validated upstream?
• Before refactoring: Does this pattern serve a purpose I'm missing?

Meta-Pattern Documentation

When capturing learnings:

Focus on:

• Recognition patterns that apply across contexts
• Decision frameworks that prevent common failures
• Universal cognitive principles
• Anti-patterns and how to avoid them

Avoid:

• Session-specific implementation details
• Framework-specific solutions without broader applicability
• File paths, line numbers, exact error messages from specific sessions

Test: "Would this apply to completely different domain/project?"

Domain-Specific Examples

This reference provides concrete examples of meta-cognitive principles applied across different domains.

Code Review Examples

File Duplication Analysis

Observation: Three files with identical content

Wrong Analysis:

CRITICAL: File duplication - consolidate to single file

Correct Analysis:

$ ls -la specs/
-rw-r--r-- 44754 AGENTS.md
lrwxrwxrwx     9 CLAUDE.md -> AGENTS.md
lrwxrwxrwx     9 GEMINI.md -> AGENTS.md

Competing Hypotheses:

• A: Duplicated copies -> CRITICAL: Consolidate
• B: Symlinks to single source -> EXCELLENT: Keep
• C: Hardlinks -> Investigate platform implications
• D: Generated from template -> Check build process

Evidence Shows: Symlinks (Hypothesis B)

Assessment: EXCELLENT architecture

• Agent-specific entry points (discoverability)
• Single source of truth (maintainability)
• Zero maintenance burden (automatic sync)

Code Duplication Analysis

Observation: Identical function in two modules

Competing Hypotheses:

• A: Copy-pasted code -> BAD: Extract to shared utility
• B: Intentional duplication -> GOOD: Bounded context isolation
• C: Shared import with re-export -> NEUTRAL: Check imports
• D: Generated from macro -> NEUTRAL: Check generation

Discriminating Evidence:

• Check import statements
• Check git history (intentional divergence?)
• Check module boundaries (different domains?)
• Check comments (documented rationale?)

Mechanism Determines Assessment:

• If A: Refactor to DRY
• If B: Keep separate (bounded context isolation)
• If C: Already shared, no action needed
• If D: Review generation config

Debugging Examples

Test Failures

Observation: 5 tests failing with "connection timeout"

Competing 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)

Discriminating Evidence:

• Check test dependencies (shared fixture?)
• Check error timestamps (simultaneous vs sequential?)
• Run tests in isolation (still fail?)
• Check test environment setup (missing config?)

Evidence-Based Investigation:

grep -A 5 "timeout" test_output.log

Performance Issues

Observation: Two endpoints both respond in 5 seconds

Competing Hypotheses:

• A: Shared bottleneck (fix one thing)
• B: Coincidental similar issues (fix two things)
• C: Artificial throttling (configuration issue)
• D: Resource exhaustion (infrastructure issue)

Discriminating Evidence:

• Profile each endpoint separately
• Check for rate limiting config
• Check resource utilization
• Check network latency

Version Verification Examples

Package Version Claims

Situation: Review flags certifi==2025.10.5 as invalid

Wrong Response:

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

Correct Response:

$ grep -A 3 'name = "certifi"' uv.lock
name = "certifi"
version = "2025.10.5"
source = { registry = "https://pypi.org/simple" }
sdist = { url = "...", hash = "sha256:47c09..." }

Temporal Analysis:

• Knowledge cutoff: January 2025
• Current date: October 2025
• Gap: 9 months
• Certifi releases monthly
• Calculation: Version could exist

Evidence: Version EXISTS on PyPI with valid hash

Action: NO CHANGE NEEDED

Framework Version Claims

Situation: Code uses React 19 features

Wrong Analysis:

React 19 doesn't exist, use React 18 patterns

Correct Analysis:

Temporal check:
- Training cutoff: January 2025
- React major releases: ~yearly
- Time elapsed: Could allow new major version

Verification needed before claiming non-existence

Infrastructure Examples

CI/CD Configuration

Observation: mkdir -p commands in workflow

- name: Prepare build contexts
  run: mkdir -p certs src/utils

Justification Given: "For idempotency on fresh checkout"

Investigation:

$ ls -la certs/
.gitkeep  README.md  # Tracked files exist

$ git ls-files src/utils/
__init__.py
common_utils.py

Evidence: Directories always exist after checkout (tracked content)

Assessment: Redundant defensive code solving non-existent problem

Configuration Analysis

Observation: Identical configuration in three services

Competing Hypotheses:

• A: Copy-pasted config -> BAD: Centralize
• B: Inherited from shared config -> GOOD: Already centralized
• C: Coincidentally same values -> NEUTRAL: Independent decisions
• D: Generated from IaC -> EXCELLENT: Automated consistency

Discriminating Evidence:

• Check config source (inheritance?)
• Check version control (single source?)
• Check infrastructure code (terraform/helm?)
• Check deployment process

Documentation Examples

Useless Documentation Detection

Example 1: Restating Syntax

# Class Definition
class UserService:
    pass

Assessment: Useless - syntax already shows it's a class

Example 2: Rephrasing Identifiers

def get_user_by_id(user_id):
    """Gets user by ID"""

Assessment: Useless - function name already says this

Example 3: Valuable Documentation

def get_user_by_id(user_id):
    """Retrieves user from cache if available, otherwise queries database.
    Returns None if user not found or access denied."""

Assessment: Valuable - explains behavior not obvious from name

Header Evaluation

Useless:

# ==============================================================================
# User Service Module - Authentication Package
# ==============================================================================

In file: src/authentication/user_service.py

Assessment: Useless - path already provides this information

Valuable:

# CRITICAL: This service uses optimistic locking.
# Do not modify user records without acquiring version lock first.
# See incident #1234 for consequences of race condition.

Assessment: Valuable - explains non-obvious constraints

API Design Examples

Structure Debate

Debate: REST vs GraphQL

Surface Level: Technical trade-offs

Deeper Question: What are the unstated assumptions?

• REST assumes: Stable contracts, server-defined resources
• GraphQL assumes: Client flexibility, dynamic queries

Resolution Approach:

• "What's more important: stable contracts or flexible queries?"
• "How often do client needs change?"
• "What's our API versioning strategy?"

Test Organization

Debate: Mirror src structure vs group by type

Hypotheses:

• A: Mirror -> Maintenance optimization (co-located)
• B: Group -> Discovery optimization (all tests together)

Clarifying Questions:

• How do developers find tests?
• How often do tests move with code?
• What's the team's existing mental model?

Error Correction Examples

Format for Self-Correction

## CRITICAL CORRECTION: Previous Analysis Error

### Previous Claim
"Version X doesn't exist" (marked as BLOCKER)

### Evidence

$ [verification command]
[output showing claim was wrong]

### Why Error Occurred
Temporal knowledge gap: Training data from [date], current date is [date]

### Correct Assessment
[What the evidence actually shows]

### Action
NO CHANGE NEEDED / [Specific alternative action]

Real Correction Example

## CRITICAL CORRECTION: Previous Review Was Incorrect

**Previous claim:** "certifi 2025.10.5 doesn't exist" (CRITICAL/BLOCKER)

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

**Conclusion:** certifi 2025.10.5 EXISTS on PyPI

**Error cause:** Temporal knowledge issue - training data from January 2025,
but today is October 2025. Version released after knowledge cutoff.

**Action:** NO CHANGE NEEDED - pyproject.toml is correct as-is.