focused-fix

# 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.

```dot
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

```dot
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
- 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 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

- **`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 |

{
  "format": "aiskill/v1",
  "skill": {
    "name": "focused-fix",
    "slug": "focused-fix",
    "version": "1.0.0",
    "description": "Use when the user asks to fix, debug, or make a specific feature/module/area work end-to-end. Triggers: 'make X work', 'fix the Y feature', 'the Z module is broken', 'focus on [area]'. Not for quick single-bug fixes — this is for systematic deep-dive repair across all files and dependencies.",
    "category": "Development",
    "tags": [
      "dev-workflow"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "MIT"
  },
  "prompts": {
    "system": "# Focused Fix — Deep-Dive Feature Repair\r\n\r\n## When to Use\r\n\r\nActivate when the user asks to fix, debug, or make a specific feature/module/area work. Key triggers:\r\n- \"make X work\"\r\n- \"fix the Y feature\"\r\n- \"the Z module is broken\"\r\n- \"focus on [area]\"\r\n- \"this feature needs to work properly\"\r\n\r\nThis 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.\r\n\r\n```dot\r\ndigraph when_to_use {\r\n    \"User reports feature broken\" [shape=diamond];\r\n    \"Single bug or symptom?\" [shape=diamond];\r\n    \"Use systematic-debugging\" [shape=box];\r\n    \"Entire feature/module needs repair?\" [shape=diamond];\r\n    \"Use focused-fix\" [shape=box];\r\n    \"Something else\" [shape=box];\r\n\r\n    \"User reports feature broken\" -> \"Single bug or symptom?\";\r\n    \"Single bug or symptom?\" -> \"Use systematic-debugging\" [label=\"yes\"];\r\n    \"Single bug or symptom?\" -> \"Entire feature/module needs repair?\" [label=\"no\"];\r\n    \"Entire feature/module needs repair?\" -> \"Use focused-fix\" [label=\"yes\"];\r\n    \"Entire feature/module needs repair?\" -> \"Something else\" [label=\"no\"];\r\n}\r\n```\r\n\r\n## The Iron Law\r\n\r\n```\r\nNO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST\r\n```\r\n\r\nIf you haven't finished Phase 3, you cannot propose fixes. Period.\r\n\r\n**Violating the letter of these phases is violating the spirit of focused repair.**\r\n\r\n## Protocol — STRICTLY follow these 5 phases IN ORDER\r\n\r\n```dot\r\ndigraph phases {\r\n    rankdir=LR;\r\n    SCOPE [shape=box, label=\"Phase 1\\nSCOPE\"];\r\n    TRACE [shape=box, label=\"Phase 2\\nTRACE\"];\r\n    DIAGNOSE [shape=box, label=\"Phase 3\\nDIAGNOSE\"];\r\n    FIX [shape=box, label=\"Phase 4\\nFIX\"];\r\n    VERIFY [shape=box, label=\"Phase 5\\nVERIFY\"];\r\n\r\n    SCOPE -> TRACE -> DIAGNOSE -> FIX -> VERIFY;\r\n    FIX -> DIAGNOSE [label=\"fix broke\\nsomething else\"];\r\n    FIX -> ESCALATE [label=\"3+ fixes\\ncreate new issues\"];\r\n    ESCALATE [shape=doubleoctagon, label=\"STOP\\nQuestion Architecture\\nDiscuss with User\"];\r\n}\r\n```\r\n\r\n### Phase 1: SCOPE — Map the Feature Boundary\r\n\r\nBefore touching any code, understand the full scope of the feature.\r\n\r\n1. Ask the user: \"Which feature/folder should I focus on?\" if not already clear\r\n2. Identify the PRIMARY folder/files for this feature\r\n3. Map EVERY file in that folder — read each one, understand its purpose\r\n4. Create a feature manifest:\r\n\r\n```\r\nFEATURE SCOPE:\r\n  Primary path: src/features/auth/\r\n  Entry points: [files that are imported by other parts of the app]\r\n  Internal files: [files only used within this feature]\r\n  Total files: N\r\n  Total lines: N\r\n```\r\n\r\n### Phase 2: TRACE — Map All Dependencies (Inside AND Outside)\r\n\r\nTrace every connection this feature has to the rest of the codebase.\r\n\r\n**INBOUND (what this feature imports):**\r\n1. For every import statement in every file in the feature folder:\r\n   - Trace it to its source\r\n   - Verify the source file exists\r\n   - Verify the imported entity (function, type, component) exists and is exported\r\n   - Check if the types/signatures match what the feature expects\r\n2. Check for:\r\n   - Environment variables used (grep for process.env, import.meta.env, os.environ, etc.)\r\n   - Config files referenced\r\n   - Database models/schemas used\r\n   - API endpoints called\r\n   - Third-party packages imported\r\n\r\n**OUTBOUND (what imports this feature):**\r\n1. Search the entire codebase for imports from this feature folder\r\n2. For each consumer:\r\n   - Verify they're importing entities that actually exist\r\n   - Check if they're using the correct API/interface\r\n   - Note if any consumers are using deprecated patterns\r\n\r\nOutput format:\r\n```\r\nDEPENDENCY MAP:\r\n  Inbound (this feature depends on):\r\n    src/lib/db.ts → used in auth/repository.ts (getUserById, createUser)\r\n    src/lib/jwt.ts → used in auth/service.ts (signToken, verifyToken)\r\n    @prisma/client → used in auth/repository.ts\r\n    process.env.JWT_SECRET → used in auth/service.ts\r\n    process.env.DATABASE_URL → used via prisma\r\n\r\n  Outbound (depends on this feature):\r\n    src/app/api/login/route.ts → imports { login } from auth/service\r\n    src/app/api/register/route.ts → imports { register } from auth/service\r\n    src/middleware.ts → imports { verifyToken } from auth/service\r\n\r\n  Env vars required: JWT_SECRET, DATABASE_URL\r\n  Config files: prisma/schema.prisma (User model)\r\n```\r\n\r\n### Phase 3: DIAGNOSE — Find Every Issue\r\n\r\nSystematically check for problems. Run ALL of these checks:\r\n\r\n**CODE QUALITY:**\r\n- [ ] Every import resolves to a real file/export\r\n- [ ] No circular dependencies within the feature\r\n- [ ] Types are consistent across boundaries (no `any` at interfaces)\r\n- [ ] Error handling exists for all async operations\r\n- [ ] No TODO/FIXME/HACK comments indicating known issues\r\n\r\n**RUNTIME:**\r\n- [ ] All required environment variables are set (check .env)\r\n- [ ] Database migrations are up to date (if applicable)\r\n- [ ] API endpoints return expected shapes\r\n- [ ] No hardcoded values that should be configurable\r\n\r\n**TESTS:**\r\n- [ ] Run ALL tests related to this feature: find them by searching for imports from the feature folder\r\n- [ ] Record every failure with full error output\r\n- [ ] Check test coverage — are there untested code paths?\r\n\r\n**LOGS & ERRORS:**\r\n- [ ] Search for any log files, error reports, or Sentry-style error tracking\r\n- [ ] Check git log for recent changes to this feature: `git log --oneline -20 -- <feature-path>`\r\n- [ ] Check if any recent commits might have broken something: `git log --oneline -5 --all -- <files that this feature depends on>`\r\n\r\n**CONFIGURATION:**\r\n- [ ] Verify all config files this feature depends on are valid\r\n- [ ] Check for mismatches between development and production configs\r\n- [ ] Verify third-party service credentials are valid (if testable)\r\n\r\n**ROOT-CAUSE CONFIRMATION:**\r\nFor each CRITICAL issue found, confirm root cause before adding it to the fix list:\r\n- State clearly: \"I think X is the root cause because Y\"\r\n- Trace the data/control flow backward to verify — don't trust surface-level symptoms\r\n- If the issue spans multiple components, add diagnostic logging at each boundary to identify which layer fails\r\n- 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.\r\n\r\n**RISK LABELING:**\r\nAssign each issue a risk label:\r\n\r\n| Risk | Criteria |\r\n|---|---|\r\n| HIGH | Public API surface / breaking interface contract / DB schema / auth or security logic / widely imported module (>3 callers) / git hotspot |\r\n| MED | Internal module with tests / shared utility / config with runtime impact / internal callers of changed functions |\r\n| LOW | Leaf module / isolated file / test-only change / single-purpose helper with no callers |\r\n\r\nOutput format:\r\n```\r\nDIAGNOSIS REPORT:\r\n  Issues found: N\r\n\r\n  CRITICAL:\r\n    1. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]\r\n    2. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]\r\n\r\n  WARNINGS:\r\n    1. [MED] [file:line] — description of issue\r\n    2. [LOW] [file:line] — description of issue\r\n\r\n  TESTS:\r\n    Ran: N tests\r\n    Passed: N\r\n    Failed: N\r\n    [list each failure with one-line summary]\r\n```\r\n\r\n### Phase 4: FIX — Repair Everything Systematically\r\n\r\nFix issues in this EXACT order:\r\n\r\n1. **DEPENDENCIES FIRST** — fix broken imports, missing packages, wrong versions\r\n2. **TYPES SECOND** — fix type mismatches at feature boundaries\r\n3. **LOGIC THIRD** — fix actual business logic bugs\r\n4. **TESTS FOURTH** — fix or create tests for each fix\r\n5. **INTEGRATION LAST** — verify the feature works end-to-end with its consumers\r\n\r\nRules:\r\n- Fix ONE issue at a time\r\n- After each fix, run the related test to confirm it works\r\n- If a fix breaks something else, STOP and re-evaluate (go back to DIAGNOSE)\r\n- Keep a running log of every change made\r\n- Never change code outside the feature folder without explicitly stating why\r\n- Fix HIGH-risk issues before MED, MED before LOW\r\n\r\n**ESCALATION RULE — 3-Strike Architecture Check:**\r\nIf 3+ fixes in this phase create NEW issues (not pre-existing ones), STOP immediately.\r\n\r\nThis pattern indicates an architectural problem, not a bug collection:\r\n- Each fix reveals new shared state / coupling / problem in a different place\r\n- Fixes require \"massive refactoring\" to implement\r\n- Each fix creates new symptoms elsewhere\r\n\r\n**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?\"\r\n\r\nDo NOT attempt fix #4 without this discussion.\r\n\r\nOutput after each fix:\r\n```\r\nFIX #1:\r\n  File: auth/service.ts:45\r\n  Issue: signToken called with wrong argument order\r\n  Change: swapped (expiresIn, payload) to (payload, expiresIn)\r\n  Test: auth.test.ts → PASSES\r\n```\r\n\r\n### Phase 5: VERIFY — Confirm Everything Works\r\n\r\nAfter all fixes are applied:\r\n\r\n1. Run ALL tests in the feature folder — every single one must pass\r\n2. Run ALL tests in files that IMPORT from this feature — must pass\r\n3. Run the full test suite if available — check for regressions\r\n4. If the feature has a UI, describe how to manually verify it\r\n5. Summarize all changes made\r\n\r\nFinal output:\r\n```\r\nFOCUSED FIX COMPLETE:\r\n  Feature: auth\r\n  Files changed: 4\r\n  Total fixes: 7\r\n  Tests: 23/23 passing\r\n  Regressions: 0\r\n\r\n  Changes:\r\n    1. auth/service.ts — fixed token signing argument order\r\n    2. auth/repository.ts — added null check for user lookup\r\n    3. auth/middleware.ts — fixed async error handling\r\n    4. auth/types.ts — aligned UserResponse type with actual DB schema\r\n\r\n  Consumers verified:\r\n    - src/app/api/login/route.ts ✅\r\n    - src/app/api/register/route.ts ✅\r\n    - src/middleware.ts ✅\r\n```\r\n\r\n## Red Flags — STOP and Return to Current Phase\r\n\r\nIf you catch yourself thinking any of these, you are skipping phases:\r\n\r\n- \"I can see the bug, let me just fix it\" → STOP. You haven't traced dependencies yet.\r\n- \"Scoping is overkill, it's obviously just this file\" → STOP. That's always wrong for feature-level fixes.\r\n- \"I'll map dependencies after I fix the obvious stuff\" → STOP. You'll miss root causes.\r\n- \"The user said fix X, so I only need to look at X\" → STOP. Features have dependencies.\r\n- \"Tests are passing so I'm done\" → STOP. Did you run consumer tests too?\r\n- \"I don't need to check env vars for this\" → STOP. Config issues masquerade as code bugs.\r\n- \"One more fix should do it\" (after 2+ cascading failures) → STOP. Escalate.\r\n- \"I'll skip the diagnosis report, the fixes are obvious\" → STOP. Write it down.\r\n\r\n**ALL of these mean: Return to the phase you're supposed to be in.**\r\n\r\n## Common Rationalizations\r\n\r\n| Excuse | Reality |\r\n|---|---|\r\n| \"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. |\r\n| \"I already know this codebase\" | Knowledge decays. Trace the actual imports, don't rely on memory. |\r\n| \"The user wants speed, not process\" | Skipping phases causes rework. Systematic is faster than thrashing. |\r\n| \"Only one file is broken\" | If only one file were broken, the user would say \"fix this bug\", not \"make the feature work.\" |\r\n| \"I fixed the tests, so it works\" | Tests can pass while consumers are broken. Verify Phase 5 fully. |\r\n| \"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. |\r\n| \"Root cause is obvious, I don't need to confirm\" | \"Obvious\" root causes are wrong 40% of the time. Confirm with evidence. |\r\n| \"3 cascading failures is normal for a big fix\" | 3 cascading failures means you're patching symptoms of an architectural problem. |\r\n\r\n## Anti-Patterns — NEVER do these\r\n\r\n| Anti-Pattern | Why It's Wrong |\r\n|---|---|\r\n| Starting to fix code before mapping all dependencies | You'll miss root causes and create whack-a-mole fixes |\r\n| Fixing only the file the user mentioned | Related files likely have issues too |\r\n| Ignoring environment variables and configuration | Many \"code bugs\" are actually config issues |\r\n| Skipping the test run phase | You can't verify fixes without running tests |\r\n| Making changes outside the feature folder without explaining why | Unexpected side effects confuse the user |\r\n| Fixing symptoms in consumer files instead of root cause in feature | Band-aids that break when the next consumer appears |\r\n| Declaring \"done\" without running verification tests | Untested fixes are unverified fixes |\r\n| Changing the public API without updating all consumers | Breaks everything that depends on the feature |\r\n\r\n## Related Skills\r\n\r\n- **`self-eval`** (this repo, `engineering/skills/self-eval`) — Use after Phase 5 to score the fix honestly before reporting it done\r\n- **`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\r\n- **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.\r\n\r\n## Quick Reference\r\n\r\n| Phase | Key Action | Output |\r\n|---|---|---|\r\n| SCOPE | Read every file, map entry points | Feature manifest |\r\n| TRACE | Map inbound + outbound dependencies | Dependency map |\r\n| DIAGNOSE | Check code, runtime, tests, logs, config | Diagnosis report |\r\n| FIX | Fix in order: deps → types → logic → tests → integration | Fix log per issue |\r\n| VERIFY | Run all tests, check consumers, summarize | Completion report |",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The focused-fix/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/focused-fix",
    "exported_at": "2026-11-03T07:43:29.594Z"
  }
}

