metacognition

name	metacognition
description	Validates approach and checks assumptions before/after tasks. Use when: starting work, encountering errors, or switching phases.

Metacognition Protocol

Purpose

Self-assessment checkpoints.

When to Apply [MANDATORY CHECKPOINTS]

BLOCKING METACOGNITION REQUIRED at:

• [CHECKPOINT] Task type changes → CANNOT proceed without assessment
• [CHECKPOINT] After completing ANY task from Work Plan document → MUST evaluate before next task
• [CHECKPOINT] When encountering error or unexpected result → ASSESS approach immediately
• [CHECKPOINT] Before writing first line of new feature → VALIDATE approach first
• [CHECKPOINT] When switching between major phases → CONFIRM all gates passed

ENFORCEMENT: Skipping metacognition = CRITICAL VIOLATION

Assessment Questions

1. Task Understanding

• What is the fundamental goal?
• Am I solving the root cause or symptom?
• Do I have all necessary information?
• Are success criteria clear and measurable?
• What are the known unknowns at this point?

2. Current State

• What rules are currently loaded?
• Which rules are actually being used?
• What assumptions am I making?
• What could go wrong?

3. Approach Validation

• Is my approach the simplest solution?
• Am I following established patterns?
• Have I considered alternatives?
• Is this maintainable long-term?
• What would make me reverse this decision? (Kill criteria)

Rule Selection Guide

By Task Type

Task Type	Essential Rules	Optional Rules
Implementation	language/rules.md, ai-development-guide.md	architecture patterns
Bug Fix	ai-development-guide.md	debugging patterns
Design	documentation-criteria.md	architecture patterns
Testing	language/testing.md	coverage strategies
Refactoring	ai-development-guide.md	design patterns

Loading Strategy

Immediate needs: Load only what's required now Progressive loading: Add rules as specific needs arise Cleanup: Unload rules after task completion

Note: Context management is user's responsibility. Ask for guidance if unsure.

Common Decision Points

When Starting Work [BLOCKING CHECKLIST]

☐ [MUST VERIFY] Task type and scale documented with evidence ☐ [MUST VERIFY] Required rules LOADED and file paths listed ☐ [MUST VERIFY] Success criteria MEASURABLE and specific ☐ [MUST VERIFY] Approach validated against existing patterns

GATE: CANNOT start coding if ANY unchecked

During Execution [PROGRESS GATES]

☐ [VERIFY] Following Work Plan from docs/plans/ ☐ [VERIFY] Making measurable progress (list completed items) ☐ [EVALUATE] Additional rules needed? (load IMMEDIATELY if yes) ☐ [EVALUATE] Blocked for >10 minutes? (MUST ask for help)

Dynamic Rule Loading Triggers:

• Same error occurs 2+ times → Load ai-development-guide.md for debugging patterns
• "Performance" mentioned in requirements → Load optimization rules if available
• "Security" mentioned in requirements → Load security guidelines if available
• External API/service integration needed → Load integration patterns if available

ENFORCEMENT: If progress stalled → MANDATORY metacognition

After Completion [EXIT GATES]

☐ [VERIFIED] ALL completion criteria met with evidence ☐ [VERIFIED] Code quality metrics passed (lint, test, build) ☐ [VERIFIED] Documentation updated (if applicable) ☐ [RECORDED] What worked/failed for next iteration

GATE: CANNOT mark complete without ALL verified

Anti-Pattern Recognition

Pattern	Signs	Correction
Over-engineering	Complex solution for simple problem	Simplify approach
Under-planning	Jumping into code too quickly	Step back, plan first
Tunnel vision	Ignoring alternatives	Consider other approaches
Quality debt	Skipping tests or docs	Complete properly
Context bloat	Loading unnecessary rules	Load only essentials

Error Recovery

When stuck:

1. Identify what's blocking progress
2. Check if it's a knowledge gap or logic error
3. Review loaded rules for guidance
4. Consider simpler approach
5. Ask user for clarification

ERROR HANDLING PROTOCOL:

When encountering an error or blocker:

• [IMMEDIATE] Execute metacognition assessment
• [SEARCH] Look for similar patterns in codebase
• [RE-READ] Relevant rule files for guidance
• [EVALUATE] Can I solve this with available information?

If unable to resolve:

• [DOCUMENT] Exact error message and context
• [EXPLAIN] What was attempted and why it failed
• [REQUEST] User guidance with specific questions

PRINCIPLE: Ask for help when genuinely stuck, not after arbitrary attempt count

Learning from Experience

Track:

• What worked well
• What caused delays
• Which rules were helpful
• What patterns emerged
• What to do differently

Guidelines

• Be honest: Acknowledge when uncertain
• Be systematic: Follow structured approach
• Be efficient: Don't overthink simple tasks
• Be thorough: Don't skip important steps
• Be adaptive: Adjust approach based on feedback

Notes

Remember:

• Metacognition prevents costly mistakes
• Regular reflection improves quality
• It's okay to pause and think
• Ask for help when genuinely stuck
• Perfect is the enemy of good