# Debug My Harness

> Diagnose why an agent harness misbehaved by reading the local flight-recorder ledger (.vigiles/runs.jsonl) — which skills fired or got hijacked, which hooks blocked or wrongly allowed, which subagent tool-contract violations happened, and how a skill's trigger rate moved. Use when asked why a skill stopped firing, why a hook didn't block, why the wrong skill ran, or to debug/investigate what the…

- **Type:** Skill
- **Install:** `agentstack add skill-zernie-vigiles-debug-my-harness`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [zernie](https://agentstack.voostack.com/s/zernie)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [zernie](https://github.com/zernie)
- **Source:** https://github.com/zernie/vigiles/tree/main/skills/debug-my-harness
- **Website:** https://vigiles.sh

## Install

```sh
agentstack add skill-zernie-vigiles-debug-my-harness
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

Diagnose harness misbehavior from the **flight recorder** — the local, append-only ledger
at `.vigiles/runs.jsonl` that vigiles writes as your harness runs. It records what actually
happened, so you debug from evidence instead of guessing.

## What's in the ledger

One JSON record per line, each with a `kind`:

- `hook` — a compiled-hook gate decision: `{event, decision: allow|deny|ask, mode: enforce|observe, rule, cmd, reason}`.
- `agent` — a subagent tool-contract decision: `{name, tool, allowed, reason}` (a `false` = the agent went outside its lane).
- `skill` — a skill activation: `{name, fired}`.
- `eval` — a measured metric: `{name, metric, value}` (e.g. trigger-rate recall/precision).
- `capability-diff` — a blast-radius change: `{pr, added, removed, widened}`.

## Instructions

### Step 1: Read the ledger

Read `.vigiles/runs.jsonl` (JSONL — one record per line; tolerate a torn last line). If it's
absent or empty, say so — there's nothing recorded yet; suggest running the harness (or
`vigiles audit`) first. Do NOT fabricate records.

### Step 2: Answer the specific question, evidence-first

Match the user's question to the ledger:

- **"Why did skill X stop firing / why does the wrong one run?"** — count `skill` fires by
  name over time. If X's fire-rate dropped, look for a sibling that fired on the same kinds
  of prompts (a **selection collision**) and check their descriptions for overlap. Recommend
  differentiating or merging the descriptions.
- **"Why didn't my hook block that?"** — find `hook` records for the event. A `decision:
allow` on something that should be denied, or `mode: observe` (shadow, never blocks), or
  the absence of any record, tells you which. Recommend flipping `observe`→`enforce` or
  fixing the gate logic.
- **"Did a subagent misbehave?"** — list `agent` records with `allowed: false`: the agent
  reached for a tool outside its declared contract. Point at the contract to tighten or widen.
- **"Is it getting worse?"** — compare `eval` metric values (recall/precision) across runs;
  a downward trend is drift (often after a harness/model upgrade).

### Step 3: Recommend a fix, tied to the evidence

Prefer **promoting an ignored-but-decidable rule from prose to a deterministic gate**: a
repeated `agent` violation or a rule the agent keeps breaking → a compiled hook or a tighter
tool-contract (the `strengthen` skill can help). A description collision → differentiate the
skill descriptions. Always cite the specific records you based the diagnosis on.

### Step 4: Offer the next step

If the fix is a spec change, hand off to `edit-spec`. If it's promoting guidance to a linter
rule, hand off to `strengthen`. If a behavioral claim needs measuring (does the skill fire
now?), hand off to `test-harness` (`measureTriggerRate`).

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [zernie](https://github.com/zernie)
- **Source:** [zernie/vigiles](https://github.com/zernie/vigiles)
- **License:** MIT
- **Homepage:** https://vigiles.sh

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-zernie-vigiles-debug-my-harness
- Seller: https://agentstack.voostack.com/s/zernie
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.