focused-fix

---
name: focused-fix
description: Use when the user asks to fix, debug, or make a whole feature/module work end-to-end, not a quick single-bug fix. Triggers: "make X work", "fix the Y feature", "the Z module is broken".
category: Engineering
version: 1.0.0
tools: []
---

# Focused Fix — Deep-Dive Feature Repair

## When to use
Apply this when asked to fix, debug, or make a specific feature/module/area work — not for a quick single-bug fix (use systematic-debugging practice for that instead). Triggers: "make X work", "fix the Y feature", "the Z module is broken", "focus on [area]". This is for when an entire feature or module needs systematic repair: tracing every dependency, checking tests, mapping the full dependency graph — not just patching the one obviously-wrong line.

## The iron law
No fixes without completing Scope → Trace → Diagnose first. If Phase 3 isn't finished, do not propose fixes. Violating the letter of these phases violates the spirit of focused repair.

## Phase 1 — Scope: map the feature boundary
Before touching anything, confirm which feature/folder to focus on if it isn't already clear. Identify the primary files for the feature and read every one of them, distinguishing entry points (files other parts of the app import) from internal-only files. Produce a feature manifest: primary path, entry points, internal files, file/line counts.

## Phase 2 — Trace: map all dependencies, inbound and outbound
**Inbound** — for every import in every file in the feature: trace it to its source, confirm the source exists, confirm the imported function/type/component exists and is exported, and check that types/signatures match what the feature expects. Also identify environment variables, config files, database models/schemas, API endpoints, and third-party packages the feature relies on.

**Outbound** — find every place elsewhere in the codebase that imports from this feature, and for each consumer verify it's using entities that actually exist, using the correct interface, and not relying on a deprecated pattern.

Produce a dependency map: inbound dependencies (what the feature needs, with specific functions used), outbound consumers (what depends on the feature), required env vars, and relevant config files.

## Phase 3 — Diagnose: find every issue
Check systematically across five areas:
- **Code quality** — imports resolve, no circular dependencies, no untyped boundaries, async operations have error handling, no unresolved TODO/FIXME/HACK markers
- **Runtime** — required env vars are set, migrations are current, API responses match expected shapes, no hardcoded values that should be configurable
- **Tests** — run every test tied to the feature, record failures with full output, note untested code paths
- **Logs & history** — check error tracking/logs and recent change history for the feature and anything it depends on
- **Configuration** — validate config files the feature depends on, check dev/prod mismatches, verify third-party credentials where testable

For each critical issue, confirm root cause before listing it as a fix candidate: state the hypothesis and why, trace the data/control flow backward rather than trusting the surface symptom, and for complex, multi-component bugs add diagnostic checks at each boundary to isolate which layer fails. "Obvious" root causes are wrong roughly 40% of the time — confirm with evidence before proceeding.

Label every issue's risk:

| Risk | Criteria |
|---|---|
| HIGH | Public API surface, breaking interface contract, DB schema, auth/security logic, module imported by more than 3 callers, or a git hotspot |
| MED | Internal module with tests, shared utility, config with runtime impact, internal callers of changed functions |
| LOW | Leaf module, isolated file, test-only change, single-purpose helper with no callers |

Produce a diagnosis report: total issues found, critical issues with file/line/root cause, warnings, and test pass/fail counts with failure summaries.

## Phase 4 — Fix: repair systematically, in order
Fix in this exact order: dependencies first (broken imports, missing packages, wrong versions) → types second (mismatches at feature boundaries) → logic third (actual business-logic bugs) → tests fourth (fix or create tests per fix) → integration last (verify the feature works end-to-end with consumers). Fix one issue at a time, confirm each with its related test, and if a fix breaks something else, stop and return to Diagnose. Never change code outside the feature folder without stating why. Fix HIGH-risk issues before MED, MED before LOW.

**3-strike escalation rule** — if 3 or more fixes in this phase create new issues that weren't there before, stop immediately. That pattern indicates an architectural problem, not a bug collection: each fix reveals new shared state or coupling elsewhere, needs "massive refactoring," or creates new symptoms. Tell the user the fixes have cascaded into new issues, summarize findings, and ask whether to keep patching symptoms or discuss restructuring. Do not attempt a 4th fix without that conversation.

Log each fix: file, issue, change made, and test result.

## Phase 5 — Verify: confirm everything works
Run every test in the feature folder — all must pass. Run every test in files that import from the feature — must pass. Run the full test suite if available, checking for regressions. If the feature has a UI, describe how to manually verify it. Summarize files changed, total fixes, test pass count, regressions, and confirm each consumer still works.

## Red flags — these thoughts mean you're skipping a phase
"I can see the bug, let me just fix it" · "Scoping is overkill, it's obviously just this file" · "I'll map dependencies after the obvious stuff" · "The user only mentioned X, so I only need to look at X" · "Tests are passing so I'm done" (did you run consumer tests?) · "I don't need to check env vars for this" · "One more fix should do it" after 2+ cascading failures · "I'll skip the diagnosis report, it's obvious." Each means: return to the phase you're supposed to be in.

## Common rationalizations vs. reality
| Excuse | Reality |
|---|---|
| "The feature is small, skip the phases" | Small features have dependencies too — Phases 1–2 take minutes for small features, so do them |
| "I already know this codebase" | Knowledge decays — trace actual imports, don't rely on memory |
| "The user wants speed, not process" | Skipping phases causes rework; systematic is faster than thrashing |
| "Only one file is broken" | If it were one file, the user would say "fix this bug," not "make the feature work" |
| "Tests pass, so it works" | Tests can pass while consumers are broken — verify Phase 5 fully |
| "The dependency map is too big to trace" | Then the feature is too big to fix without tracing |
| "Root cause is obvious" | Obvious root causes are wrong roughly 40% of the time — confirm with evidence |
| "3 cascading failures is normal" | It means you're patching symptoms of an architectural problem |

## Anti-patterns
Starting fixes before mapping dependencies; fixing only the file the user named while related files share the issue; ignoring environment variables and configuration (many "code bugs" are config issues); skipping the test-run phase; changing code outside the feature folder without explaining why; patching symptoms in consumer files instead of the root cause in the feature; declaring done without running verification; changing a public API without updating all consumers.

## Related practice
Use root-cause investigation practice within Phase 3 for individual complex bugs, and a verification-before-completion check within Phase 5 before declaring the feature fixed. If blast radius is unclear before starting, scope that out first, then run this protocol.

## Quick reference
| Phase | Key action | Output |
|---|---|---|
| Scope | Read every file, map entry points | Feature manifest |
| Trace | Map inbound + outbound dependencies | Dependency map |
| Diagnose | Check code, runtime, tests, logs, config | Diagnosis report |
| Fix | Fix in order: deps → types → logic → tests → integration | Fix log per issue |
| Verify | Run all tests, check consumers, summarize | Completion report |
</content>