metathink

name	metathink
description	Metathink - Optimize Claude Code usage through metacognitive strategies. Use extended thinking, context engineering, task decomposition, and chain-of-thought prompting. Use when planning complex tasks, debugging difficult issues, making architectural decisions, or improving AI collaboration effectiveness.
version	1.0.0
last_updated	2026-01-18

Metathink: Metacognitive Reasoning with Claude Code

Strategic framework for optimizing Claude Code effectiveness through metacognitive awareness—thinking about how you and Claude think together.

Metathink = Thinking about thinking while coding

When to Use This Skill

• Complex architectural decisions - Need deep reasoning about trade-offs
• Difficult debugging - Issues requiring multi-step investigation
• Large refactoring tasks - Planning before implementation critical
• Learning new patterns - Understanding "why" not just "what"
• Session optimization - Improving collaboration effectiveness
• Context management - Maintaining clean, relevant context
• Quality improvement - Moving beyond "metacognitive laziness"

Quick Reference

Trigger Extended Thinking

# In your prompts, use trigger words for deeper reasoning:
"think"         # ~4,000 token thinking budget
"think hard"    # ~10,000 tokens
"think harder"  # ~31,999 tokens (maximum)
"ultrathink"    # Maximum reasoning budget

# View Claude's internal reasoning
Ctrl+O          # Toggle verbose mode (gray italic text)

Essential Commands

/clear          # Reset context between distinct tasks
Ctrl+O          # Toggle thinking visibility
/help           # Get Claude Code help

Quick Metacognitive Checklist

Before any task:

1. REFLECT → What's the complexity? What context is needed?
2. PLAN → Enter plan mode? Use agent? Which skills?
3. PROMPT → High-level instructions, trigger thinking if needed
4. MONITOR → Use Ctrl+O to observe reasoning
5. EVALUATE → Review solutions, ask "why"
6. ITERATE → Clear context, refine approach

Core Workflow

1. Metacognitive Task Assessment

Before prompting Claude, ask yourself:

Question	Action
How complex is this task?	Simple = direct prompt; Complex = plan mode or "think harder"
What domain does this involve?	Database → database-specialist; Sentry → sentry-fixer-agent
Do I need to explore first?	Unknown codebase areas → explore agent
Will this touch multiple files?	Yes → Enter plan mode for user approval
Are there multiple approaches?	Yes → Use AskUserQuestion or plan mode

2. Strategic Prompt Construction

Context Engineering Strategies:

❌ BAD - Direct jump to implementation:
"Add user authentication"

✅ GOOD - Metacognitive approach:
"I need to add user authentication. First, research our existing auth patterns
and explore how other features handle authentication. Then think hard about
the best approach before proposing an implementation plan."

Trigger Deep Reasoning When:

• Architectural decisions required
• Multiple valid approaches exist
• Edge cases need consideration
• Performance optimization needed
• Security implications present

Example Prompts:

# Trigger extended thinking
"Think harder about the trade-offs between these database indexing strategies"

# Request explicit reasoning
"Explain your reasoning step-by-step before implementing the RLS policy"

# Encourage exploration
"Research how our codebase handles file uploads, then plan the best approach"

# Plan before implementation
"Let's enter plan mode - I want to review your approach before coding"

3. Context Management

The 2026 Shift: Context Engineering > Prompt Engineering

Strategy	Implementation	Benefit
Clear frequently	/clear between distinct tasks	Removes irrelevant context
Just-in-time loading	Load files/skills only when needed	Reduces token usage
Progressive disclosure	Start broad, drill down as needed	Maintains focus
Skill injection	Use skills for domain knowledge	On-demand expertise
Agent delegation	Use specialized agents for domains	Optimized reasoning

Practical Context Commands:

# Clear context between tasks
/clear

# Use skills for just-in-time knowledge
# (No need to load full docs into context)
"Use the database-migration-manager skill to create this migration"

# Delegate to specialized agents
"Use the database-specialist agent to design this schema"

# Load specific context files when needed
"Read the CLAUDE.md file in apps/web/"

4. Task Decomposition Strategy

Think metacognitively about task structure:

# Step 1: Identify task type
├─ Research/Exploration → Use explore agent, don't code yet
├─ Implementation → Enter plan mode first
├─ Bug Fix → Use Sentry agent or step-by-step debugging
└─ Database Work → Use database-specialist agent

