Zwergomaniac

Diagnosing Agent Sessions

| "It ignored the plan" | Plan load event, compaction |

Zwergomaniac 0 Updated 1mo ago

Resources

1
GitHub

Install

npx skillscat add zwergomaniac/mxagile/agents-skills-diagnosing-agent-session

Install via the SkillsCat registry.

SKILL.md

Diagnosing Agent Sessions

Adapted from diagnosing-superpowers (obra/superpowers). See PROVENANCE.md for mapping.

Purpose

Pin down with the user what went wrong in an agent session: repeated work, ignored plans, poor results, excessive tokens, confused behavior. Read transcripts and report findings with evidence.

Core principle: Every finding cites path:line. No citation, no finding. Every number comes from the transcript or a command you ran — never from memory.

Hard Rules

  • Read-only. Never modify, move or delete a session file.
  • Intake before analysis. Nothing in steps 2–4 starts until the problem is scoped.
  • No framework diagnosis. Report evidence; let maintainers decide.
  • Context safety. One transcript line can be large. Read targeted ranges, not full files indiscriminately.
  • Approval gates. No issue or comment before the user approves the exact text.

Workflow

Step 1: Problem Intake

Ask one question at a time until you can write a statement naming:

  • Which session(s)
  • Turn range if known
  • What was expected
  • What happened
  • The observable that matters (wall-clock, tokens, repeated actions, one specific action)

"It took too long" is a complaint, not a problem statement. Do not proceed to step 2 until scoped.

Step 2: Locate

Resolve each session to verified absolute filesystem paths. Confirm a past session by quoting its first prompt and timestamp. List every candidate you rejected with the reason.

Common Claude Code transcript locations:

  • ~/.claude/projects/<project-hash>/ — project-scoped sessions
  • Session files are typically JSON with timestamped turns

Step 3: Triage

Read the region around the reported problem yourself. Focus on:

Complaint Focus first
"Took too long" Token count per turn, stumbles, retry loops
"Extra work / repeated actions" Plan loading, where divergence started
"Too expensive" Token concentration, large context turns
"Ignored the plan" Plan loading event, session compaction points
"Skill didn't fire" Skill file presence, trigger conditions in transcript
"What is it doing?" Current action vs. plan

Step 4: Report

Write findings with citations. Distinguish:

  • Confirmed — cites specific path:line from transcript
  • Inferred — pattern observed across multiple lines, no single citation
  • Unknown — insufficient transcript access; state what is missing

Report format:

## Finding: [brief title]
Evidence: [path:line — quote]
Assessment: [what this shows]
Classification: Confirmed / Inferred / Unknown

Red Flags

Thought Reality
"Problem is obvious, skip intake" The problem statement scopes everything. Ask.
"I'll reconstruct what they meant" You cannot reconstruct what they wanted. Write the questions and stop.
"I'll sweep everything now, ask later" An unscoped sweep spends their budget on the wrong question. Ask first.
"The price per token is well known" Numbers you did not compute from the transcript are invented. Cite or drop.

Quick Reference

Complaint Read First
"Took too long" Turn timestamps, token counts
"Why did it do extra work?" Plan adherence, repeated tool calls
"Skill X never fired" Skill file presence, trigger words in prompts
"It ignored the plan" Plan load event, compaction