Maps every file and dependency of the area before changing anything.
---name: "focused-fix"description: "Use when a whole feature or module is broken and needs fixing end to end ('make X work', 'the Y module is broken'). Maps every file and dependency of the area before changing anything. Single quick bug fixes do not need it."--- # 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. ```dotdigraph 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 ```dotdigraph 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 clear2. Identify the PRIMARY folder/files for this feature3. Map EVERY file in that folder — read each one, understand its purpose4. 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 expects2. 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 folder2. 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- For complex bugs, run a root-cause investigation before proceeding: reproduce the failure reliably, read the full error and stack trace, check what changed recently (`git log`, `git diff`), and form one hypothesis at a time that you test with the smallest possible change. Do not add a bug to the fix list until a hypothesis survives its test. **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 versions2. **TYPES SECOND** — fix type mismatches at feature boundaries3. **LOGIC THIRD** — fix actual business logic bugs4. **TESTS FOURTH** — fix or create tests for each fix5. **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 pass2. Run ALL tests in files that IMPORT from this feature — must pass3. Run the full test suite if available — check for regressions4. If the feature has a UI, describe how to manually verify it5. 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 - **`self-eval`** (this repo, `engineering/skills/self-eval`) — Use after Phase 5 to score the fix honestly before reporting it done- **`incident-commander`** (this repo, `engineering-team/skills/incident-commander`, separate plugin) — Use instead when the broken feature is a live production incident, not a local repair- **Optional, if installed:** the third-party `superpowers` plugin's `systematic-debugging` and `verification-before-completion` skills cover the same ground as the root-cause step in Phase 3 and the checks in Phase 5. This skill does not require them; the steps above are self-contained. ## 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 |