# Step 2: Break down complexity
├─ Simple (1-2 files) → Direct prompt
├─ Medium (3-5 files) → Use TodoWrite to track steps
└─ Complex (5+ files, architecture) → Plan mode required

# Step 3: Choose collaboration strategy
├─ Need thinking visibility → Ctrl+O (verbose mode)
├─ Need deeper reasoning → Add "think harder"
└─ Need user input on approach → AskUserQuestion or plan mode

Example: Decomposing Complex Task

User: "Optimize the event listing page performance"

Metacognitive Approach:
1. REFLECT: This is complex - involves DB queries, React rendering, caching
2. PLAN: Use explore agent first, then db-performance-agent
3. PROMPT: "First, explore how the event listing page works. Then use the
   db-performance-agent to scan for N+1 queries and performance issues.
   Think hard about optimization strategies before proposing changes."
4. MONITOR: Enable Ctrl+O to see reasoning about trade-offs
5. EVALUATE: Review proposed optimizations, ask about edge cases
6. ITERATE: Implement approved changes, measure improvements

5. Chain-of-Thought Prompting

Encourage explicit reasoning:

# Request step-by-step thinking
"Before implementing, explain:
1. What approaches you considered
2. Why you chose this approach
3. What edge cases exist
4. What could go wrong"

# Ask for trade-off analysis
"Compare the pros/cons of using Redis vs in-memory cache for this feature"

# Require justification
"Why is this the best pattern for our codebase?"

# Seek alternatives
"What are 3 different ways to solve this? Which do you recommend and why?"

6. Monitoring Claude's Reasoning

Use Ctrl+O to observe:

• How Claude approaches problems
• What it considers important
• Where it self-corrects
• How it handles edge cases
• When it's uncertain

Look for:

• ✅ Systematic exploration of options
• ✅ Consideration of edge cases
• ✅ Self-correction when wrong
• ❌ Jumping to conclusions
• ❌ Missing obvious alternatives
• ❌ Not checking assumptions

Intervene when needed:

"I see you're considering approach A, but what about approach B?"
"You mentioned edge case X - how would the solution handle that?"
"I notice you didn't check if that file exists - let's verify first"

7. Avoiding Metacognitive Laziness

Research Warning: Over-reliance on AI can cause "metacognitive laziness"—letting AI do all thinking while you disengage.

Stay Cognitively Engaged:

❌ Passive AI Use	✅ Active Collaboration
"Just fix it"	"Explain the issue first, then propose solutions"
Accept code without review	"Walk me through what this code does"
Skip reading plans	"Why did you choose this approach?"
Don't question suggestions	"Are there alternative approaches?"
Copy-paste without understanding	"Explain this pattern so I can use it elsewhere"

Maintain Your Metacognition:

1. Understand, don't just accept - Ask "why" and "how"
2. Review before approving - Read plans, check reasoning
3. Challenge assumptions - "Did you consider X?"
4. Learn patterns - Build your own understanding
5. Practice independent thinking - Try solving before asking
6. Verify outputs - Test, don't blindly trust

Common Patterns

Pattern 1: Research-First Workflow

# Instead of: "Add feature X"
# Use metacognitive approach:

"I need to add feature X. First:
1. Explore how similar features are implemented in our codebase
2. Research best practices for this pattern
3. Think hard about edge cases and security implications
4. Enter plan mode so I can review your approach before coding"

Pattern 2: Debugging with Metacognition

# Instead of: "Fix this bug"
# Use systematic approach:

"I'm seeing error Y. Before fixing:
1. Use the explore agent to understand the relevant code paths
2. Explain what you think is causing the error
3. Think through potential solutions and their trade-offs
4. Propose the safest fix with minimal side effects"

Pattern 3: Architecture Decisions

# For complex architectural choices:

"We need to decide between approach A and B. Please:
1. Research how our codebase handles similar patterns
2. Think harder about the long-term implications of each approach
3. Consider: maintainability, performance, security, scalability
4. Present pros/cons with your recommendation and reasoning"

Pattern 4: Context-Aware Sessions

# Manage context deliberately:

# Start of session
"Let's work on the authentication system. First, explore the current
implementation so we have shared context."

# Between tasks
"/clear"  # Clean slate for next task

# Before complex work
"Let me give you context on our auth requirements..."
# (Provide specific, relevant context)

