Focused Fix — Deep-Dive Feature Repair

When to Use

Activate when the user asks to fix, debug, or make a specific feature/module/area work. Key triggers:

• "make X work"

• "fix the Y feature"

• "the Z module is broken"

• "focus on [area]"

• "this feature needs to work properly"

This is NOT for quick single-bug fixes (use systematic-debugging for that). This is for when an entire feature or module needs systematic repair — tracing every dependency, reading logs, checking tests, mapping the full dependency graph.

digraph when_to_use {

    "User reports feature broken" [shape=diamond];

    "Single bug or symptom?" [shape=diamond];

    "Use systematic-debugging" [shape=box];

    "Entire feature/module needs repair?" [shape=diamond];

    "Use focused-fix" [shape=box];

    "Something else" [shape=box];



    "User reports feature broken" -> "Single bug or symptom?";

    "Single bug or symptom?" -> "Use systematic-debugging" [label="yes"];

    "Single bug or symptom?" -> "Entire feature/module needs repair?" [label="no"];

    "Entire feature/module needs repair?" -> "Use focused-fix" [label="yes"];

    "Entire feature/module needs repair?" -> "Something else" [label="no"];

}

The Iron Law

NO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST

If you haven't finished Phase 3, you cannot propose fixes. Period.

Violating the letter of these phases is violating the spirit of focused repair.

Protocol — STRICTLY follow these 5 phases IN ORDER

digraph phases {

    rankdir=LR;

    SCOPE [shape=box, label="Phase 1\nSCOPE"];

    TRACE [shape=box, label="Phase 2\nTRACE"];

    DIAGNOSE [shape=box, label="Phase 3\nDIAGNOSE"];

    FIX [shape=box, label="Phase 4\nFIX"];

    VERIFY [shape=box, label="Phase 5\nVERIFY"];



    SCOPE -> TRACE -> DIAGNOSE -> FIX -> VERIFY;

    FIX -> DIAGNOSE [label="fix broke\nsomething else"];

    FIX -> ESCALATE [label="3+ fixes\ncreate new issues"];

    ESCALATE [shape=doubleoctagon, label="STOP\nQuestion Architecture\nDiscuss with User"];

}

Phase 1: SCOPE — Map the Feature Boundary

Before touching any code, understand the full scope of the feature.

1. Ask the user: "Which feature/folder should I focus on?" if not already clear

2. Identify the PRIMARY folder/files for this feature

3. Map EVERY file in that folder — read each one, understand its purpose

4. Create a feature manifest:

FEATURE SCOPE:

  Primary path: src/features/auth/

  Entry points: [files that are imported by other parts of the app]

  Internal files: [files only used within this feature]

  Total files: N

  Total lines: N

Phase 2: TRACE — Map All Dependencies (Inside AND Outside)

Trace every connection this feature has to the rest of the codebase.

INBOUND (what this feature imports):

1. For every import statement in every file in the feature folder:

   • Trace it to its source

   • Verify the source file exists

   • Verify the imported entity (function, type, component) exists and is exported

   • Check if the types/signatures match what the feature expects

2. Check for:

   • Environment variables used (grep for process.env, import.meta.env, os.environ, etc.)

   • Config files referenced

   • Database models/schemas used

   • API endpoints called

   • Third-party packages imported

OUTBOUND (what imports this feature):

1. Search the entire codebase for imports from this feature folder

2. For each consumer:

   • Verify they're importing entities that actually exist

   • Check if they're using the correct API/interface

   • Note if any consumers are using deprecated patterns

Output format:

DEPENDENCY MAP:

  Inbound (this feature depends on):

    src/lib/db.ts → used in auth/repository.ts (getUserById, createUser)

    src/lib/jwt.ts → used in auth/service.ts (signToken, verifyToken)

    @prisma/client → used in auth/repository.ts

    process.env.JWT_SECRET → used in auth/service.ts

    process.env.DATABASE_URL → used via prisma



  Outbound (depends on this feature):

    src/app/api/login/route.ts → imports { login } from auth/service

    src/app/api/register/route.ts → imports { register } from auth/service

    src/middleware.ts → imports { verifyToken } from auth/service



  Env vars required: JWT_SECRET, DATABASE_URL

  Config files: prisma/schema.prisma (User model)

