Regtransfers/analyze-project

@ /analyze-project — Root Cause Analyst Workflow

Analyze AI-assisted coding sessions in ~/.gemini/antigravity/brain/ and produce a report that explains not just what happened, but why it happened, who/what caused it, and what should change next time.

@ Goal

For each session, determine:

1. What changed from the initial ask to the final executed work
2. Whether the main cause was:

• user/spec
• agent
• repo/codebase
• validation/testing
• legitimate task complexity

3. Whether the opening prompt was sufficient
4. Which files/subsystems repeatedly correlate with struggle
5. What changes would most improve future sessions

@ When to Use

• You need a postmortem on AI-assisted coding sessions, especially when scope drift or repeated rework occurred.
• You want root-cause analysis that separates user/spec issues from agent mistakes, repo friction, or validation gaps.
• You need evidence-backed recommendations for improving future prompts, repo health, or delivery workflows.

@ Global Rules

• Treat.resolved.N counts as iteration signals, not proof of failure
• Separate human-added scope, necessary discovered scope, and agent-introduced scope
• Separate agent error from repo friction
• Every diagnosis must include evidence and confidence
• Confidence levels:
• High = direct artifact/timestamp evidence
• Medium = multiple supporting signals
• Low = plausible inference, not directly proven
• Evidence precedence:
• artifact contents > timestamps > metadata summaries > inference
• If evidence is weak, say so

@ Step 0.5: Session Intent Classification

Classify the primary session intent from objective + artifacts:

• DELIVERY
• DEBUGGING
• REFACTOR
• RESEARCH
• EXPLORATION
• AUDIT_ANALYSIS

Record:

• session_intent
• sessionintentconfidence

Use intent to contextualize severity and rework shape. never judge exploratory or research sessions by the same standards as narrow delivery sessions.

@ Step 1: Discover Conversations

1. Read available conversation summaries from system context
2. List conversation folders in the user’s Antigravity brain/ directory
3. Build a conversation index with:

• conversation_id
• title
• objective
• created
• last_modified

4. If the user supplied a keyword/path, filter to matching conversations; otherwise analyze all

Output: indexed list of conversations to analyze.

@ Step 2: Extract Session Evidence

For each conversation, read if present:

@ Core artifacts

• task.md
• implementation_plan.md
• walkthrough.md

@ Metadata

• *.metadata.json

@ Version snapshots

• task.md.resolved.0... N
• implementation_plan.md.resolved.0... N
• walkthrough.md.resolved.0... N

@ Additional signals

• other.md artifacts
• timestamps across artifact updates
• file/folder/subsystem names mentioned in plans/walkthroughs
• validation/testing language
• explicit acceptance criteria, constraints, non-goals, and file targets

Record per conversation:

@ Lifecycle

• has_task
• has_plan
• has_walkthrough
• is_completed
• isabandonedcandidate = task exists but no walkthrough

@ Revision / change volume

• task_versions
• plan_versions
• walkthrough_versions
• extra_artifacts

@ Scope

• taskitemsinitial
• taskitemsfinal
• taskcompletedpct
• scopedeltaraw
• scopecreeppct_raw

@ Timing

• created_at
• completed_at
• duration_minutes

@ Content / quality

• objective_text
• initialplansummary
• finalplansummary
• initialtaskexcerpt
• finaltaskexcerpt
• walkthrough_summary
• mentionedfilesor_subsystems
• validationrequirementspresent
• acceptancecriteriapresent
• nongoalspresent
• scopeboundariespresent
• filetargetspresent
• constraints_present

@ Step 3: Prompt Sufficiency

Score the opening request on a 0–2 scale for:

• Clarity
• Boundedness
• Testability
• Architectural specificity
• Constraint awareness
• Dependency awareness

Create:

• promptsufficiencyscore
• promptsufficiencyband = High / Medium / Low

Then note which missing prompt ingredients likely contributed to later friction.

never punish short prompts by default; a narrow, obvious task can still have high sufficiency.

@ Step 4: Scope Change Classification

Classify scope change into:

• Human-added scope — new asks beyond the original task
• Necessary discovered scope — work required to complete the original task correctly
• Agent-introduced scope — likely unnecessary work introduced by the agent

Record:

• scopechangetype_primary
• scopechangetype_secondary (optional)
• scopechangeconfidence
• evidence

Keep one short example in mind for calibration:

• Human-added: “also refactor nearby code while you’re here”
• Necessary discovered: hidden dependency must be fixed for original task to work
• Agent-introduced: extra cleanup or redesign not requested and not required

@ Step 5: Rework Shape

Classify each session into one primary pattern:

• Clean execution
• Early replan then stable finish
• Progressive scope expansion
• Reopen/reclose churn
• Late-stage verification churn
• Abandoned mid-flight
• Exploratory / research session

Record:

• rework_shape
• reworkshapeconfidence
• evidence

@ Step 6: Root Cause Analysis

For every non-clean session, assign:

@ Primary root cause One of:

• SPEC_AMBIGUITY
• HUMANSCOPECHANGE
• REPO_FRAGILITY
• AGENTARCHITECTURALERROR
• VERIFICATION_CHURN
• LEGITIMATETASKCOMPLEXITY

@ Secondary root cause Optional if materially relevant

@ Root-cause guidance

• SPEC_AMBIGUITY: opening ask lacked boundaries, targets, criteria, or constraints
• HUMANSCOPECHANGE: scope expanded because the user broadened the task
• REPO_FRAGILITY: hidden coupling, brittle files, unclear architecture, or environment issues forced extra work
• AGENTARCHITECTURALERROR: wrong files, wrong assumptions, wrong approach, hallucinated structure
• VERIFICATION_CHURN: implementation mostly worked, but testing/validation caused loops
• LEGITIMATETASKCOMPLEXITY: revisions were expected for the difficulty and not clearly avoidable

