Hk Autonomy Audit

/hk-autonomy-audit — Autonomous Loop-Closing Readiness Audit

You're auditing whether the tooling, docs, commands, and flows in a given area are sufficient for an AI agent to autonomously solve problems — from first symptom to verified fix — without stopping to ask a human.

This is not a documentation quality check. It's an operational readiness assessment. The question isn't "do docs exist?" but "if an agent hit a wall here at 3am, could it get itself unstuck?"

Target

<audit_target> $ARGUMENTS </audit_target>

If the target is empty or vague, ask the user:

1. What area or flow should be audited? (e.g., "odin task execution", "taskit API debugging", "reflection quality issues")
2. Is there a specific scenario that prompted this? (a recent failure where an agent got stuck is the best input)

If the user provides a doc path, start there but don't stop there — trace outward to the commands, tools, and flows the doc references.

The Mental Model

An AI agent closing the loop on a problem goes through six stages. A gap at any stage breaks the chain:

DISCOVER → DIAGNOSE → HYPOTHESIZE → FIX → VERIFY → DOCUMENT
   ↓          ↓           ↓          ↓       ↓          ↓
 "Something  "The root   "Changing  "Apply  "Confirm   "Record what
  is wrong"   cause is    X should   the     it works   happened and
              Y because   fix it     change  end-to-    why"
              Z"          because W" itself  end"

Each stage needs specific resources. The audit checks whether those resources exist, are discoverable, and are actually usable by an agent (not just by a human who knows where to look).

Process

Step 1: Scope the audit

Read the target area's CLAUDE.md, AGENTS.md, and any referenced docs. Build a mental map of:

• What problems can occur here? (error types, failure modes, misconfigurations)
• What tools exist for this area? (diagnostic scripts, CLI commands, log files)
• What docs cover this area? (guides, patterns, solutions)

Don't read everything — scan headings and structure first. Depth comes in Step 2 when you know where to look.

Step 2: Walk the agent journey

For each stage, evaluate from the perspective of an AI agent that has access to the repo's CLAUDE.md files and tools but no prior tribal knowledge. Use parallel subagents to check multiple stages simultaneously.

DISCOVER — Can the agent detect that something is wrong?

• Are error messages actionable? (Do they say what failed, or just "error"?)
• Are logs accessible and parseable? (Where are they? What format? Can an agent tail them?)
• Are there health checks or status commands? (Quick "is this working?" checks)
• Is there monitoring that surfaces problems before a human reports them?

DIAGNOSE — Can the agent find the root cause?

• Are diagnostic scripts/commands available? (Not just "look at the code")
• Do diagnostic tools explain what they find? (Auto-detected problems, not just raw data)
• Is the data flow traceable? (Can the agent follow data from input to symptom?)
• Are common failure patterns documented with their signatures?

HYPOTHESIZE — Can the agent form a theory?

• Do docs explain the WHY behind design decisions? (Not just what the code does)
• Are edge cases and gotchas documented? (The non-obvious things)
• Are there solution docs from past incidents? (Searchable by symptom)
• Is there enough architectural context to reason about side effects?

FIX — Can the agent make the change?

• Are modification commands documented? (Not just read-only inspection)
• Are there guard rails? (Tests that catch regressions, linters, type checks)
• Is the change surface well-bounded? (Can the agent know which files to touch?)
• Are there examples of similar past fixes? (Patterns to follow)

VERIFY — Can the agent confirm the fix works?

• Are test commands documented and runnable? (Not just "run the tests")
• Is there a live verification path? (Beyond unit tests — can the agent check end-to-end?)
• Are success criteria defined? (How does "working" look, specifically?)
• Can the agent verify without human eyes? (No "check the UI visually" without tooling)

DOCUMENT — Can the agent record what happened?

• Is there a documentation workflow? (Where to put learnings, what format)
• Are there templates for incident docs? (Solution docs, RCA reports)
• Is the compounding mechanism discoverable? (Would an agent know to use /hk-compound?)