Agent Misalignment Debugger

A recovery skill for failed AI coding-agent sessions.

It diagnoses what went wrong, separates useful changes from risky changes, and writes a minimal recovery prompt for the next agent run.

What It Is

agent-misalignment-debugger is a platform-neutral Skill for diagnosing failed, unsafe, incomplete, or misaligned AI coding-agent sessions.

It is useful when an AI coding agent such as Codex, Claude Code, Cursor, Gemini CLI, or another coding agent:

• Misunderstands the original task
• Changes too many files
• Ignores explicit user constraints
• Performs unnecessary refactoring
• Adds unnecessary dependencies
• Claims completion without evidence
• Skips validation
• Ignores failing tests
• Wastes context by repeatedly scanning the repository
• Attempts unsafe recovery actions

This skill helps the user answer:

• What went wrong?
• Did the agent actually complete the task?
• Which changes are useful?
• Which changes are risky?
• Should I continue, partially revert, or fully restart?
• What should I tell the next agent?

Why This Exists

AI coding agents are powerful, but real-world sessions can fail in predictable ways.

Common failure patterns include:

• Intent misread
• Scope creep
• Constraint violation
• False completion report
• Validation gap
• Ignored test failure
• Context misread
• Over-refactoring
• Dependency drift
• Environment misdiagnosis
• Partial implementation
• Regression risk
• Token waste / context churn
• Unsafe recovery attempt

The goal is not to blame the agent. The goal is to recover safely, preserve useful work, avoid destructive commands, and produce a clear next prompt.

Core Principles

Evidence-Based Diagnosis

The skill does not guess. It inspects evidence such as:

• User request
• Explicit constraints
• Agent claims
• Git status
• Git diff
• Changed files
• Build output
• Test output
• Lint/typecheck output
• Runtime logs
• Error messages
• Dependency changes

Minimal Recovery

The skill should not turn recovery into a new large refactor. It identifies the smallest safe next step.

Preserve Useful Work

The skill does not recommend a full revert by default. It separates:

• Useful changes to keep
• Risky changes to re-check
• Unrelated changes to revert
• Unknown changes requiring user decision

No Destructive Commands by Default

The skill must not run or recommend destructive commands casually.

Examples of destructive commands:

• git reset
• git reset --hard
• git clean
• git checkout -- .
• rm
• rm -rf

Destructive actions require explicit user confirmation.

Installation

Codex

mkdir -p ~/.codex/skills
cp -R agent-misalignment-debugger ~/.codex/skills/

Other coding agents

Copy the agent-misalignment-debugger directory into the agent’s supported skills, commands, rules, or reusable instruction directory.

The important file is:

• agent-misalignment-debugger/SKILL.md

Additional reference material is stored in:

• agent-misalignment-debugger/references/

Directory Structure

agent-misalignment-debugger/
  SKILL.md
  README.md
  references/
    failure-taxonomy.md
    recovery-report-template.md
    recovery-prompt-template.md
    evidence-checklist.md
    examples.md

File roles:

• SKILL.md: main skill instructions and trigger description
• README.md: project overview and usage guide
• references/failure-taxonomy.md: detailed failure types and recovery advice
• references/recovery-report-template.md: standard recovery report format
• references/recovery-prompt-template.md: copy-paste prompts for future agent runs
• references/evidence-checklist.md: evidence checklist for diagnosis
• references/examples.md: complete examples for common failure scenarios

Usage

Use this Skill when you need to diagnose a failed or misaligned AI coding-agent run and recover safely.

Example trigger prompts:

• “Use agent-misalignment-debugger to diagnose this failed Codex run.”
• “The previous agent changed too much code. Diagnose what went wrong and write a recovery prompt.”
• “Codex claimed this was done, but tests failed. Use the failure doctor.”
• “Analyze this git diff and tell me what to keep, what to revert, and what prompt to use next.”
• “The previous AI agent ignored my constraints. Use agent-misalignment-debugger and generate a recovery report.”
• “This coding-agent session wasted a lot of context and did not make progress. Diagnose the failure and write a better next prompt.”

