| 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:
- Identify what's blocking progress
- Check if it's a knowledge gap or logic error
- Review loaded rules for guidance
- Consider simpler approach
- 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
