metacognition

name	metacognition
description	Route and calibrate work with model-agnostic metacognitive control. Use when the user asks for thinking-about-thinking, harness effectiveness, task routing, self-correction, confidence calibration, or strategy improvement before execution.
argument-hint	["task"]
disable-model-invocation	true

/metacognition

Steered metacognition mode for:

$ARGUMENTS

/metacognition is the harness-level control plane for thinking about the work, not a replacement executor.

It classifies the task, chooses the smallest useful reasoning and verification budget, accounts for parallel capacity, records evidence requirements, and routes to the existing harness command that should do the work.

It does not replace /workflow; it steers /opusworkflow for mutating work and the underlying /workflow lifecycle when an explicit fallback is needed. It does not replace /introspect; /introspect remains the canonical hard-gate self-audit command.

Command Boundary

Use /metacognition to decide how the harness should approach the task before execution: route, evidence, capacity, confidence threshold, and blocked inputs.

Use /introspect to decide whether the current plan, diff, verification, or closeout is trustworthy enough to continue.

In a normal file-changing /workflow, the order is:

metacognitive route -> research -> code audit -> /introspect pre-plan
-> plan -> SPEC.md -> execute -> /introspect post-implementation -> verify

Do not use /metacognition as a softer synonym for /introspect. If the task needs a hard self-audit, route to /introspect and require a blocker decision.

Core Contract

Metacognition is useful only when it is evidence-grounded.

It must:

• classify the task before choosing a route
• inspect or cite capacity evidence before deciding parallelism
• treat MAX_PARALLEL_AGENTS, Codex max_threads, and hardware ceiling as ceilings, not quotas
• name required evidence before confidence is allowed
• treat model self-reports as candidate evidence, not ground truth
• avoid depending on raw hidden chain-of-thought or provider-specific thinking blocks
• downgrade confidence when sources, tests, repo evidence, credentials, or runtime proof are missing
• route execution to existing commands instead of becoming a second workflow engine

Task Classes

Choose exactly one:

Task Class	Use When	Route
answer	direct answer, no repo mutation, no current facts required	answer directly
claudeproduct	Claude, Claude Code, Claude.ai, Anthropic API, connector, plugin, skill, or subagent product question	/claudeproduct
webresearch	narrow current fact check	/webresearch
deepresearch	landscape, architecture, due diligence, strategic research	/deepresearch
deepretaste	detect product intent, define ICPs, and bootstrap or retaste taste.md / taste.vision from research-backed customer evidence	/deepretaste
defineicp	define ICPs or tailor taste.md / taste.vision to an ideal customer profile	/defineicp
workflow	repo-changing build/fix/refactor/docs/config work	/opusworkflow with inner_contract=workflow
parallel	dense independent packets with clear ownership and verification	/opusworkflow with inner_contract=parallel for mutation; /parallel for explicit execution-only fallback
hive	multi-agent coordination needs roles, blackboard, dissent, and synthesis	/hive for read-only coordination or /opusworkflow with inner_contract=hiveworkflow for mutation
agentfactory	governed Hermes agent creation or runtime-bound agent design	/opusworkflow with inner_contract=agentfactory
verify	check an output against SPEC.md	/verify
introspect	hard-gate self-audit or confidence challenge	/introspect
blocked	credentials, policy, source truth, safety, or approval is missing	stop and state blocker

Smart Autorouting

Route to the smallest mode that can improve correctness:

Route	Choose When	Downgrade When
/opusworkflow	default for any repo-changing work, including specialist mutation	analysis-only task, explicit local /workflow override, or provider split unavailable
/workflow	explicit fallback when the work must stay in one local supervisor loop	default mutating work should use /opusworkflow first
/parallel	independent execution or evidence packets have clear ownership and aggregate verification	the main need is judgment breadth, dissent, or synthesis rather than execution throughput
/hive	independent roles, blackboard state, dissent, and synthesis improve planning, research, review, or risk judgment	no visible blackboard, no dissent path, or summaries would become unverified truth
/hiveworkflow	file-changing work needs both hive coordination and workflow execution	use under /opusworkflow; downgrade when roles/blackboard/ownership/capacity/verification cannot be written cleanly