Expected Output

The Skill should produce a report with this structure:

# Agent Failure Recovery Report
## 1. Summary
## 2. Original Intent
## 3. Evidence Reviewed
## 4. Failure Classification
## 5. What Went Wrong
## 6. Useful Changes to Keep
## 7. Risky Changes to Revert or Re-check
## 8. Validation Status
## 9. Recommended Recovery Strategy
## 10. Minimal Next Task
## 11. Copy-Paste Recovery Prompt
## 12. Do Not Do

The report should always end with a copy-paste prompt for the next agent run.

Supported Agents

This Skill is designed to work with:

• Codex
• Claude Code
• Cursor
• Gemini CLI
• OpenHands
• Aider
• Other agentic coding tools that support reusable instruction packs

It does not claim official support from any vendor.

Recovery Strategies

Continue with constraints

Use when:

• The diff is mostly relevant
• The main issue is missing validation
• The task is partially implemented
• No hard constraints were deeply violated

Partial revert then continue

Use when:

• Useful and risky changes are mixed
• Scope creep occurred
• Over-refactoring occurred
• Dependency drift occurred
• Some files are unrelated to the original task

Full revert and restart

Use when:

• The agent fundamentally misunderstood the task
• Most changes are unsafe or unrelated
• Hard constraints were deeply violated
• There is no clear useful subset of changes

Important:

Do not execute destructive revert commands automatically. Recommend the strategy and require user confirmation for destructive actions.

Example Workflow

1. User notices an AI coding-agent run may have failed.
2. User asks to use this skill.
3. The agent inspects the original request, constraints, git status, diff, and validation evidence.
4. The agent classifies the failure.
5. The agent separates useful changes from risky changes.
6. The agent recommends a recovery strategy.
7. The agent writes a copy-paste recovery prompt.
8. The next agent run uses that prompt to recover safely.

Safety

This skill defaults to diagnosis-only mode.

It should not:

• Modify files during diagnosis
• Run destructive git commands
• Delete files
• Overwrite user changes
• Install dependencies
• Run broad formatters
• Regenerate lockfiles
• Hide failing tests
• Claim completion without validation evidence

It should:

• Base conclusions on evidence
• Label unknowns clearly
• Keep recovery minimal
• Separate useful changes from risky changes
• Stop after writing the recovery prompt unless the user asks for more

When Not to Use

Do not use this Skill when:

• You need a normal code review instead of recovery diagnosis
• You need a general debugging walkthrough for code that was never touched by an agent
• You want a fresh implementation plan rather than post-failure recovery
• You already know the exact fix and do not need a recovery report

Suggested License

Suggested open-source license:

• MIT

If you distribute this Skill, choose a license that matches your project policy.

Contributing

Contributions should keep the Skill:

• Platform-neutral
• Evidence-based
• Diagnosis-first
• Minimal and non-destructive
• Focused on recovery prompts and failure analysis

Please keep wording consistent across SKILL.md, README.md, and the reference files.

Included References

• references/failure-taxonomy.md: failure categories and recovery advice
• references/recovery-report-template.md: structured diagnosis report template
• references/recovery-prompt-template.md: ready-to-copy recovery prompt templates
• references/evidence-checklist.md: evidence checklist for diagnosis
• references/examples.md: concrete examples of common failure modes and recovery prompts

Open Source Notes

This Skill is intentionally generic and portable.

It avoids:

• Vendor-specific assumptions
• Project-specific language bindings
• Framework-specific recovery logic
• Destructive recovery instructions

That makes it suitable for reuse across repositories and agent platforms.

Final Note

The recovery report should end with a copy-paste prompt for the next agent run. If the report cannot produce a prompt, the diagnosis is incomplete.