Metacognition

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: shinpr
• Source: shinpr/agentic-code
• License: MIT

Install and usage instructions live in the source repository linked above.