Default to /opusworkflow for mutation. Within that route, default to inner_contract=parallel for disjoint execution throughput and inner_contract=hiveworkflow when coordinated judgment breadth plus file changes are both needed. Use /hive directly for read-only coordination.

Never route to hive just because more agents are available.

Capacity Evidence

Every metacognitive run must inspect or cite current capacity evidence:

bash scripts/parallel-capacity.sh --json 2>/dev/null || true

If the command is unavailable, use the conservative path and say capacity evidence is unavailable.

Effective Parallel Budget

Compute:

effective_metacognition_budget =
  min(MAX_PARALLEL_AGENTS, codex_max_threads, hardware_recommended_ceiling,
      independent_questions_or_packets, supervisor_capacity, verifier_capacity)

Use the smallest useful budget:

• 1 lane: tightly coupled work, one file/surface, or one decision loop
• 2-4 lanes: independent research tracks, risk review, or code-path exploration
• 5+ lanes: broad audits, dense planning, independent packet DAGs, or multi-surface verification

Never claim that max agents means max quality. Never claim linear speedup such as "10 agents means 10x faster."

Required Output

## Task Class
[answer / webresearch / deepresearch / opusworkflow / deepretaste / workflow-fallback / parallel / hive / agentfactory / verify / introspect / blocked]

## Capacity Evidence
- Source: [`scripts/parallel-capacity.sh --json` output, repo config, or unavailable]
- MAX_PARALLEL_AGENTS: [value or unknown]
- Codex max_threads: [value or unknown]
- Hardware ceiling: [value or unknown]

## Effective Parallel Budget
- MAX_PARALLEL_AGENTS: [value or unknown]
- Codex max_threads: [value or unknown]
- Hardware ceiling: [value or unknown]
- Independent lanes available: [number]
- Effective budget: [number]
- Decision: [local / subagents / parallel / blocked]
- Reason: [why this is the smallest useful budget]

## Reasoning Budget
[low / medium / high / xhigh] as harness effort, not hidden chain-of-thought

## Evidence Required
- [repo files, source ledger, tests, runtime proof, human approval, credentials, or blocked input]

## Metacognitive Audits
- Assumption audit: ...
- Source/evidence audit: ...
- Scope audit: ...
- Verification audit: ...
- Risk audit: ...
- Estimate audit: ...

## Route Decision
- Route: [/opusworkflow with inner_contract, /workflow fallback, /claudeproduct, /deepresearch, /deepretaste, /parallel, /hive, /hiveworkflow, /agentfactory, /verify, /introspect, direct answer, or blocked]
- Reason: ...

## Confidence
- Level: [high / medium / low]
- Downgrade: [none / reason]

Route Behavior

• If effective budget is 1, continue local.
• If effective budget is 2+ for research only, split independent research/risk tracks.
• If the task asks how to use Claude, Claude Code, Claude.ai, Anthropic API, skills, connectors, plugins, hooks, MCP, subagents, models, plan availability, limits, or setup, route to /claudeproduct. That skill may then choose /webresearch or /deepresearch under an official-source policy.
• If implementation packets are independent and file ownership is clear, recommend /parallel.
• If packets overlap or verification cannot aggregate results, downgrade to local /workflow.
• If capacity evidence is unavailable, choose a conservative budget and state the downgrade.

Workflow Integration

When /workflow handles file-changing work, record a compact ## Metacognitive Route section before ## Research Brief in the workflow artifact. It must include:

• task class
• capacity evidence
• effective parallel budget
• chosen route
• evidence required
• confidence threshold
• why the full parallel ceiling was or was not used

Quality Gates

The metacognitive route must fail or block when:

• task class is missing
• effective parallel budget is missing
• max agents are treated as a quota
• reflection is not tied to evidence
• hidden/raw chain-of-thought is required
• model self-report is promoted without verified outcome
• confidence is high while evidence is missing
• unresolved blockers are followed by positive closeout
• /metacognition is presented as replacing or satisfying /introspect

Use bash scripts/metacognition-scorecard.sh --fixtures --json to prove the static contract.

Anti-Patterns

• "I reflected and it seems good" without evidence
• using /metacognition as a second implementation engine
• treating /review or /metacognition as a substitute for /introspect
• using all parallel lanes because they exist
• scoring raw hidden chain-of-thought
• promoting self-reported lessons into memory without verified outcomes