Phase 3: DIAGNOSE — Find Every Issue

Systematically check for problems. Run ALL of these checks:

CODE QUALITY:

• Every import resolves to a real file/export

• No circular dependencies within the feature

• Types are consistent across boundaries (no any at interfaces)

• Error handling exists for all async operations

• No TODO/FIXME/HACK comments indicating known issues

RUNTIME:

• All required environment variables are set (check .env)

• Database migrations are up to date (if applicable)

• API endpoints return expected shapes

• No hardcoded values that should be configurable

TESTS:

• Run ALL tests related to this feature: find them by searching for imports from the feature folder

• Record every failure with full error output

• Check test coverage — are there untested code paths?

LOGS & ERRORS:

• Search for any log files, error reports, or Sentry-style error tracking

• Check git log for recent changes to this feature: git log --oneline -20 -- <feature-path>

• Check if any recent commits might have broken something: git log --oneline -5 --all -- <files that this feature depends on>

CONFIGURATION:

• Verify all config files this feature depends on are valid

• Check for mismatches between development and production configs

• Verify third-party service credentials are valid (if testable)

ROOT-CAUSE CONFIRMATION:

For each CRITICAL issue found, confirm root cause before adding it to the fix list:

• State clearly: "I think X is the root cause because Y"

• Trace the data/control flow backward to verify — don't trust surface-level symptoms

• If the issue spans multiple components, add diagnostic logging at each boundary to identify which layer fails

• REQUIRED SUB-SKILL: For complex bugs found during diagnosis, apply systematic-debugging Phase 1 (Root Cause Investigation) to confirm before proceeding

RISK LABELING:

Assign each issue a risk label:

| Risk | Criteria |

|---|---|

| HIGH | Public API surface / breaking interface contract / DB schema / auth or security logic / widely imported module (>3 callers) / 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 |

Output format:

DIAGNOSIS REPORT:

  Issues found: N



  CRITICAL:

    1. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]

    2. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]



  WARNINGS:

    1. [MED] [file:line] — description of issue

    2. [LOW] [file:line] — description of issue



  TESTS:

    Ran: N tests

    Passed: N

    Failed: N

    [list each failure with one-line summary]

Phase 4: FIX — Repair Everything Systematically

Fix issues in this EXACT order:

1. DEPENDENCIES FIRST — fix broken imports, missing packages, wrong versions

2. TYPES SECOND — fix type mismatches at feature boundaries

3. LOGIC THIRD — fix actual business logic bugs

4. TESTS FOURTH — fix or create tests for each fix

5. INTEGRATION LAST — verify the feature works end-to-end with its consumers

Rules:

• Fix ONE issue at a time

• After each fix, run the related test to confirm it works

• If a fix breaks something else, STOP and re-evaluate (go back to DIAGNOSE)

• Keep a running log of every change made

• Never change code outside the feature folder without explicitly stating why

• Fix HIGH-risk issues before MED, MED before LOW

ESCALATION RULE — 3-Strike Architecture Check:

If 3+ fixes in this phase create NEW issues (not pre-existing ones), STOP immediately.

This pattern indicates an architectural problem, not a bug collection:

• Each fix reveals new shared state / coupling / problem in a different place

• Fixes require "massive refactoring" to implement

• Each fix creates new symptoms elsewhere

Action: Stop fixing. Tell the user: "3+ fixes have cascaded into new issues. This suggests the feature's architecture may need rethinking, not patching. Here's what I've found: [summary]. Should we continue fixing symptoms or discuss restructuring?"

