agent-feedback

Phase 1: Session Discovery

.jsonl

.jsonl

~/.claude/projects/

1. Read the first few lines to extract the session metadata (sessionId, cwd, version, timestamp, the user's first message)
2. Read the last few lines to get the most recent activity and timestamp
3. Extract the model used and the slug/name if available

• Session name/slug (if available) or a summary derived from the first user message (truncated to ~60 chars)
• Model: which model was used
• Started: timestamp of first message
• Last active: timestamp of last message
• Status: whether it appears to still be active or has ended

Phase 2: Session Analysis

1. The Task: What was the agent asked to do? What were the requirements?
2. The Plan: What approach did the agent take? Did it make a plan?
3. Key Decision Points: Where did the agent make significant choices? What alternatives existed?
4. Tool Usage: What tools did the agent use? Were there failed tool calls, rejected permissions, or wasted effort?
5. Context Drift: Did the agent lose sight of the original goal? Where?
6. Mistakes: Did the agent misunderstand instructions, skip steps, or produce incorrect output?
7. CLAUDE.md / AGENTS.md Compliance: If there is a

   CLAUDE.md

   or

   AGENTS.md

   file in the working directory, check whether the agent followed its guidance. Note any violations.
8. Stopping Point: Where and why did the agent stop? Was the task complete?

Phase 3: Interactive Q&A and Corrective Prompt Construction

• "Why did it make that decision?"
• "Why did it stop?"
• "Why did it ignore [X]?"
• "What did it get confused about?"
• "Did it follow the AGENTS.md / CLAUDE.md?"
• "Where did it go wrong?"

Constructing Corrective Prompts

Corrective Prompt Format

## Context
[1-2 sentences stating what the agent was working on and where it currently is]

## Issue
[Clear, specific description of what went wrong or what needs correction]

## Evidence
[Quote or reference the specific mistake from the session, so the agent understands exactly what you're referring to]

## Required Action
[Precise, unambiguous instructions for what the agent should do next. Be directive, not suggestive.]

## Constraints
[Any guardrails to prevent the same mistake from recurring]

Corrective Prompt Principles

1. Be specific, not vague: Don't say "be more careful." Say "You modified

   src/auth.ts

   but missed the corresponding update needed in

   src/auth.test.ts

   at line 45."
2. Reference the agent's own actions: Quote what it did so it can't misinterpret what you're referring to.
3. State the desired outcome: Not just what's wrong, but what "done" looks like.
4. Prevent recurrence: If the agent drifted, add a constraint like "Before making any changes, re-read AGENTS.md section X."
5. Keep it short: Agents have limited context. Every unnecessary word dilutes the signal. Aim for the minimum effective prompt.
6. One issue per prompt: If there are multiple issues, offer to generate separate prompts for each, prioritized by impact.

Important Notes

• You are read-only. Do not modify any files or send messages to other agents.
• When reading large session files, use offset/limit parameters to read in chunks rather than loading entire files at once.
• Focus on being genuinely useful. The user is trying to fix a real problem with a real agent. Precision matters more than thoroughness.
• If a session file is very large, start with the beginning (to understand the task) and the end (to understand where things stand), then fill in the middle as needed based on the user's questions.
• Always look for

  CLAUDE.md

  and

  AGENTS.md

  files in the session's working directory, as violations of these are a common source of agent mistakes.