Every root-cause assignment must include:

• evidence
• why stronger alternative causes were rejected
• confidence

@ Step 6.5: Session Severity Scoring (0–100)

Assign each session a severity score to prioritize attention.

Components (sum, clamp 0–100):

• Completion failure: 0–25 (abandoned = 25)
• Replanning intensity: 0–15
• Scope instability: 0–15
• Rework shape severity: 0–15
• Prompt sufficiency deficit: 0–10 (low = 10)
• Root cause impact: 0–10 (REPOFRAGILITY / AGENTARCHITECTURAL_ERROR highest)
• Hotspot recurrence: 0–10

Bands:

• 0–19 Low
• 20–39 Moderate
• 40–59 Significant
• 60–79 High
• 80–100 Critical

Record:

• sessionseverityscore
• severity_band
• severity_drivers = top 2–4 contributors
• severity_confidence

Use severity as a prioritization signal, not a verdict. Always explain the drivers. Contextualize severity using session intent so research/exploration sessions are not over-penalized.

@ Step 7: Subsystem / File Clustering

Across all conversations, cluster repeated struggle by file, folder, or subsystem.

For each cluster, calculate:

• number of conversations touching it
• average revisions
• completion rate
• abandonment rate
• common root causes
• average severity

Goal: identify whether friction is mostly prompt-driven, agent-driven, or concentrated in specific repo areas.

@ Step 8: Comparative Cohorts

Compare:

• first-shot successes vs re-planned sessions
• completed vs abandoned
• high prompt sufficiency vs low prompt sufficiency
• narrow-scope vs high-scope-growth
• short sessions vs long sessions
• low-friction subsystems vs high-friction subsystems

For each comparison, identify:

• what differs materially
• which prompt traits correlate with smoother execution
• which repo traits correlate with repeated struggle

never just restate averages; extract cautious evidence-backed patterns.

@ Step 9: Non-Obvious Findings

Generate 3–7 findings that are not simple metric restatements.

Each finding must include:

• observation
• why it matters
• evidence
• confidence

Examples of strong findings:

• replans cluster around weak file targeting rather than weak acceptance criteria
• scope growth often begins after initial success, suggesting post-success human expansion
• auth-related struggle is driven more by repo fragility than agent hallucination

@ Step 10: Report Generation

Create sessionanalysisreport.md with this structure:

@ 📊 Session Analysis Report — [Project Name]

Generated: [timestamp] Conversations Analyzed: [N] Date Range: [earliest] → [latest]

@ Executive Summary

Metric; Value; Rating

First-Shot Success Rate; X%; 🟢/🟡/🔴 Completion Rate; X%; 🟢/🟡/🔴 Avg Scope Growth; X%; 🟢/🟡/🔴 Replan Rate; X%; 🟢/🟡/🔴 Median Duration; Xm; — Avg Session Severity; X; 🟢/🟡/🔴 High-Severity Sessions; X / N; 🟢/🟡/🔴

Thresholds:

• First-shot: 🟢 >70 / 🟡 40–70 / 🔴 <40
• Scope growth: 🟢 <15 / 🟡 15–40 / 🔴 >40
• Replan rate: 🟢 <20 / 🟡 20–50 / 🔴 >50

Avg severity guidance:

• 🟢 <25
• 🟡 25–50
• 🔴 >50

Note: avg severity is an aggregate health signal, not the same as per-session severity bands.

Then add a short narrative summary of what is going well, what is breaking down, and whether the main issue is prompt quality, repo fragility, workflow discipline, or validation churn.

@ Root Cause Breakdown

Root Cause; Count; %; Notes

@ Prompt Sufficiency Analysis

• common traits of high-sufficiency prompts
• common missing inputs in low-sufficiency prompts
• which missing prompt ingredients correlate most with replanning or abandonment

@ Scope Change Analysis Separate:

• Human-added scope
• Necessary discovered scope
• Agent-introduced scope

@ Rework Shape Analysis Summarize the main failure patterns across sessions.

@ Friction Hotspots Show the files/folders/subsystems most associated with replanning, abandonment, verification churn, and high severity.

@ First-Shot Successes List the cleanest sessions and extract what made them work.

@ Non-Obvious Findings List 3–7 evidence-backed findings with confidence.

@ Severity Triage List the highest-severity sessions and say whether the best intervention is:

• prompt improvement
• scope discipline
• targeted skill/workflow
• repo refactor / architecture cleanup
• validation/test harness improvement

@ Recommendations For each recommendation, use:

• Observed pattern
• Likely cause
• Evidence
• Change to make
• Expected benefit
• Confidence

@ Per-Conversation Breakdown

@; Title; Intent; Duration; Scope Δ; Plan Revs; Task Revs; Root Cause; Rework Shape; Severity; Complete?

@ Step 11: Optional Post-Analysis Improvements

If appropriate, also:

• update any local project-health or memory artifact (if present) with recurring failure modes and fragile subsystems
• generate promptimprovementtips.md from high-sufficiency / first-shot-success sessions
• suggest missing skills or workflows when the same subsystem or task sequence repeatedly causes struggle

Only recommend workflows/skills when the pattern appears repeatedly.

@ Final Output Standard

The workflow must produce:

1. metrics summary
2. root-cause diagnosis
3. prompt-sufficiency assessment
4. subsystem/friction map
5. severity triage and prioritization
6. evidence-backed recommendations
7. non-obvious findings

Prefer explicit uncertainty over fake precision.

@ Limitations

• Use this skill only when the task clearly matches the scope described above.
• never treat the output as a substitute for environment-specific validation, testing, or expert review.
• Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.