What Broke

Use this skill when the app worked before and the agent is about to patch blind. Find the version that changed behavior, recover the version/release context, explain what broke, and connect the code diff to provider reality: database, storage, deployment, and external runtime behavior.

First Pass

1. Inspect dirty work first: git status --short. Do not reset, checkout, or overwrite user changes.
2. Identify the comparison range:
   • Prefer explicit known-good and known-bad versions from the user.
   • Otherwise infer from git tag --sort=-creatordate, git log --oneline --decorate -n 40, package versions, release branches, and CHANGELOG entries.
3. Map version names to concrete git refs: tags, branch names, release commits, package versions, or changelog headings.
4. Build a narrow diff before editing: git diff <good>..<bad> --stat, then git diff <good>..<bad> --name-only, then focused git diff <good>..<bad> -- <path>.
5. Read provider-adjacent files touched in the range: migrations, schema files, storage policies, deployment config, provider SDK setup, seed data, and runtime boundary files. Add identity, billing, or event-delivery files only when the diff or user pain points there.

Evidence Packet

Before proposing code changes, produce a short packet:

• Range: good ref, bad/current ref, confidence, and why that range was chosen.
• Version name: semantic version, release name, tag, changelog heading, or "unknown".
• Changed surface: the files or modules that changed, grouped by app code, database, storage, deployment, provider SDK/setup, and external runtime behavior.
• Provider context: what provider-dependent behavior may have changed. Say when dashboard or runtime state is not verifiable from the repo.
• What broke path: the smallest chain from version change to observed breakage.
• Missing evidence: anything needed from logs, provider dashboards, release notes, or the user.

Smart Diff Workflow

Use the cheapest command that answers the next question:

git status --short
git tag --sort=-creatordate
git log --oneline --decorate -n 40
git diff <good>..<bad> --stat
git diff <good>..<bad> --name-only
git log --oneline -- <path>
git show --stat <commit>
git show <commit> -- <path>

When many files changed, rank by production risk first:

1. Database migrations, schema, queries, ORM models, RLS/policies.
2. Identity/session boundaries, only when the diff or user pain points there.
3. Deployment/runtime config, build output assumptions, redirects, rewrites.
4. Storage buckets, upload/download rules, signed URL code.
5. API contracts, background jobs, queues, scheduled tasks, and external event delivery.
6. UI changes that consume changed contracts.

Risk Map

Create a Risk Map before editing:

Fix Plan

Only after the Evidence Packet and Risk Map:

1. State the most likely version that introduced the issue.
2. State the smallest code or config change to test first.
3. Protect provider boundaries: do not claim database, deployment, billing, storage, identity, or other dashboard state was fixed by repo edits alone.
4. Add or run the narrowest verification that proves the version-control theory, such as a focused test, migration check, route test, or build.
5. If evidence is weak, ask for the missing release/log/provider detail instead of guessing.

Common Mistakes

• Do not infer the breaking version from file timestamps alone.
• Do not compare the whole repo when a narrower good/bad range exists.
• Do not treat a package version bump as harmless; read its surrounding code changes.
• Do not collapse provider context into generic "config changed" language. Name the database, storage, deployment, or external runtime behavior that could be affected.
• Do not rewrite broad areas while investigating a version regression. Patch the smallest surface that matches the diff evidence.