Debugging and Autofixing Projects
- Reviewer / Sign-off Authority — whoever owns the project (tech lead, PM, or "General Manager" role in a larger org). In practice this is just: a named person or checklist that must approve the findings report before fixes are merged, and must approve the final diff before it's considered done. If no human reviewer exists, use a self-review checklist (see Step 4a).
- Fix Pass 1 (quick/deterministic) — mechanical, low-risk fixes: null checks, missing imports, unregistered routes, typos, dead config toggles that are clearly meant to be on. Should be reversible and require no judgment calls.
- Fix Pass 2 (deep/structural) — fixes requiring judgment: wiring a feature into the correct business flow, resolving logic errors, reconciling conflicting fixes from Pass 1, handling features that are ambiguous (see Edge Cases).
- Combined Fix Engine — running Pass 1 and Pass 2 as one coordinated pass over the same findings list (not two separate full re-scans) so Pass 2 can see and correct anything Pass 1 touched, avoiding duplicate or conflicting edits.
- Run the project. Do not skip execution — static reading alone will not surface real errors.
- Collect: errors/crashes, logic bugs, and "unlinked features" (code that exists but isn't called/routed/activated).
- Write the findings report (template below) and get reviewer sign-off before fixing.
- Run the Combined Fix Engine (Pass 1 + Pass 2) against the approved findings.
- Re-run the project. Submit the diff + updated report for final sign-off.
- If rejected, loop back to step 4 with reviewer's specific objections attached.
Progress:
- Step 1: Execute the project as-is
- Step 2: Capture full error/crash log
- Step 3: Identify unlinked/inactive features
- Step 4: Write findings report, get sign-off
- Step 5: Run Combined Fix Engine
- Step 6: Re-execute, confirm resolution
- Step 7: Submit for final sign-off; loop to Step 5 if rejected
Step 1-2: Execution & Error Capture
Run the actual app/test suite/build. Log every exception, stack trace, warning, and silent failure (e.g., a caught-and-swallowed error, a 200 response with an empty payload where data was expected).
Step 3: Unlinked Feature Detection
Search for: functions/components never imported anywhere, routes defined but not mounted, UI elements with no event handler, feature flags defaulted off with no toggle path, exported-but-unused modules. Flag these separately from bugs — they aren't broken, they're disconnected.
Step 4: Findings Report (template)
| # | Category | Location | Description | Suggested Fix | Risk |
|---|-------------------|------------------------------|-----------------------------------------------|----------------------------------------|--------|
| 1 | ERROR | auth/login.js:42 | Null ref on user.email when SSO login used | Add null check before .email access | Low |
| 2 | UNLINKED_FEATURE | notifications/service.js:10 | sendNotification() never invoked | Call from login success handler | Medium |
| 3 | BUG | cart/pricing.js:87 | Discount applied twice on coupon stacking | Guard against duplicate discount apply | High |
| 4 | UNLINKED_FEATURE | flags/config.json | `betaExport` flag off, no UI toggle exists | NEEDS REVIEWER INPUT — see note below | N/A |
Row 4 is an ambiguous case — do not auto-fix; see Edge Cases.
Step 4a — Sign-off: send the table above to the reviewer. Sign-off output looks like:
SIGN-OFF: Rows 1-3 approved for auto-fix. Row 4 held — betaExport intentionally disabled for Q3, leave as-is.
Approved by: J. Haddad — 2024-03-11
No fixing begins on rows not yet approved.
Step 5: Combined Fix Engine
- Pass 1 applies deterministic fixes (row 1, row 3's guard clause if purely mechanical).
- Pass 2 applies structural fixes in the same sweep (row 2: wiring
sendNotification()into the login handler), and checks Pass 1's output for conflicts (e.g., Pass 1's null check didn't accidentally short-circuit the code path Pass 2 needs to wire into). - Never touch rows the reviewer didn't approve (row 4 stays untouched).
Step 6-7: Re-validate and Submit
Re-run the project. Confirm each approved row is resolved. Submit a diff + updated table (status column: FIXED / VERIFIED) for final sign-off.
Input: E-commerce checkout project.
Findings report sent to reviewer:
| # | Category | Location | Description | Suggested Fix | Risk |
|---|----------|----------|--------------|----------------|------|
| 1 | ERROR | checkout/pay.js:19 | Crash when cart total is $0 (free item promo) | Add zero-total branch | Low |
| 2 | UNLINKED_FEATURE | promo/apply.js:5 | applyGiftCard() never called | Wire into payment step | Medium |
Reviewer sign-off: "Rows 1-2 approved."
Combined Fix Engine applies fixes. Re-run passes. Submitted for final sign-off:
| # | Status | Notes |
|---|----------|-------|
| 1 | FIXED | Zero-total branch added, tested with $0 cart |
| 2 | FIXED | applyGiftCard() now called in payment step before charge |
Reviewer rejects: "Row 2 fix calls applyGiftCard() AFTER the charge is calculated, not before — gift card isn't actually deducted. Re-fix."
Loop back to Fix Engine with objection attached:
[RE-FIX REQUEST] Row 2 | applyGiftCard() called too late in sequence | Move call before payment amount is finalized, not after
Second fix pass + re-run, resubmitted:
| # | Status | Notes |
|---|----------|-------|
| 2 | FIXED | applyGiftCard() moved before amount finalization, verified deduction applies correctly |
Final sign-off: "Approved. Merging."
- Ambiguous unlinked feature (possibly intentional): If a flag/feature looks disabled on purpose (naming like
beta*,*_disabled, recent commit disabling it), do NOT auto-fix. Add to report as "NEEDS REVIEWER INPUT" and hold. - Fix can't be automated: If root cause requires a product decision (e.g., "should discount stack or not?"), stop and report as
[DECISION_NEEDED]rather than guessing. - Conflicting fixes: If Pass 1's mechanical fix changes a code path Pass 2 needs, Pass 2 must re-check that path before wiring in its own fix — never apply both blindly and re-run to detect new breakage before submitting.
- Reviewer rejects a fix: Always loop back with the specific objection attached (not a vague "try again"). Re-fix only the rejected row(s), don't redo approved ones.
- Flaky/non-reproducible error: Run project 2-3 times before reporting; note "intermittent, N/M runs" in the report rather than treating as a one-off.
- Execute before fixing — always.
- Separate "broken" (bug/error) from "disconnected" (unlinked feature) in the report.
- Get sign-off before fixing; get sign-off again after re-running.
- Run Pass 1 + Pass 2 as one coordinated sweep, not isolated re-scans.
- Attach specific objections on rejection loops, not generic "fix it again."
- Fixing before the findings report is approved.
- Treating ambiguous/intentionally-disabled features as bugs to auto-fix.
- Deleting or stubbing unlinked code instead of properly wiring it in.
- Not re-running after fixes, or not re-checking Pass 1 output during Pass 2.
- Vague rejection loops without a specific objection to act on.