Metacognition Protocol
Purpose
Prevent the agent from following an invalid route, expanding work without evidence, or declaring completion without observable proof.
Checkpoints
Run a checkpoint when:
- 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.
Routine reversible actions inside an already validated approach do not require a separate checkpoint.
Assessment
Outcome and Scope
- 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?
Evidence
- 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?
Approach
- 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?
Completion
- 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?
Decision
After assessment, choose one:
- 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 an unexpected result occurs:
- Identify the failed assumption or boundary.
- Inspect the narrowest relevant repository evidence.
- Prefer removing or correcting the invalid rule or implementation before adding a fallback.
- Retry only when new evidence changes the attempt.
- Ask the user only under the user-decision conditions above.
Quality Check
- 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.
1---2name: metacognition3description: 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.4---56# Metacognition Protocol78## Purpose910Prevent the agent from following an invalid route, expanding work without evidence, or declaring completion without observable proof.1112## Checkpoints1314Run a checkpoint when:1516- repository work begins;17- the task type or approved outcome changes;18- unexpected evidence invalidates the current approach;19- a major phase or coherent implementation task completes;20- the next action requires user authority or an irreversible operation.2122Routine reversible actions inside an already validated approach do not require a separate checkpoint.2324## Assessment2526### Outcome and Scope2728- What observable outcome owns this work?29- Which requirements are current, and which items are current-state evidence or speculation?30- What non-goals and contracts must remain unchanged?31- Could reuse or no-change already satisfy the outcome?3233### Evidence3435- Which claims are observed, inferred, or unknown?36- What repository rule or pattern governs the next decision?37- Does an unknown change the outcome, scale, major design, authority, or verification?3839### Approach4041- Is the current route the smallest sufficient one?42- Does every added artifact, mechanism, test, gate, or task change the outcome, protect a boundary, serve a consumer, or supply necessary proof?43- What current evidence would make the approach invalid?4445### Completion4647- Is the requested result observable?48- Did the applicable established checks pass?49- Are verification gaps and residual limitations reported?50- Did review findings remain within approved scope?5152## Decision5354After assessment, choose one:5556- **continue**: Current evidence supports the route.57- **adjust**: A reversible local change keeps the approved outcome intact.58- **return to owning phase**: Evidence invalidates a requirement, major design decision, task boundary, or verification strategy.59- **ask the user**: Progress requires a new requirement, scope change, unavailable authority, or unauthorized irreversible action.60- **complete**: The outcome and required proof are observable.6162## Error Recovery6364When an unexpected result occurs:65661. Identify the failed assumption or boundary.672. Inspect the narrowest relevant repository evidence.683. Prefer removing or correcting the invalid rule or implementation before adding a fallback.694. Retry only when new evidence changes the attempt.705. Ask the user only under the user-decision conditions above.7172## Quality Check7374- The checkpoint changed or validated a real decision.75- It did not create a status artifact solely to prove reflection occurred.76- It preserved the approved outcome and stopped generating work once proof was sufficient.
shinpr