1# Crash Fix
 2
 3You are fixing a crash that has been analyzed and has a reproduction test case. Your goal is to implement a minimal, correct fix that resolves the root cause and makes the reproduction test pass.
 4
 5## Inputs
 6
 7Before starting, you should have:
 8
 91. **ANALYSIS.md** — the crash analysis from the investigation phase. Read it thoroughly.
102. **A failing test** — a reproduction test that triggers the crash. Run it first to confirm it fails as expected.
11
12If either is missing, ask the user to provide them or run the investigation phase first (`/prompt crash/investigate`).
13
14## Workflow
15
16### Step 1: Confirm the Failing Test
17
18Run the reproduction test and verify it fails with the expected crash:
19
20```
21cargo test -p <crate> <test_name>
22```
23
24Read the failure output. Confirm the panic message and stack trace match what ANALYSIS.md describes. If the test doesn't fail, or fails differently than expected, stop and reassess before proceeding.
25
26### Step 2: Understand the Fix
27
28Read the "Suggested Fix" section of ANALYSIS.md and the relevant source code. Before writing any code, be clear on:
29
301. **What invariant is being violated** — what property of the data does the crashing code assume?
312. **Where the invariant breaks** — which function produces the bad state?
32
33### Step 3: Implement the Fix
34
35Apply the minimal change needed to resolve the root cause. Guidelines:
36
37- **Fix the root cause, not the symptom.** Don't just catch the panic with a bounds check if the real problem is an incorrect offset calculation. Fix the calculation.
38- **Preserve existing behavior** for all non-crashing cases. The fix should only change what happens in the scenario that was previously crashing.
39- **Don't add unnecessary changes.** No drive-by improvements, keep the diff focused.
40- **Add a comment only if the fix is non-obvious.** If a reader might wonder "why is this check here?", a brief comment explaining the crash scenario is appropriate.
41- **Consider long term maintainability** Please make a targeted fix while being sure to consider the long term maintainability and reliability of the codebase
42
43### Step 4: Verify the Fix
44
45Run the reproduction test and confirm it passes:
46
47```
48cargo test -p <crate> <test_name>
49```
50
51Then run the full test suite for the affected crate to check for regressions:
52
53```
54cargo test -p <crate>
55```
56
57If any tests fail, determine whether the fix introduced a regression. Fix regressions before proceeding.
58
59### Step 5: Run Clippy
60
61```
62./script/clippy
63```
64
65Address any new warnings introduced by your change.
66
67### Step 6: Summarize
68
69Write a brief summary of the fix for use in a PR description. Include:
70
71- **What was the bug** — one sentence on the root cause.
72- **What the fix does** — one sentence on the change.
73- **How it was verified** — note that the reproduction test now passes.
74- **Sentry issue link** — if available from ANALYSIS.md.
75
76We use the following template for pull request descriptions. Please add information to answer the relevant sections, especially for release notes.
77
78```
79<Description of change, what the issue was and the fix.>
80
81Release Notes:
82
83- N/A *or* Added/Fixed/Improved ...
84```