Agent Debug
This is a Hermes-native agent-debug workflow skill.
Why This Exists
agent-debug exists so Hermes users can ask for this workflow in chat and receive a structured, evidence-bounded OMH operating surface instead of ad hoc narration.
Do Not Use When
- The request is already handled by a narrower explicit skill with stronger evidence.
- The user asks OMH to secretly run external platforms, connectors, schedulers, file exports, or runtime agents.
- The only safe answer is to ask for missing authority, credentials, target, or observed evidence first.
Examples
Good example:
- Prompt: agent-debug capture why this agent is looping on the same tool and prepare the smallest safe recovery action.
- Expected behavior: Produce
prepare_agent_debug with required context, wrapper actions, and not-evidence boundaries.
- Why: The prompt names a real workflow surface that Hermes can orchestrate without hiding execution.
Bad example:
- Prompt: agent-debug silently reset the executor, patch the environment, and claim the future loop is fixed.
- Expected behavior: Report the missing observed evidence or authority instead of claiming the external step happened.
- Why: Prepared OMH guidance is not platform, runtime, connector, file, memory, or delivery evidence.
Completion Checklist
- Failure state, intended goal, recent tool sequence, and context pressure are captured.
- Diagnosis distinguishes repeated command/tool loops, context drift, environment mismatch, service errors, and wrong-hypothesis tests.
- Recovery action is contained, reversible, and does not claim implementation, verification, CI, merge, or future-loop fixes.
Recovery Notes
- If the request is install/setup health, route to doctor.
- If the request is a manager status or throughput review, route to agent-ops-review.
- If the request is a durable self-improvement record after diagnosis, route to workflow-learning.
Workflow Lane
- Current lane: Automation and status (
achievements, workspace-audit, production-audit, automation-blueprint, github-event-ops, github-issue-intake, buzz, agent-board, +35 more) - schedules, status, health, and ops review.
- If intent belongs to another lane, hand back to
oh-my-hermes or name the adjacent workflow.
- Shared product, routing, compatibility, and evidence rules:
omh-routing/references/skill-common-rail.md.
Use When
Use when an agent run is stuck, looping on tools, burning tokens without progress, drifting from the objective, losing context, or failing on recoverable environment/tool assumptions.
Strong routing signals: `agent-debug`, `agent debug`, `agent debugging`, `agent introspection`, `agent self-debug`, `self-debug`, `self debugging`, `looping agent`, `agent loop failure`, `agent run stuck`, `agent failure capture`, `tool retry loop`, `repeated tool calls`, `context drift`, `prompt drift`, `token burn`, `에이전트 디버그`, `에이전트 실패`, `에이전트 반복 실패`, `반복 실패`, `도구 반복`, `컨텍스트 드리프트`, `토큰 낭비`
Catalog Metadata
Category: operations
Phase: agent-debug
Hermes role: operator
Quality tier: workflow-surface-gated
Reasoning demand: light
Quality bar:
- Name the user-facing workflow objective, required context, next action, and stop condition.
- Separate prepared guidance from observed platform, runtime, connector, file, memory, or delivery evidence.
- Expose missing tools, credentials, targets, or observations as user-visible gaps.
- Hold at least two competing failure hypotheses at once, each with observed evidence for and against; a diagnosis that never named a rival hypothesis is a guess.
- Order probes cheapest-discriminating-first: run the cheapest check that splits the surviving hypotheses before any expensive capture, rerun, or restart.
- When a run that used to work now fails, bisect from last-known-good to first-bad change (prompt, config, tool, model, or environment) instead of debugging the newest symptom.
- Name a cause only after revert-verify: remove the suspect change and observe the failure disappear, or state that causation is unproven.
- Reproduce the failure before preparing any recovery action; a fix without a reproduced failure first is a guess.
Handoff policy:
Keep this as Hermes-facing orchestration guidance first. Prepare executor, connector, gateway, or host-runtime handoff only when the user accepts that next step and observed evidence can be recorded.
Required inputs:
- user request
- target context
- delivery or status expectation
- known missing evidence
Expected outputs:
- agent_debug_report/v1
- agent_failure_capture/v1
- agent_failure_pattern_hypothesis/v1
- contained_recovery_action/v1
Artifact expectations:
- agent_debug_report/v1 with failure pattern, recent tool sequence, goal/context pressure, environment assumptions, recovery action, and evidence status
- agent_failure_capture/v1 separating observed errors and tool loops from inferred root-cause hypotheses
- contained_recovery_action/v1 with the smallest safe next action and explicit escalation boundary
Safety rules:
- An agent debug report is not executor reset, hidden state mutation, tool repair, implementation, verification, CI, merge-readiness, merge, or proof that future loops are fixed. Record only observed failure evidence, diagnosis hypotheses, contained recovery actions, and remaining blockers.
- Do not claim connector, gateway, runtime, file generation, memory mutation, or host automation evidence from prepared guidance.
Runtime Evidence
Preferred harness for this skill: agent-debug.
omh runtime record --skill agent-debug --harness agent-debug --status started
Record observed delegation results; otherwise return not_available or not_observed.
Prepared OMH routing is not execution, review, CI, merge-readiness, or merge evidence.
- Treat wrapper memory/context summaries as advisory local context, not proof of opaque Hermes memory reads or changes.
Preserve workflow intent and stop conditions; verify before claiming completion.
Use Hermes-native subagent/delegation features when available: native subagents -> Hermes delegation when available, otherwise sequential lanes.
Shared product, compatibility, topology, memory, harness, and execution rules: omh-routing/references/skill-common-rail.md. Load it when applicable; otherwise name an unavailable capability.
1---
2name: "omh-agent-debug"
3description: "[omh] Agent Debug workflow: capture a stuck, looping, drifting, or repeatedly failing agent run, diagnose the likely failure pattern, and prepare the smallest safe recovery action. Use when the user says: agent-debug, agent debug, agent debugging, agent introspection, agent self-debug, self-debug, self debugging, looping agent."
4metadata:
5 hermes:
6 tags: [workflow, oh-my-hermes, operations]
7 category: operations
8 phase: agent-debug
9 role: operator
10 quality_tier: workflow-surface-gated
11---
12
13# Agent Debug
14
15This is a Hermes-native `agent-debug` workflow skill.
16
17## Why This Exists
18
19`agent-debug` exists so Hermes users can ask for this workflow in chat and receive a structured, evidence-bounded OMH operating surface instead of ad hoc narration.
20
21## Do Not Use When
22
23- The request is already handled by a narrower explicit skill with stronger evidence.
24- The user asks OMH to secretly run external platforms, connectors, schedulers, file exports, or runtime agents.
25- The only safe answer is to ask for missing authority, credentials, target, or observed evidence first.
26
27## Examples
28
29Good example:
30
31- Prompt: agent-debug capture why this agent is looping on the same tool and prepare the smallest safe recovery action.
32- Expected behavior: Produce `prepare_agent_debug` with required context, wrapper actions, and not-evidence boundaries.
33- Why: The prompt names a real workflow surface that Hermes can orchestrate without hiding execution.
34
35Bad example:
36
37- Prompt: agent-debug silently reset the executor, patch the environment, and claim the future loop is fixed.
38- Expected behavior: Report the missing observed evidence or authority instead of claiming the external step happened.
39- Why: Prepared OMH guidance is not platform, runtime, connector, file, memory, or delivery evidence.
40
41## Completion Checklist
42
43- Failure state, intended goal, recent tool sequence, and context pressure are captured.
44- Diagnosis distinguishes repeated command/tool loops, context drift, environment mismatch, service errors, and wrong-hypothesis tests.
45- Recovery action is contained, reversible, and does not claim implementation, verification, CI, merge, or future-loop fixes.
46
47## Recovery Notes
48
49- If the request is install/setup health, route to doctor.
50- If the request is a manager status or throughput review, route to agent-ops-review.
51- If the request is a durable self-improvement record after diagnosis, route to workflow-learning.
52
53## Workflow Lane
54
55- Current lane: **Automation and status** (`achievements`, `workspace-audit`, `production-audit`, `automation-blueprint`, `github-event-ops`, `github-issue-intake`, `buzz`, `agent-board`, `+35 more`) - schedules, status, health, and ops review.
56- If intent belongs to another lane, hand back to `oh-my-hermes` or name the adjacent workflow.
57- Shared product, routing, compatibility, and evidence rules: `omh-routing/references/skill-common-rail.md`.
58
59## Use When
60
61Use when an agent run is stuck, looping on tools, burning tokens without progress, drifting from the objective, losing context, or failing on recoverable environment/tool assumptions.
62
63 Strong routing signals: `agent-debug`, `agent debug`, `agent debugging`, `agent introspection`, `agent self-debug`, `self-debug`, `self debugging`, `looping agent`, `agent loop failure`, `agent run stuck`, `agent failure capture`, `tool retry loop`, `repeated tool calls`, `context drift`, `prompt drift`, `token burn`, `에이전트 디버그`, `에이전트 실패`, `에이전트 반복 실패`, `반복 실패`, `도구 반복`, `컨텍스트 드리프트`, `토큰 낭비`
64
65## Catalog Metadata
66
67Category: `operations`
68Phase: `agent-debug`
69Hermes role: `operator`
70Quality tier: `workflow-surface-gated`
71Reasoning demand: `light`
72
73Quality bar:
74
75- Name the user-facing workflow objective, required context, next action, and stop condition.
76- Separate prepared guidance from observed platform, runtime, connector, file, memory, or delivery evidence.
77- Expose missing tools, credentials, targets, or observations as user-visible gaps.
78- Hold at least two competing failure hypotheses at once, each with observed evidence for and against; a diagnosis that never named a rival hypothesis is a guess.
79- Order probes cheapest-discriminating-first: run the cheapest check that splits the surviving hypotheses before any expensive capture, rerun, or restart.
80- When a run that used to work now fails, bisect from last-known-good to first-bad change (prompt, config, tool, model, or environment) instead of debugging the newest symptom.
81- Name a cause only after revert-verify: remove the suspect change and observe the failure disappear, or state that causation is unproven.
82- Reproduce the failure before preparing any recovery action; a fix without a reproduced failure first is a guess.
83
84Handoff policy:
85
86Keep this as Hermes-facing orchestration guidance first. Prepare executor, connector, gateway, or host-runtime handoff only when the user accepts that next step and observed evidence can be recorded.
87
88Required inputs:
89
90- user request
91- target context
92- delivery or status expectation
93- known missing evidence
94
95Expected outputs:
96
97- agent_debug_report/v1
98- agent_failure_capture/v1
99- agent_failure_pattern_hypothesis/v1
100- contained_recovery_action/v1
101
102Artifact expectations:
103
104- agent_debug_report/v1 with failure pattern, recent tool sequence, goal/context pressure, environment assumptions, recovery action, and evidence status
105- agent_failure_capture/v1 separating observed errors and tool loops from inferred root-cause hypotheses
106- contained_recovery_action/v1 with the smallest safe next action and explicit escalation boundary
107
108Safety rules:
109
110- An agent debug report is not executor reset, hidden state mutation, tool repair, implementation, verification, CI, merge-readiness, merge, or proof that future loops are fixed. Record only observed failure evidence, diagnosis hypotheses, contained recovery actions, and remaining blockers.
111- Do not claim connector, gateway, runtime, file generation, memory mutation, or host automation evidence from prepared guidance.
112
113## Runtime Evidence
114
115Preferred harness for this skill: `agent-debug`.
116
117```sh
118omh runtime record --skill agent-debug --harness agent-debug --status started
119```
120
121Record observed delegation results; otherwise return `not_available` or `not_observed`.
122Prepared OMH routing is not execution, review, CI, merge-readiness, or merge evidence.
123- Treat wrapper memory/context summaries as advisory local context, not proof of opaque Hermes memory reads or changes.
124Preserve workflow intent and stop conditions; verify before claiming completion.
125
126Use Hermes-native subagent/delegation features when available: native subagents -> Hermes delegation when available, otherwise sequential lanes.
127
128Shared product, compatibility, topology, memory, harness, and execution rules: `omh-routing/references/skill-common-rail.md`. Load it when applicable; otherwise name an unavailable capability.
rlaope