Diagnose root causes of AI coding session drift and rework

This skill analyzes AI-assisted coding sessions and produces a session_analysis_report.md that explains not just what happened but why it happened, who or what caused it, and what should change next time. For each session it determines what changed between the initial ask and the final executed work, whether the main cause was the user or spec, the agent, the repo or codebase, validation or testing, or legitimate task complexity, whether the opening prompt was sufficient, which files or subsystems repeatedly correlate with struggle, and what would most improve future sessions. Every diagnosis carries evidence and a confidence level - high for direct artifact or timestamp evidence, medium for multiple supporting signals, low for plausible inference not directly proven - with evidence weighted artifact contents over timestamps over metadata summaries over inference.

Use it for a postmortem on AI-assisted coding sessions, especially where scope drift or repeated rework occurred, when root-cause analysis needs to separate user/spec issues from agent mistakes, repo friction, or validation gaps, or when the goal is evidence-backed recommendations for improving future prompts, repo health, or delivery workflow. Each session's primary intent is first classified as delivery, debugging, refactor, research, exploration, or audit analysis, and that intent is used to contextualize severity - the skill explicitly does not judge exploratory or research sessions by the same standard as narrow delivery sessions, and does not punish a short prompt by default if a narrow, obvious task still had high sufficiency.

Input is a set of conversation folders (in the user's Antigravity brain/ directory), optionally filtered to a supplied keyword or path. For each conversation it reads task.md, implementation_plan.md, and walkthrough.md plus their .resolved.N revision snapshots and metadata, recording lifecycle flags, revision counts, scope deltas, timing, and content signals such as acceptance criteria, non-goals, file targets, and constraints. Output is a structured report containing: an executive summary with rated metrics (first-shot success rate, completion rate, average scope growth, replan rate, median duration, average severity, high-severity session count); a root-cause breakdown table; a prompt-sufficiency analysis (scored 0-2 across clarity, boundedness, testability, architectural specificity, constraint awareness, and dependency awareness); a scope-change analysis split into human-added, necessary-discovered, and agent-introduced scope; a rework-shape analysis (clean execution, early replan then stable finish, progressive scope expansion, reopen/reclose churn, late-stage verification churn, abandoned mid-flight, or exploratory/research session); friction hotspots clustered by file, folder, or subsystem; first-shot successes; 3-7 non-obvious findings; a severity triage naming the best intervention per session (prompt improvement, scope discipline, targeted skill or workflow, repo refactor, or validation/test-harness improvement); evidence-backed recommendations; and a per-conversation breakdown table. Root causes are one of spec ambiguity, human scope change, repo fragility, agent architectural error, verification churn, or legitimate task complexity. Each session also gets a 0-100 severity score built from completion failure, replanning intensity, scope instability, rework-shape severity, prompt-sufficiency deficit, root-cause impact, and hotspot recurrence, banded low through critical, used as a prioritization signal rather than a verdict.

As an optional final step it updates a local project-health or memory artifact with recurring failure modes and fragile subsystems, generates a prompt_improvement_tips.md drawn from high-sufficiency, first-shot-success sessions, and suggests missing skills or workflows, but only when the same subsystem or task sequence repeatedly causes struggle.

Anyone running or reviewing AI-assisted coding sessions who wants an evidence-based postmortem that separates prompt quality, agent error, repo fragility, and legitimate task complexity, rather than a simple pass/fail summary, and who needs the friction concentrated by file or subsystem made visible for prioritization.