Merge pull request #402 from alirezarezvani/dev

release: sync dev → main — focused-fix, GSC verification, #392 fix, PR #387 fixes

.claude-plugin/marketplace.json

@@ -59,7 +59,7 @@
     {
       "name": "engineering-advanced-skills",
       "source": "./engineering",
-      "description": "30 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, and more.",
+      "description": "31 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, focused-fix, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, and more.",
       "version": "2.1.2",
       "author": {
         "name": "Alireza Rezvani"

.claude/commands/focused-fix.md

@@ -0,0 +1,17 @@
+---
+description: Deep-dive feature repair — systematically fix an entire feature/module. Usage: /focused-fix <feature-path>
+---
+
+Systematically repair the feature/module at `$ARGUMENTS` using the focused-fix 5-phase protocol.
+
+If `$ARGUMENTS` is empty, ask which feature/module to fix.
+
+Read `engineering/focused-fix/SKILL.md` and execute ALL 5 phases IN ORDER:
+
+1. **SCOPE** — Map the feature boundary (all files, entry points, internal files)
+2. **TRACE** — Map inbound + outbound dependencies across the entire codebase
+3. **DIAGNOSE** — Check code, runtime, tests, logs, config. Assign risk labels (HIGH/MED/LOW). Confirm root causes with evidence.
+4. **FIX** — Repair in order: deps → types → logic → tests → integration. One fix at a time, test after each. 3-strike escalation if fixes cascade.
+5. **VERIFY** — Run all feature tests + consumer tests. Summarize changes.
+
+**Iron Law:** No fixes before completing Phase 3. No exceptions.

.codex/skills-index.json

@@ -3,7 +3,7 @@
   "name": "claude-code-skills",
   "description": "Production-ready skill packages for AI agents - Marketing, Engineering, Product, C-Level, PM, and RA/QM",
   "repository": "https://github.com/alirezarezvani/claude-skills",
-  "total_skills": 165,
+  "total_skills": 166,
   "skills": [
     {
       "name": "contract-and-proposal-writer",
@@ -437,6 +437,12 @@
       "category": "engineering-advanced",
       "description": "Env & Secrets Manager"
     },
+    {
+      "name": "focused-fix",
+      "source": "../../engineering/focused-fix",
+      "category": "engineering-advanced",
+      "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 \u2014 this is for systematic deep-dive repair across all files and dependencies."
+    },
     {
       "name": "git-worktree-manager",
       "source": "../../engineering/git-worktree-manager",
@@ -1013,7 +1019,7 @@
       "description": "Software engineering and technical skills"
     },
     "engineering-advanced": {
-      "count": 30,
+      "count": 31,
       "source": "../../engineering",
       "description": "Advanced engineering skills - agents, RAG, MCP, CI/CD, databases, observability"
     },

.codex/skills/focused-fix

@@ -0,0 +1 @@
+../../engineering/focused-fix

agents/engineering/cs-senior-engineer.md

@@ -24,6 +24,7 @@ Cross-cutting senior engineer covering architecture, backend, DevOps, security,
 
 ### Code Quality & Review
 - `engineering/pr-review-expert` — Pull request review methodology
+- `engineering/focused-fix` — Deep-dive feature repair (5-phase: scope → trace → diagnose → fix → verify)
 - `engineering-team/code-reviewer` — Code quality analysis
 - `engineering-team/tdd-guide` — Test-driven development
 - `engineering-team/senior-qa` — Quality assurance strategy
@@ -63,7 +64,15 @@ Cross-cutting senior engineer covering architecture, backend, DevOps, security,
 4. Configure observability via `observability-designer`
 5. Set up release process via `release-manager`
 
-### 4. Technical Debt Assessment
+### 4. Feature Repair (Deep-Dive Debugging)
+1. Identify broken feature scope via `focused-fix` Phase 1 (SCOPE)
+2. Map inbound + outbound dependencies via Phase 2 (TRACE)
+3. Diagnose across code, runtime, tests, logs, config via Phase 3 (DIAGNOSE)
+4. Fix in priority order: deps → types → logic → tests → integration
+5. Verify all consumers pass via Phase 5 (VERIFY)
+6. Escalate if 3+ fixes cascade into new issues (architecture problem)
+
+### 5. Technical Debt Assessment
 1. Scan codebase via `tech-debt-tracker`
 2. Score and prioritize debt items
 3. Create remediation plan with effort estimates

commands/focused-fix.md

@@ -0,0 +1,91 @@
+---
+name: focused-fix
+description: Deep-dive feature repair — systematically fix an entire feature/module across all its files and dependencies. Usage: /focused-fix <feature-path>
+---
+
+# /focused-fix
+
+Systematically repair an entire feature or module using the 5-phase protocol. Target: `$ARGUMENTS` (a feature path or module name).
+
+If `$ARGUMENTS` is empty, ask the user which feature/module to fix.
+
+## Protocol — Execute ALL 5 Phases IN ORDER
+
+### Phase 1: SCOPE — Map the Feature Boundary
+
+1. Identify the primary folder/files for the target feature
+2. Read EVERY file in that folder — understand its purpose
+3. Create a feature manifest:
+
+```
+FEATURE SCOPE:
+  Primary path: <path>
+  Entry points: [files imported by other parts of the app]
+  Internal files: [files only used within this feature]
+  Total files: N
+```
+
+### Phase 2: TRACE — Map All Dependencies
+
+**INBOUND** (what this feature imports):
+- For every import statement, trace to source, verify it exists and is exported
+- Check env vars, config files, DB models, API endpoints, third-party packages
+
+**OUTBOUND** (what imports this feature):
+- Search entire codebase for imports from this feature
+- Verify consumers use correct API/interface
+
+Output a dependency map with inbound, outbound, env vars, and config files.
+
+### Phase 3: DIAGNOSE — Find Every Issue
+
+Run ALL diagnostic checks:
+
+- **Code**: imports resolve, no circular deps, types consistent, error handling, TODO/FIXME
+- **Runtime**: env vars set, migrations current, API shapes correct
+- **Tests**: run ALL related tests, record failures, check coverage
+- **Logs**: check git log for recent changes, search error logs
+- **Config**: validate config files, check dev/prod mismatches
+
+For each issue found:
+- Confirm root cause with evidence before adding to fix list
+- Assign risk: HIGH (public API, auth, >3 callers) / MED (internal with tests) / LOW (leaf module)
+
+Output a diagnosis report with issues grouped by severity.
+
+### Phase 4: FIX — Repair Systematically
+
+Fix in this EXACT order:
+1. **Dependencies** — broken imports, missing packages
+2. **Types** — type mismatches at boundaries
+3. **Logic** — business logic bugs
+4. **Tests** — fix or create tests for each fix
+5. **Integration** — verify end-to-end with consumers
+
+Rules:
+- Fix ONE issue at a time, run related test after each
+- If a fix breaks something else → go back to DIAGNOSE
+- Fix HIGH before MED before LOW
+- **3-Strike Rule**: If 3+ fixes create NEW issues, STOP. Tell the user the architecture may need rethinking, not patching.
+
+### Phase 5: VERIFY — Confirm Everything Works
+
+1. Run ALL tests in the feature folder
+2. Run ALL tests in files that import from this feature
+3. Run full test suite if available
+4. Summarize all changes made
+
+Output a completion report with files changed, fixes applied, test results, and consumers verified.
+
+## Iron Law
+
+```
+NO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST
+```
+
+If you haven't finished Phase 3, you cannot propose fixes.
+
+## Related Skills
+
+- `engineering/focused-fix` — Full SKILL.md with detailed checklists, output templates, and anti-patterns
+- `superpowers:systematic-debugging` — For individual complex bugs found during Phase 3

docs/agents/cs-senior-engineer.md

@@ -27,6 +27,7 @@ Cross-cutting senior engineer covering architecture, backend, DevOps, security,
 
 ### Code Quality & Review
 - `engineering/pr-review-expert` — Pull request review methodology
+- `engineering/focused-fix` — Deep-dive feature repair (5-phase: scope → trace → diagnose → fix → verify)
 - `engineering-team/code-reviewer` — Code quality analysis
 - `engineering-team/tdd-guide` — Test-driven development
 - `engineering-team/senior-qa` — Quality assurance strategy
@@ -66,7 +67,15 @@ Cross-cutting senior engineer covering architecture, backend, DevOps, security,
 4. Configure observability via `observability-designer`
 5. Set up release process via `release-manager`
 
-### 4. Technical Debt Assessment
+### 4. Feature Repair (Deep-Dive Debugging)
+1. Identify broken feature scope via `focused-fix` Phase 1 (SCOPE)
+2. Map inbound + outbound dependencies via Phase 2 (TRACE)
+3. Diagnose across code, runtime, tests, logs, config via Phase 3 (DIAGNOSE)
+4. Fix in priority order: deps → types → logic → tests → integration
+5. Verify all consumers pass via Phase 5 (VERIFY)
+6. Escalate if 3+ fixes cascade into new issues (architecture problem)
+
+### 5. Technical Debt Assessment
 1. Scan codebase via `tech-debt-tracker`
 2. Score and prioritize debt items
 3. Create remediation plan with effort estimates

docs/commands/focused-fix.md

@@ -0,0 +1,97 @@
+---
+title: "/focused-fix — Slash Command for AI Coding Agents"
+description: "Deep-dive feature repair — systematically fix an entire feature/module across all its files and dependencies. Usage: /focused-fix <feature-path>. Slash command for Claude Code, Codex CLI, Gemini CLI."
+---
+
+# /focused-fix
+
+<div class="page-meta" markdown>
+<span class="meta-badge">:material-console: Slash Command</span>
+<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/commands/focused-fix.md">Source</a></span>
+</div>
+
+
+Systematically repair an entire feature or module using the 5-phase protocol. Target: `$ARGUMENTS` (a feature path or module name).
+
+If `$ARGUMENTS` is empty, ask the user which feature/module to fix.
+
+## Protocol — Execute ALL 5 Phases IN ORDER
+
+### Phase 1: SCOPE — Map the Feature Boundary
+
+1. Identify the primary folder/files for the target feature
+2. Read EVERY file in that folder — understand its purpose
+3. Create a feature manifest:
+
+```
+FEATURE SCOPE:
+  Primary path: <path>
+  Entry points: [files imported by other parts of the app]
+  Internal files: [files only used within this feature]
+  Total files: N
+```
+
+### Phase 2: TRACE — Map All Dependencies
+
+**INBOUND** (what this feature imports):
+- For every import statement, trace to source, verify it exists and is exported
+- Check env vars, config files, DB models, API endpoints, third-party packages
+
+**OUTBOUND** (what imports this feature):
+- Search entire codebase for imports from this feature
+- Verify consumers use correct API/interface
+
+Output a dependency map with inbound, outbound, env vars, and config files.
+
+### Phase 3: DIAGNOSE — Find Every Issue
+
+Run ALL diagnostic checks:
+
+- **Code**: imports resolve, no circular deps, types consistent, error handling, TODO/FIXME
+- **Runtime**: env vars set, migrations current, API shapes correct
+- **Tests**: run ALL related tests, record failures, check coverage
+- **Logs**: check git log for recent changes, search error logs
+- **Config**: validate config files, check dev/prod mismatches
+
+For each issue found:
+- Confirm root cause with evidence before adding to fix list
+- Assign risk: HIGH (public API, auth, >3 callers) / MED (internal with tests) / LOW (leaf module)
+
+Output a diagnosis report with issues grouped by severity.
+
+### Phase 4: FIX — Repair Systematically
+
+Fix in this EXACT order:
+1. **Dependencies** — broken imports, missing packages
+2. **Types** — type mismatches at boundaries
+3. **Logic** — business logic bugs
+4. **Tests** — fix or create tests for each fix
+5. **Integration** — verify end-to-end with consumers
+
+Rules:
+- Fix ONE issue at a time, run related test after each
+- If a fix breaks something else → go back to DIAGNOSE
+- Fix HIGH before MED before LOW
+- **3-Strike Rule**: If 3+ fixes create NEW issues, STOP. Tell the user the architecture may need rethinking, not patching.
+
+### Phase 5: VERIFY — Confirm Everything Works
+
+1. Run ALL tests in the feature folder
+2. Run ALL tests in files that import from this feature
+3. Run full test suite if available
+4. Summarize all changes made
+
+Output a completion report with files changed, fixes applied, test results, and consumers verified.
+
+## Iron Law
+
+```
+NO FIXES WITHOUT COMPLETING SCOPE → TRACE → DIAGNOSE FIRST
+```
+
+If you haven't finished Phase 3, you cannot propose fixes.
+
+## Related Skills
+
+- `engineering/focused-fix` — Full SKILL.md with detailed checklists, output templates, and anti-patterns
+- `superpowers:systematic-debugging` — For individual complex bugs found during Phase 3

docs/commands/index.md

@@ -1,13 +1,13 @@
 ---
 title: "Slash Commands — AI Coding Agent Commands & Codex Shortcuts"
-description: "21 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more."
+description: "22 slash commands for Claude Code, Codex CLI, and Gemini CLI — sprint planning, tech debt analysis, PRDs, OKRs, and more."
 ---
 
 <div class="domain-header" markdown>
 
 # :material-console: Slash Commands
 
-<p class="domain-count">21 commands for quick access to common operations</p>
+<p class="domain-count">22 commands for quick access to common operations</p>
 
 </div>
 
@@ -43,6 +43,12 @@ description: "21 slash commands for Claude Code, Codex CLI, and Gemini CLI — s
 
     Analyze financial statements, build valuation models, assess budget variances, and construct forecasts.
 
+-   :material-console:{ .lg .middle } **[`/focused-fix`](focused-fix.md)**
+
+    ---
+
+    Systematically repair an entire feature or module using the 5-phase protocol. Target: $ARGUMENTS (a feature path or m...
+
 -   :material-console:{ .lg .middle } **[`/google-workspace`](google-workspace.md)**
 
     ---

docs/skills/engineering/focused-fix.md

@@ -0,0 +1,329 @@
+---
+title: "Focused Fix — Deep-Dive Feature Repair — Agent Skill for Codex & OpenClaw"
+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. Agent skill for Claude Code, Codex CLI, Gemini CLI, OpenClaw."
+---
+
+# Focused Fix — Deep-Dive Feature Repair
+
+<div class="page-meta" markdown>
+<span class="meta-badge">:material-rocket-launch: Engineering - POWERFUL</span>
+<span class="meta-badge">:material-identifier: `focused-fix`</span>
+<span class="meta-badge">:material-github: <a href="https://github.com/alirezarezvani/claude-skills/tree/main/engineering/focused-fix/SKILL.md">Source</a></span>
+</div>
+
+<div class="install-banner" markdown>
+<span class="install-label">Install:</span> <code>claude /plugin install engineering-advanced-skills</code>
+</div>
+
+
+## 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
+- **REQUIRED SUB-SKILL:** For complex bugs found during diagnosis, apply `superpowers: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
+
+- **`superpowers:systematic-debugging`** — Use within Phase 3 for root-cause tracing of individual complex bugs
+- **`superpowers: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 |

docs/skills/engineering/index.md

@@ -1,13 +1,13 @@
 ---
 title: "Engineering - POWERFUL Skills — Agent Skills & Codex Plugins"
-description: "43 engineering - powerful skills — advanced agent-native skill and Claude Code plugin for AI agent design, infrastructure, and automation. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw."
+description: "44 engineering - powerful skills — advanced agent-native skill and Claude Code plugin for AI agent design, infrastructure, and automation. Works with Claude Code, Codex CLI, Gemini CLI, and OpenClaw."
 ---
 
 <div class="domain-header" markdown>
 
 # :material-rocket-launch: Engineering - POWERFUL
 
-<p class="domain-count">43 skills in this domain</p>
+<p class="domain-count">44 skills in this domain</p>
 
 </div>
 
@@ -107,6 +107,12 @@ description: "43 engineering - powerful skills — advanced agent-native skill a
 
     Tier: POWERFUL
 
+-   **[Focused Fix — Deep-Dive Feature Repair](focused-fix.md)**
+
+    ---
+
+    Activate when the user asks to fix, debug, or make a specific feature/module/area work. Key triggers:
+
 -   **[Git Worktree Manager](git-worktree-manager.md)**
 
     ---

engineering-team/self-improving-agent/hooks/hooks.json

@@ -6,7 +6,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "./hooks/error-capture.sh"
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/error-capture.sh"
           }
         ]
       }

engineering-team/self-improving-agent/settings.json

@@ -18,7 +18,7 @@
   },
   "hooks": {
     "PostToolUse": {
-      "Bash": "hooks/error-capture.sh"
+      "Bash": "${CLAUDE_PLUGIN_ROOT}/hooks/error-capture.sh"
     }
   },
   "agents": [

engineering/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "engineering-advanced-skills",
-  "description": "30 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, and more. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.",
+  "description": "31 advanced engineering skills: agent designer, agent workflow designer, AgentHub, RAG architect, database designer, migration architect, observability designer, dependency auditor, release manager, API reviewer, CI/CD pipeline builder, MCP server builder, skill security auditor, performance profiler, Helm chart builder, Terraform patterns, focused-fix, and more. Agent skill and plugin for Claude Code, Codex, Gemini CLI, Cursor, OpenClaw.",
   "version": "2.1.2",
   "author": {
     "name": "Alireza Rezvani",

engineering/focused-fix/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: "focused-fix"
+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."
+---
+
+# 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
+- **REQUIRED SUB-SKILL:** For complex bugs found during diagnosis, apply `superpowers: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
+
+- **`superpowers:systematic-debugging`** — Use within Phase 3 for root-cause tracing of individual complex bugs
+- **`superpowers: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 |

mkdocs.yml

@@ -181,6 +181,7 @@ nav:
       - "Database Schema Designer": skills/engineering/database-schema-designer.md
       - "Dependency Auditor": skills/engineering/dependency-auditor.md
       - "Env & Secrets Manager": skills/engineering/env-secrets-manager.md
+      - "Focused Fix": skills/engineering/focused-fix.md
       - "Git Worktree Manager": skills/engineering/git-worktree-manager.md
       - "Interview System Designer": skills/engineering/interview-system-designer.md
       - "MCP Server Builder": skills/engineering/mcp-server-builder.md
@@ -372,6 +373,7 @@ nav:
     - "/code-to-prd": commands/code-to-prd.md
     - "/competitive-matrix": commands/competitive-matrix.md
     - "/financial-health": commands/financial-health.md
+    - "/focused-fix": commands/focused-fix.md
     - "/okr": commands/okr.md
     - "/persona": commands/persona.md
     - "/pipeline": commands/pipeline.md