agent-feedback

name

agent-feedback

description

Friction-log breadcrumb (`just agent-feedback "<note>"`) — appends one JSON line to `logs/agent-friction.jsonl` capturing what was tried, where it broke, and how severe. Fire at the *moment of friction*, not as a TODO list. Trigger conditions — "you tried two things and they both failed", "a tool's output didn't match its SKILL.md description", "you can't figure out which `just` command serves the user's intent", "you misread an envelope and had to retry after a course-correction". Do NOT fire for — routine errors that resolve on the first retry, syntax mistakes the user corrects in stride, gaps in your codebase knowledge that aren't tooling gaps, or as a venting channel.

Friction-Log Breadcrumb (just agent-feedback)

just agent-feedback "<note>" writes a single JSON line to logs/agent-friction.jsonl capturing the moment a workflow bonked. The corpus accumulates over weeks. Periodic review surfaces recurring patterns worth encoding into AGENTS.md, a new SKILL.md, or a new tool.

This is the agent-side mirror of logs/agent-call-history.jsonl (which records successful tool calls and their rationales). Friction is the data the call-history doesn't capture.

When to fire

Fire when:

• You tried two reasonable approaches and both failed — even though the user's request seemed in-scope for the available tooling.
• A tool's output shape didn't match what its SKILL.md described (and you wasted a turn parsing the disagreement).
• You couldn't pick the right just command from the available surface for the user's intent — i.e., the routing layer let you down.
• A SKILL.md's Fire when / Do NOT fire when block was wrong about a case that came up in practice.
• You hit a friction the user had to point out manually that should have been catchable from tool output alone.

Do NOT fire when:

• You made a mistake the user immediately corrected — that's not tool friction, it's you. Adjust and move on.
• A tool refused as designed (e.g., q events on a sweep dir refusing — the tool is correct; if its narrative pointed you at the right alternative, no friction occurred).
• A tool errored on bad input that's clearly the caller's fault (typos, malformed args).
• You were exploring and a tool said "no such file" — that's exploration, not friction.
• As a venting channel about AGENTS.md being inconvenient or about not liking a constraint.
• Multiple times for the same friction in one session — one breadcrumb per friction is enough.

Output

The tool writes to stderr agent-feedback: recorded (<severity>) → logs/agent-friction.jsonl and exits 0 on success. No useful return value to the calling agent — this is fire-and-forget breadcrumb-leaving.

Schema

{
  "timestamp":   "<ISO8601 UTC>",
  "commit":      "<short hash or null>",
  "cwd":         "/Users/.../clowder",
  "note":        "<one-sentence summary>",
  "severity":    "minor" | "major" | "blocker",
  "tool":        "<name or null>",     // which tool the friction was around
  "what_tried":  "<text or null>",     // what you tried (often redundant with note)
  "where_stuck": "<text or null>"      // where things broke or became ambiguous
}

Severity rubric

• minor — annoyance, didn't lose time. Default. Use generously; the corpus is the point.
• major — had to redo work, take a different path, or escalate to the user.
• blocker — couldn't proceed at all. Rare; this is the "this tool is broken or missing" signal.

Examples

# Most common — minor severity, with tool tag.
just agent-feedback "q events refused on sweep dir; narrative didn't suggest q deaths" --tool q

# Major — wasted a turn parsing output mismatch.
just agent-feedback "frame-diff output table shape didn't match SKILL.md columns" --severity major --tool frame-diff

# Routing gap — couldn't pick a tool.
just agent-feedback "user wanted to compare two single runs (not sweeps); no obvious tool — verdict is single-run-vs-baseline; sweep-stats wants directories" --severity major

# Blocker — tool absent for a real workflow.
just agent-feedback "no way to query trace records by DSE name across multiple cats" --severity blocker --tool q

Periodic review

The friction log is meant to be reviewed weekly or fortnightly. Suggested triage:

# Last week's friction.
jq -c 'select(.timestamp > "2026-04-20")' logs/agent-friction.jsonl

# Group by tool.
jq -c 'select(.tool)' logs/agent-friction.jsonl | jq -s 'group_by(.tool) | map({tool: .[0].tool, n: length})'

# Blockers only.
jq -c 'select(.severity == "blocker")' logs/agent-friction.jsonl

Recurring entries (2+ separate sessions on the same theme) are the strongest signal that the pattern deserves a fix — a AGENTS.md note, a new SKILL.md, or a tool change.

Hook safety

logs/agent-friction.jsonl is at the root of logs/ and is not under the logs/tuned-* or logs/baseline-* prefixes that .Codex/hooks/no-log-overwrite.py protects. Append-writes are allowed without prompting.

Non-goals

• Does not page anyone, file an issue, or auto-create tickets. The corpus is a passive record.
• Does not include tool args or full context — this is for your friction signal, not for reproducing the situation. Pair with logs/agent-call-history.jsonl if cross-referencing is needed (match on commit + nearby timestamps).
• Does not have a "resolved" field. Once written, an entry stays. If a friction is fixed, that's evidence in the next periodic review's delta, not a state change on the old entry.