format: aiskill/v1
skill:
  name: focused-fix
  slug: focused-fix
  version: 1.0.0
  description: >-
    Use when the user asks to fix, debug, or make a specific feature/module/area work end-to-end.
    Triggers: 'make X work', 'fix the Y feature', 'the Z module is broken', 'focus on [area]'. Not
    for quick single-bug fixes — this is for systematic deep-dive repair across all files and
    dependencies.
  category: Development
  tags:
    - dev-workflow
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: MIT
prompts:
  system: "# Focused Fix — Deep-Dive Feature Repair\r\n\r\n## When to Use\r\n\r\nActivate when the user asks to fix, debug, or make a specific feature/module/area work. Key triggers:\r\n- \"make X work\"\r\n- \"fix the Y feature\"\r\n- \"the Z module is broken\"\r\n- \"focus on [area]\"\r\n- \"this feature needs to work properly\"\r\n\r\nThis 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.\r\n\r\n```dot\r\ndigraph when_to_use {\r\n    \"User reports feature broken\" [shape=diamond];\r\n    \"Single bug or symptom?\" [shape=diamond];\r\n    \"Use systematic-debugging\" [shape=box];\r\n    \"Entire feature/module needs repair?\" [shape=diamond];\r\n    \"Use focused-fix\" [shape=box];\r\n    \"Something else\" [shape=box];\r\n\r\n    \"User reports feature broken\" -> \"Single bug or symptom?\";\r\n    \"Single bug or symptom?\" -> \"Use systematic-debugging\" [label=\"yes\"];\r\n    \"Single bug or symptom?\" -> \"Entire feature/module needs repair?\" [label=\"no\"];\r\n    \"Entire feature/module needs repair?\" -> \"Use focused-fix\" [label=\"yes\"];\r\n    \"Entire feature/module needs repair?\" -> \"Something else\" [label=\"no\"];\r\n}\r\n```\r\n\r\n## The Iron Law\r\n\r\n```\r\nNO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST\r\n```\r\n\r\nIf you haven't finished Phase 3, you cannot propose fixes. Period.\r\n\r\n**Violating the letter of these phases is violating the spirit of focused repair.**\r\n\r\n## Protocol — STRICTLY follow these 5 phases IN ORDER\r\n\r\n```dot\r\ndigraph phases {\r\n    rankdir=LR;\r\n    SCOPE [shape=box, label=\"Phase 1\\nSCOPE\"];\r\n    TRACE [shape=box, label=\"Phase 2\\nTRACE\"];\r\n    DIAGNOSE [shape=box, label=\"Phase 3\\nDIAGNOSE\"];\r\n    FIX [shape=box, label=\"Phase 4\\nFIX\"];\r\n    VERIFY [shape=box, label=\"Phase 5\\nVERIFY\"];\r\n\r\n    SCOPE -> TRACE -> DIAGNOSE -> FIX -> VERIFY;\r\n    FIX -> DIAGNOSE [label=\"fix broke\\nsomething else\"];\r\n    FIX -> ESCALATE [label=\"3+ fixes\\ncreate new issues\"];\r\n    ESCALATE [shape=doubleoctagon, label=\"STOP\\nQuestion Architecture\\nDiscuss with User\"];\r\n}\r\n```\r\n\r\n### Phase 1: SCOPE — Map the Feature Boundary\r\n\r\nBefore touching any code, understand the full scope of the feature.\r\n\r\n1. Ask the user: \"Which feature/folder should I focus on?\" if not already clear\r\n2. Identify the PRIMARY folder/files for this feature\r\n3. Map EVERY file in that folder — read each one, understand its purpose\r\n4. Create a feature manifest:\r\n\r\n```\r\nFEATURE SCOPE:\r\n  Primary path: src/features/auth/\r\n  Entry points: [files that are imported by other parts of the app]\r\n  Internal files: [files only used within this feature]\r\n  Total files: N\r\n  Total lines: N\r\n```\r\n\r\n### Phase 2: TRACE — Map All Dependencies (Inside AND Outside)\r\n\r\nTrace every connection this feature has to the rest of the codebase.\r\n\r\n**INBOUND (what this feature imports):**\r\n1. For every import statement in every file in the feature folder:\r\n   - Trace it to its source\r\n   - Verify the source file exists\r\n   - Verify the imported entity (function, type, component) exists and is exported\r\n   - Check if the types/signatures match what the feature expects\r\n2. Check for:\r\n   - Environment variables used (grep for process.env, import.meta.env, os.environ, etc.)\r\n   - Config files referenced\r\n   - Database models/schemas used\r\n   - API endpoints called\r\n   - Third-party packages imported\r\n\r\n**OUTBOUND (what imports this feature):**\r\n1. Search the entire codebase for imports from this feature folder\r\n2. For each consumer:\r\n   - Verify they're importing entities that actually exist\r\n   - Check if they're using the correct API/interface\r\n   - Note if any consumers are using deprecated patterns\r\n\r\nOutput format:\r\n```\r\nDEPENDENCY MAP:\r\n  Inbound (this feature depends on):\r\n    src/lib/db.ts → used in auth/repository.ts (getUserById, createUser)\r\n    src/lib/jwt.ts → used in auth/service.ts (signToken, verifyToken)\r\n    @prisma/client → used in auth/repository.ts\r\n    process.env.JWT_SECRET → used in auth/service.ts\r\n    process.env.DATABASE_URL → used via prisma\r\n\r\n  Outbound (depends on this feature):\r\n    src/app/api/login/route.ts → imports { login } from auth/service\r\n    src/app/api/register/route.ts → imports { register } from auth/service\r\n    src/middleware.ts → imports { verifyToken } from auth/service\r\n\r\n  Env vars required: JWT_SECRET, DATABASE_URL\r\n  Config files: prisma/schema.prisma (User model)\r\n```\r\n\r\n### Phase 3: DIAGNOSE — Find Every Issue\r\n\r\nSystematically check for problems. Run ALL of these checks:\r\n\r\n**CODE QUALITY:**\r\n- [ ] Every import resolves to a real file/export\r\n- [ ] No circular dependencies within the feature\r\n- [ ] Types are consistent across boundaries (no `any` at interfaces)\r\n- [ ] Error handling exists for all async operations\r\n- [ ] No TODO/FIXME/HACK comments indicating known issues\r\n\r\n**RUNTIME:**\r\n- [ ] All required environment variables are set (check .env)\r\n- [ ] Database migrations are up to date (if applicable)\r\n- [ ] API endpoints return expected shapes\r\n- [ ] No hardcoded values that should be configurable\r\n\r\n**TESTS:**\r\n- [ ] Run ALL tests related to this feature: find them by searching for imports from the feature folder\r\n- [ ] Record every failure with full error output\r\n- [ ] Check test coverage — are there untested code paths?\r\n\r\n**LOGS & ERRORS:**\r\n- [ ] Search for any log files, error reports, or Sentry-style error tracking\r\n- [ ] Check git log for recent changes to this feature: `git log --oneline -20 -- <feature-path>`\r\n- [ ] Check if any recent commits might have broken something: `git log --oneline -5 --all -- <files that this feature depends on>`\r\n\r\n**CONFIGURATION:**\r\n- [ ] Verify all config files this feature depends on are valid\r\n- [ ] Check for mismatches between development and production configs\r\n- [ ] Verify third-party service credentials are valid (if testable)\r\n\r\n**ROOT-CAUSE CONFIRMATION:**\r\nFor each CRITICAL issue found, confirm root cause before adding it to the fix list:\r\n- State clearly: \"I think X is the root cause because Y\"\r\n- Trace the data/control flow backward to verify — don't trust surface-level symptoms\r\n- If the issue spans multiple components, add diagnostic logging at each boundary to identify which layer fails\r\n- 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.\r\n\r\n**RISK LABELING:**\r\nAssign each issue a risk label:\r\n\r\n| Risk | Criteria |\r\n|---|---|\r\n| HIGH | Public API surface / breaking interface contract / DB schema / auth or security logic / widely imported module (>3 callers) / git hotspot |\r\n| MED | Internal module with tests / shared utility / config with runtime impact / internal callers of changed functions |\r\n| LOW | Leaf module / isolated file / test-only change / single-purpose helper with no callers |\r\n\r\nOutput format:\r\n```\r\nDIAGNOSIS REPORT:\r\n  Issues found: N\r\n\r\n  CRITICAL:\r\n    1. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]\r\n    2. [HIGH] [file:line] — description of issue. Root cause: [confirmed explanation]\r\n\r\n  WARNINGS:\r\n    1. [MED] [file:line] — description of issue\r\n    2. [LOW] [file:line] — description of issue\r\n\r\n  TESTS:\r\n    Ran: N tests\r\n    Passed: N\r\n    Failed: N\r\n    [list each failure with one-line summary]\r\n```\r\n\r\n### Phase 4: FIX — Repair Everything Systematically\r\n\r\nFix issues in this EXACT order:\r\n\r\n1. **DEPENDENCIES FIRST** — fix broken imports, missing packages, wrong versions\r\n2. **TYPES SECOND** — fix type mismatches at feature boundaries\r\n3. **LOGIC THIRD** — fix actual business logic bugs\r\n4. **TESTS FOURTH** — fix or create tests for each fix\r\n5. **INTEGRATION LAST** — verify the feature works end-to-end with its consumers\r\n\r\nRules:\r\n- Fix ONE issue at a time\r\n- After each fix, run the related test to confirm it works\r\n- If a fix breaks something else, STOP and re-evaluate (go back to DIAGNOSE)\r\n- Keep a running log of every change made\r\n- Never change code outside the feature folder without explicitly stating why\r\n- Fix HIGH-risk issues before MED, MED before LOW\r\n\r\n**ESCALATION RULE — 3-Strike Architecture Check:**\r\nIf 3+ fixes in this phase create NEW issues (not pre-existing ones), STOP immediately.\r\n\r\nThis pattern indicates an architectural problem, not a bug collection:\r\n- Each fix reveals new shared state / coupling / problem in a different place\r\n- Fixes require \"massive refactoring\" to implement\r\n- Each fix creates new symptoms elsewhere\r\n\r\n**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?\"\r\n\r\nDo NOT attempt fix #4 without this discussion.\r\n\r\nOutput after each fix:\r\n```\r\nFIX #1:\r\n  File: auth/service.ts:45\r\n  Issue: signToken called with wrong argument order\r\n  Change: swapped (expiresIn, payload) to (payload, expiresIn)\r\n  Test: auth.test.ts → PASSES\r\n```\r\n\r\n### Phase 5: VERIFY — Confirm Everything Works\r\n\r\nAfter all fixes are applied:\r\n\r\n1. Run ALL tests in the feature folder — every single one must pass\r\n2. Run ALL tests in files that IMPORT from this feature — must pass\r\n3. Run the full test suite if available — check for regressions\r\n4. If the feature has a UI, describe how to manually verify it\r\n5. Summarize all changes made\r\n\r\nFinal output:\r\n```\r\nFOCUSED FIX COMPLETE:\r\n  Feature: auth\r\n  Files changed: 4\r\n  Total fixes: 7\r\n  Tests: 23/23 passing\r\n  Regressions: 0\r\n\r\n  Changes:\r\n    1. auth/service.ts — fixed token signing argument order\r\n    2. auth/repository.ts — added null check for user lookup\r\n    3. auth/middleware.ts — fixed async error handling\r\n    4. auth/types.ts — aligned UserResponse type with actual DB schema\r\n\r\n  Consumers verified:\r\n    - src/app/api/login/route.ts ✅\r\n    - src/app/api/register/route.ts ✅\r\n    - src/middleware.ts ✅\r\n```\r\n\r\n## Red Flags — STOP and Return to Current Phase\r\n\r\nIf you catch yourself thinking any of these, you are skipping phases:\r\n\r\n- \"I can see the bug, let me just fix it\" → STOP. You haven't traced dependencies yet.\r\n- \"Scoping is overkill, it's obviously just this file\" → STOP. That's always wrong for feature-level fixes.\r\n- \"I'll map dependencies after I fix the obvious stuff\" → STOP. You'll miss root causes.\r\n- \"The user said fix X, so I only need to look at X\" → STOP. Features have dependencies.\r\n- \"Tests are passing so I'm done\" → STOP. Did you run consumer tests too?\r\n- \"I don't need to check env vars for this\" → STOP. Config issues masquerade as code bugs.\r\n- \"One more fix should do it\" (after 2+ cascading failures) → STOP. Escalate.\r\n- \"I'll skip the diagnosis report, the fixes are obvious\" → STOP. Write it down.\r\n\r\n**ALL of these mean: Return to the phase you're supposed to be in.**\r\n\r\n## Common Rationalizations\r\n\r\n| Excuse | Reality |\r\n|---|---|\r\n| \"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. |\r\n| \"I already know this codebase\" | Knowledge decays. Trace the actual imports, don't rely on memory. |\r\n| \"The user wants speed, not process\" | Skipping phases causes rework. Systematic is faster than thrashing. |\r\n| \"Only one file is broken\" | If only one file were broken, the user would say \"fix this bug\", not \"make the feature work.\" |\r\n| \"I fixed the tests, so it works\" | Tests can pass while consumers are broken. Verify Phase 5 fully. |\r\n| \"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. |\r\n| \"Root cause is obvious, I don't need to confirm\" | \"Obvious\" root causes are wrong 40% of the time. Confirm with evidence. |\r\n| \"3 cascading failures is normal for a big fix\" | 3 cascading failures means you're patching symptoms of an architectural problem. |\r\n\r\n## Anti-Patterns — NEVER do these\r\n\r\n| Anti-Pattern | Why It's Wrong |\r\n|---|---|\r\n| Starting to fix code before mapping all dependencies | You'll miss root causes and create whack-a-mole fixes |\r\n| Fixing only the file the user mentioned | Related files likely have issues too |\r\n| Ignoring environment variables and configuration | Many \"code bugs\" are actually config issues |\r\n| Skipping the test run phase | You can't verify fixes without running tests |\r\n| Making changes outside the feature folder without explaining why | Unexpected side effects confuse the user |\r\n| Fixing symptoms in consumer files instead of root cause in feature | Band-aids that break when the next consumer appears |\r\n| Declaring \"done\" without running verification tests | Untested fixes are unverified fixes |\r\n| Changing the public API without updating all consumers | Breaks everything that depends on the feature |\r\n\r\n## Related Skills\r\n\r\n- **`self-eval`** (this repo, `engineering/skills/self-eval`) — Use after Phase 5 to score the fix honestly before reporting it done\r\n- **`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\r\n- **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.\r\n\r\n## Quick Reference\r\n\r\n| Phase | Key Action | Output |\r\n|---|---|---|\r\n| SCOPE | Read every file, map entry points | Feature manifest |\r\n| TRACE | Map inbound + outbound dependencies | Dependency map |\r\n| DIAGNOSE | Check code, runtime, tests, logs, config | Diagnosis report |\r\n| FIX | Fix in order: deps → types → logic → tests → integration | Fix log per issue |\r\n| VERIFY | Run all tests, check consumers, summarize | Completion report |"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The focused-fix/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/focused-fix
  exported_at: "2026-11-03T07:43:29.594Z"