metacognition
Validates approach and checks assumptions before/after tasks. Use when: starting work, encountering errors, or switching phases.
When & Why to Use This Skill
The Metacognition skill implements a rigorous self-assessment protocol designed to enhance the reliability and accuracy of AI agent workflows. By enforcing mandatory checkpoints before, during, and after tasks, it ensures that the agent validates its approach, identifies hidden assumptions, and adheres to established rules. This systematic reasoning framework prevents common AI pitfalls such as over-engineering, tunnel vision, and context bloat, leading to higher-quality outcomes and more efficient problem-solving.
Use Cases
- 1. Complex Project Initialization: Validating the fundamental goal and success criteria before writing the first line of code to ensure the approach aligns with the root cause rather than just symptoms.
- 2. Error Recovery and Debugging: Automatically triggering a 'Blocking Metacognition' assessment when encountering unexpected results or repetitive errors to re-evaluate the strategy and identify knowledge gaps.
- 3. Phase Transition Management: Ensuring all 'Exit Gates' (such as linting, testing, and documentation updates) are fully satisfied before moving from the implementation phase to the deployment phase.
- 4. Dynamic Rule and Context Optimization: Managing agent performance by progressively loading relevant guidelines (e.g., security or performance rules) only when specific triggers are met, preventing context overload.
| 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.mdfor 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