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
- Inspect dirty work first:
git status --short. Do not reset, checkout, or overwrite user changes.
- 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.
- Map version names to concrete git refs: tags, branch names, release commits, package versions, or changelog headings.
- 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>.
- 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:
- Database migrations, schema, queries, ORM models, RLS/policies.
- Identity/session boundaries, only when the diff or user pain points there.
- Deployment/runtime config, build output assumptions, redirects, rewrites.
- Storage buckets, upload/download rules, signed URL code.
- API contracts, background jobs, queues, scheduled tasks, and external event delivery.
- UI changes that consume changed contracts.
Risk Map
Create a Risk Map before editing:
| Signal |
Why It Matters |
| Migration without matching app query update |
Code may expect old schema or policy behavior |
| Identity/provider behavior changed with no release note |
The break may be outside the edited component |
| Package or SDK version changed |
Behavior may differ without app code changes |
| Deployment config changed |
Local success may not match production |
| Changelog mentions rename, cleanup, or refactor |
High chance of hidden contract break |
Fix Plan
Only after the Evidence Packet and Risk Map:
- State the most likely version that introduced the issue.
- State the smallest code or config change to test first.
- Protect provider boundaries: do not claim database, deployment, billing, storage, identity, or other dashboard state was fixed by repo edits alone.
- Add or run the narrowest verification that proves the version-control theory, such as a focused test, migration check, route test, or build.
- 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.
1---2name: what-broke3description: Use when an AI agent needs to stop guessing, find which version broke an app, compare releases, read git tags/diffs/changelogs, and connect the code change to provider context such as database, storage, deployment, and external runtime behavior before editing.4---56# What Broke78Use 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.910## First Pass11121. Inspect dirty work first: `git status --short`. Do not reset, checkout, or overwrite user changes.132. Identify the comparison range:14 - Prefer explicit known-good and known-bad versions from the user.15 - Otherwise infer from `git tag --sort=-creatordate`, `git log --oneline --decorate -n 40`, package versions, release branches, and CHANGELOG entries.163. Map version names to concrete git refs: tags, branch names, release commits, package versions, or changelog headings.174. 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>`.185. 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.1920## Evidence Packet2122Before proposing code changes, produce a short packet:2324- **Range:** good ref, bad/current ref, confidence, and why that range was chosen.25- **Version name:** semantic version, release name, tag, changelog heading, or "unknown".26- **Changed surface:** the files or modules that changed, grouped by app code, database, storage, deployment, provider SDK/setup, and external runtime behavior.27- **Provider context:** what provider-dependent behavior may have changed. Say when dashboard or runtime state is not verifiable from the repo.28- **What broke path:** the smallest chain from version change to observed breakage.29- **Missing evidence:** anything needed from logs, provider dashboards, release notes, or the user.3031## Smart Diff Workflow3233Use the cheapest command that answers the next question:3435```bash36git status --short37git tag --sort=-creatordate38git log --oneline --decorate -n 4039git diff <good>..<bad> --stat40git diff <good>..<bad> --name-only41git log --oneline -- <path>42git show --stat <commit>43git show <commit> -- <path>44```4546When many files changed, rank by production risk first:47481. Database migrations, schema, queries, ORM models, RLS/policies.492. Identity/session boundaries, only when the diff or user pain points there.503. Deployment/runtime config, build output assumptions, redirects, rewrites.514. Storage buckets, upload/download rules, signed URL code.525. API contracts, background jobs, queues, scheduled tasks, and external event delivery.536. UI changes that consume changed contracts.5455## Risk Map5657Create a Risk Map before editing:5859| Signal | Why It Matters |60| --- | --- |61| Migration without matching app query update | Code may expect old schema or policy behavior |62| Identity/provider behavior changed with no release note | The break may be outside the edited component |63| Package or SDK version changed | Behavior may differ without app code changes |64| Deployment config changed | Local success may not match production |65| Changelog mentions rename, cleanup, or refactor | High chance of hidden contract break |6667## Fix Plan6869Only after the Evidence Packet and Risk Map:70711. State the most likely version that introduced the issue.722. State the smallest code or config change to test first.733. Protect provider boundaries: do not claim database, deployment, billing, storage, identity, or other dashboard state was fixed by repo edits alone.744. Add or run the narrowest verification that proves the version-control theory, such as a focused test, migration check, route test, or build.755. If evidence is weak, ask for the missing release/log/provider detail instead of guessing.7677## Common Mistakes7879- Do not infer the breaking version from file timestamps alone.80- Do not compare the whole repo when a narrower good/bad range exists.81- Do not treat a package version bump as harmless; read its surrounding code changes.82- Do not collapse provider context into generic "config changed" language. Name the database, storage, deployment, or external runtime behavior that could be affected.83- Do not rewrite broad areas while investigating a version regression. Patch the smallest surface that matches the diff evidence.
ohad6k