metacognition

Metacognition is a robust quality-control framework designed for AI coding agents. It forces the agent to pause and perform critical thinking assessments at high-stakes moments, such as task initiation, phase transitions, and error recovery. By requiring the agent to validate its understanding of goals, assess current assumptions, and confirm success criteria, this skill significantly reduces the incidence of hallucinations, over-engineering, and scope creep. It is essential for developers who need their coding assistants to maintain a disciplined, test-first approach while remaining adaptable to changing project requirements.

• Acts as an automated thought-governance layer, preventing the agent from proceeding into complex coding tasks without a verified plan.

• Includes a comprehensive checklist for task understanding, including root-cause analysis vs. symptom fixing and identification of known unknowns.

• Provides a dynamic Rule Selection Guide to load only relevant documentation (e.g., ai-development-guide.md, language-specific rules) based on the current task type, optimizing context window usage.

• Features a rigorous error recovery protocol that demands documentation of blockers and systematic reasoning before requesting user intervention.

• Enables anti-pattern recognition, allowing the agent to detect common pitfalls like tunnel vision, quality debt, and improper architectural decisions early in the development lifecycle.

• Use as a blocking requirement for any non-trivial coding task or architectural change.

• Works seamlessly with AGENTS.md workflow standards in Cursor, Codex, and Gemini CLI environments.

• Inputs: A clear prompt describing a task or error state.

• Outputs: A verified execution strategy, list of loaded context rules, and a signed-off completion summary.

• Practical constraint: Requires the agent to have access to the project's .agents directory for rule discovery.

• Encourages 'progressive loading' to keep the LLM context focused on the immediate implementation goal.