metacognition · diff
git:20251231.cb53cf6 to git:20260829.876a214
46 added, 128 removed. Audit A to A.
---
name: metacognition
- description: "Validates approach and checks assumptions before/after tasks. Use when: starting work, encountering errors, or switching phases."
+ description: "Checks task understanding, evidence, scope, and stopping conditions at decision-changing moments. Use when starting repository work, changing task type, encountering unexpected evidence, or completing a meaningful phase."
---
# 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)
+ Prevent the agent from following an invalid route, expanding work without evidence, or declaring completion without observable proof.
- ## Rule Selection Guide
+ ## Checkpoints
- ### By Task Type
+ Run a checkpoint when:
- | 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 |
+ - repository work begins;
+ - the task type or approved outcome changes;
+ - unexpected evidence invalidates the current approach;
+ - a major phase or coherent implementation task completes;
+ - the next action requires user authority or an irreversible operation.
- ### Loading Strategy
+ Routine reversible actions inside an already validated approach do not require a separate checkpoint.
- **Immediate needs**: Load only what's required now
- **Progressive loading**: Add rules as specific needs arise
- **Cleanup**: Unload rules after task completion
+ ## Assessment
- Note: Context management is user's responsibility. Ask for guidance if unsure.
+ ### Outcome and Scope
- ## Common Decision Points
+ - What observable outcome owns this work?
+ - Which requirements are current, and which items are current-state evidence or speculation?
+ - What non-goals and contracts must remain unchanged?
+ - Could reuse or no-change already satisfy the outcome?
- ### 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
+ ### Evidence
- **GATE: CANNOT start coding if ANY unchecked**
+ - Which claims are observed, inferred, or unknown?
+ - What repository rule or pattern governs the next decision?
+ - Does an unknown change the outcome, scale, major design, authority, or verification?
- ### 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)
+ ### Approach
- **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
+ - Is the current route the smallest sufficient one?
+ - Does every added artifact, mechanism, test, gate, or task change the outcome, protect a boundary, serve a consumer, or supply necessary proof?
+ - What current evidence would make the approach invalid?
- **ENFORCEMENT: If progress stalled → MANDATORY metacognition**
+ ### Completion
- ### 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
+ - Is the requested result observable?
+ - Did the applicable established checks pass?
+ - Are verification gaps and residual limitations reported?
+ - Did review findings remain within approved scope?
- **GATE: CANNOT mark complete without ALL verified**
+ ## Decision
- ## Anti-Pattern Recognition
+ After assessment, choose one:
- | 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 |
+ - **continue**: Current evidence supports the route.
+ - **adjust**: A reversible local change keeps the approved outcome intact.
+ - **return to owning phase**: Evidence invalidates a requirement, major design decision, task boundary, or verification strategy.
+ - **ask the user**: Progress requires a new requirement, scope change, unavailable authority, or unauthorized irreversible action.
+ - **complete**: The outcome and required proof are observable.
## 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
+ When an unexpected result occurs:
- - **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
+ 1. Identify the failed assumption or boundary.
+ 2. Inspect the narrowest relevant repository evidence.
+ 3. Prefer removing or correcting the invalid rule or implementation before adding a fallback.
+ 4. Retry only when new evidence changes the attempt.
+ 5. Ask the user only under the user-decision conditions above.
- ## Notes
+ ## Quality Check
- 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
+ - The checkpoint changed or validated a real decision.
+ - It did not create a status artifact solely to prove reflection occurred.
+ - It preserved the approved outcome and stopped generating work once proof was sufficient.