Do NOT attempt fix #4 without this discussion.

Output after each fix:

FIX #1:

  File: auth/service.ts:45

  Issue: signToken called with wrong argument order

  Change: swapped (expiresIn, payload) to (payload, expiresIn)

  Test: auth.test.ts → PASSES

Phase 5: VERIFY — Confirm Everything Works

After all fixes are applied:

1. Run ALL tests in the feature folder — every single one must pass

2. Run ALL tests in files that IMPORT from this feature — must pass

3. Run the full test suite if available — check for regressions

4. If the feature has a UI, describe how to manually verify it

5. Summarize all changes made

Final output:

FOCUSED FIX COMPLETE:

  Feature: auth

  Files changed: 4

  Total fixes: 7

  Tests: 23/23 passing

  Regressions: 0



  Changes:

    1. auth/service.ts — fixed token signing argument order

    2. auth/repository.ts — added null check for user lookup

    3. auth/middleware.ts — fixed async error handling

    4. auth/types.ts — aligned UserResponse type with actual DB schema



  Consumers verified:

    - src/app/api/login/route.ts ✅

    - src/app/api/register/route.ts ✅

    - src/middleware.ts ✅

Red Flags — STOP and Return to Current Phase

If you catch yourself thinking any of these, you are skipping phases:

• "I can see the bug, let me just fix it" → STOP. You haven't traced dependencies yet.

• "Scoping is overkill, it's obviously just this file" → STOP. That's always wrong for feature-level fixes.

• "I'll map dependencies after I fix the obvious stuff" → STOP. You'll miss root causes.

• "The user said fix X, so I only need to look at X" → STOP. Features have dependencies.

• "Tests are passing so I'm done" → STOP. Did you run consumer tests too?

• "I don't need to check env vars for this" → STOP. Config issues masquerade as code bugs.

• "One more fix should do it" (after 2+ cascading failures) → STOP. Escalate.

• "I'll skip the diagnosis report, the fixes are obvious" → STOP. Write it down.

ALL of these mean: Return to the phase you're supposed to be in.

Common Rationalizations

| Excuse | Reality |

|---|---|

| "The feature is small, I don't need all 5 phases" | Small features have dependencies too. Phases 1-2 take minutes for small features — do them. |

| "I already know this codebase" | Knowledge decays. Trace the 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 only one file were broken, the user would say "fix this bug", not "make the feature work." |

| "I fixed the tests, 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. That's exactly why you need it. |

| "Root cause is obvious, I don't need to confirm" | "Obvious" root causes are wrong 40% of the time. Confirm with evidence. |

| "3 cascading failures is normal for a big fix" | 3 cascading failures means you're patching symptoms of an architectural problem. |

Anti-Patterns — NEVER do these

| Anti-Pattern | Why It's Wrong |

|---|---|

| Starting to fix code before mapping all dependencies | You'll miss root causes and create whack-a-mole fixes |

| Fixing only the file the user mentioned | Related files likely have issues too |

| Ignoring environment variables and configuration | Many "code bugs" are actually config issues |

| Skipping the test run phase | You can't verify fixes without running tests |

| Making changes outside the feature folder without explaining why | Unexpected side effects confuse the user |

| Fixing symptoms in consumer files instead of root cause in feature | Band-aids that break when the next consumer appears |

| Declaring "done" without running verification tests | Untested fixes are unverified fixes |

| Changing the public API without updating all consumers | Breaks everything that depends on the feature |

Related Skills

• systematic-debugging — Use within Phase 3 for root-cause tracing of individual complex bugs

• verification-before-completion — Use within Phase 5 before claiming the feature is fixed

• scope — If you need to understand blast radius before starting, run scope first then focused-fix

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 |

Authorization and scope (merged from implement)

• Loading this skill is not permission to write by itself. The right

  to write is given by an authorized request or an approved plan.

• Do not expand scope silently. Any exit beyond the feature folder —

  with explicit notification to the user.