# Load knowledge just-in-time
"Use the flutter-development skill for this mobile feature"

Pattern 5: Progressive Understanding

# Build understanding incrementally:

# Level 1: Broad overview
"What's the overall architecture of the event system?"

# Level 2: Specific component
"How does event creation work specifically?"

# Level 3: Deep dive
"Read the event creation service and explain the validation logic"

# Level 4: Implementation
"Now that we understand the patterns, let's add feature X following
the same approach"

Advanced Strategies

Model-Specific Optimization

Claude Code (Sonnet 4.5):

• Prefers high-level instructions over prescriptive steps
• Excels at sustained reasoning for complex tasks
• Best for large files, complex refactors, architecture
• Use concise prompts, let Claude's creativity emerge

Prompt Patterns:

✅ "Optimize the database queries in this service"
   (High-level, Claude determines approach)

❌ "First find all queries, then wrap each in transaction,
   then add error handling, then..."
   (Too prescriptive, limits Claude's reasoning)

Extended Thinking Budget Management

When to use different thinking levels:

Task Complexity	Trigger	Token Budget	Use Case
Simple	(none)	Default	Straightforward implementations
Medium	"think"	~4k tokens	Multiple considerations
Complex	"think hard"	~10k tokens	Architectural decisions
Critical	"think harder"	~32k tokens	Security, performance, complexity

Example Usage:

# Simple task (no trigger needed)
"Add a console.log statement here"

# Medium complexity
"Think about the best way to structure this form validation"

# Complex problem
"Think hard about how to optimize this N+1 query while maintaining RLS"

# Critical decision
"Think harder about the security implications of this authentication flow"

Agent Selection Framework

Use agents for specialized reasoning:

Need	Agent	Rationale
Database design	database-specialist	Domain expertise for schema/RLS
Performance issues	db-performance-agent	Specialized N+1 detection
Quality review	quality-reviewer	Pattern validation, auto-fixes
Production errors	sentry-fixer-agent	Error investigation workflow
Code exploration	Explore agent	Efficient codebase navigation
Flutter quality	flutter-quality-agent	Mobile-specific patterns

Metacognitive Agent Selection:

# Ask yourself: "What domain expertise is needed?"
├─ Database → database-specialist
├─ Performance → db-performance-agent
├─ Quality → quality-reviewer
├─ Errors → sentry-fixer-agent
├─ Exploration → Explore agent
└─ General → Claude handles natively

# Then prompt accordingly:
"Use the database-specialist agent to design this schema with proper RLS"

Skills as Just-in-Time Knowledge

Instead of loading full documentation:

# ❌ Don't do this:
"Read all the Flutter documentation files and then help me build a form"
(Loads thousands of tokens)

# ✅ Do this:
"Use the flutter-forms skill to build a multi-step form with validation"
(Loads only relevant skill content)

Strategic Skill Usage:

Scenario	Skill	Benefit
Database migrations	database-migration-manager	Migration patterns on-demand
RLS policies	rls-policy-generator	Security patterns without full docs
API patterns	api-patterns	Server action templates
i18n work	i18n-translation-guide	Translation patterns when needed
Performance	web-performance-metrics	Optimization strategies

Troubleshooting

Issue	Cause	Metacognitive Solution
Claude jumps to coding too fast	No planning phase	Use "First, explore..." or enter plan mode
Solutions feel generic	Missing context	Provide codebase-specific context, reference existing patterns
Repeated mistakes	Context pollution	Use /clear between tasks
Shallow reasoning	No thinking trigger	Add "think hard" or "think harder"
Missing edge cases	Not prompted for them	Ask "What edge cases exist?"
Wrong approach chosen	No comparison requested	"Compare approaches A, B, C - pros/cons"
Can't see Claude's reasoning	Verbose mode off	Press Ctrl+O to view thinking
Context limits hit	Too much loaded	Use skills/agents, progressive disclosure

Anti-Patterns to Avoid

❌ Anti-Pattern 1: Lazy Prompting

"Fix it"
"Make it work"
"Do the thing"

Problem: No context, no guidance, poor results

✅ Instead:

"The user authentication is failing with error X. First, explore the auth
code to understand the flow, then think about what could cause this error,
and propose a fix with explanation."

❌ Anti-Pattern 2: Blindly Accepting Output

User: "Add feature X"
Claude: [Generates code]
User: "Great, ship it!"

Problem: Metacognitive laziness, no understanding

✅ Instead:

User: "Add feature X"
Claude: [Generates code]
User: "Explain what this code does and why you chose this approach"
Claude: [Explains reasoning]
User: "What about edge case Y?"
Claude: [Addresses concern]
User: "Good, let's implement it"

❌ Anti-Pattern 3: Context Hoarding

# Loading everything "just in case"
"Read all files in /app"
"Load all skills"
"Show me everything about feature X"

Problem: Token waste, context pollution

✅ Instead:

# Just-in-time loading
"Explore the auth feature to find relevant files"
"Use the database-migration-manager skill for this migration"
"Read the specific file I need: apps/web/lib/auth.ts"

❌ Anti-Pattern 4: No Task Decomposition

"Build the entire user management system"

Problem: Too complex, no tracking, likely incomplete

✅ Instead:

"Let's build the user management system. First, enter plan mode so we can
break this into phases. I want to review the architecture before we start."

❌ Anti-Pattern 5: Ignoring Claude's Uncertainty

Claude: "I think this might work, but I'm not certain about..."
User: "Just do it"

Problem: Proceeding despite uncertainty leads to bugs

✅ Instead:

Claude: "I think this might work, but I'm not certain about..."
User: "Let's investigate that uncertainty. Research our codebase to see
how we handle similar cases."

Quality Metrics

Assess your metacognitive collaboration:

Metric	Target	How to Measure
Understanding	Can explain all code changes	Ask yourself: "Why this approach?"
Context efficiency	< 5 /clear needs per complex task	Monitor context bloat
Planning rate	Use plan mode for 80%+ complex tasks	Track when you skip planning
Thinking triggers	Use extended thinking for critical decisions	Review transcripts
Question frequency	Ask "why" 3+ times per complex feature	Self-monitor engagement
Error rate	< 5% of implementations need rework	Track fixes/revisions

Session Optimization Checklist

Before starting work:

• Complexity assessed (simple/medium/complex)?
• Relevant skills identified?
• Need for plan mode evaluated?
• Context window clean (used /clear if needed)?
• Extended thinking triggers considered?

During work:

• Using Ctrl+O to monitor reasoning when appropriate?
• Asking "why" questions to understand approaches?
• Challenging assumptions and seeking alternatives?
• Using TodoWrite for multi-step tasks?
• Loading context just-in-time, not preemptively?

After work:

• Understanding all implemented code?
• Can explain design decisions to team?
• Learned patterns for future use?
• Context cleared for next task?
• Session insights captured?

Related Resources

Ballee-Specific Skills

Apply metacognitive strategies with domain skills:

Web Development:

• database-migration-manager - Migrations with planning
• rls-policy-generator - Security-first thinking
• service-patterns - Service layer patterns
• api-patterns - Server action patterns
• web-performance-metrics - Performance optimization

Mobile Development:

• flutter-development - Flutter patterns
• flutter-query-testing - Query validation
• flutter-testing - Testing strategies

Operations:

• sentry-error-manager - Error investigation
• production-database-query - Safe production queries
• dev-environment-manager - Environment management

Official Documentation

• Extended Thinking Tips - Claude Docs
• Claude Code Best Practices
• The "think" tool
• Chain of Thought Prompting
• Effective Context Engineering

Research Papers

• Scaffolding Metacognition in Programming Education
• IBM 2026 Guide to Prompt Engineering
• K2View Prompt Engineering Techniques 2026

Success Criteria

Effective metacognitive collaboration achieves:

✅ You understand WHY, not just WHAT was implemented ✅ Complex tasks planned before implementation ✅ Context stays relevant and clean ✅ Extended thinking used for critical decisions ✅ Claude's reasoning visible when needed ✅ Assumptions questioned, alternatives explored ✅ Implementations rarely need rework ✅ You're learning patterns, not just getting code ✅ Collaboration feels strategic, not reactive ✅ Quality improves over time

---

Last Updated: 2026-01-18 Version: 1.0.0 Maintainer: Ballee Engineering Team

Key Takeaway

Metacognition in Claude Code is not about using more features—it's about thinking strategically about:

1. What you ask (task decomposition)
2. How you ask (prompting strategies)
3. When to use tools (context engineering)
4. Why approaches work (understanding, not just accepting)

Master these, and you transform Claude Code from a code generator into a reasoning partner.