From ce1d7925cce98c0bdb86ff665703b67d15918469 Mon Sep 17 00:00:00 2001 From: Reza Rezvani Date: Mon, 23 Mar 2026 13:59:15 +0100 Subject: [PATCH] =?UTF-8?q?feat(engineering):=20integrate=20focused-fix=20?= =?UTF-8?q?skill=20=E2=80=94=20docs,=20command,=20agent,=20marketplace?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Normalize SKILL.md frontmatter to repo standard (remove non-standard license, metadata.* fields; inline description) - Generate docs page (docs/skills/engineering/focused-fix.md) - Add to mkdocs.yml nav (skills + commands) - Create /focused-fix slash command (commands/ + .claude/commands/) - Add to cs-senior-engineer agent (skill integration + new workflow #4) - Update marketplace.json and plugin.json descriptions (30 → 31 skills) Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude-plugin/marketplace.json | 2 +- .claude/commands/focused-fix.md | 17 ++ agents/engineering/cs-senior-engineer.md | 11 +- commands/focused-fix.md | 91 +++++++ docs/agents/cs-senior-engineer.md | 11 +- docs/commands/focused-fix.md | 97 +++++++ docs/commands/index.md | 10 +- docs/skills/engineering/focused-fix.md | 329 +++++++++++++++++++++++ docs/skills/engineering/index.md | 10 +- engineering/.claude-plugin/plugin.json | 2 +- engineering/focused-fix/SKILL.md | 13 +- mkdocs.yml | 2 + 12 files changed, 575 insertions(+), 20 deletions(-) create mode 100644 .claude/commands/focused-fix.md create mode 100644 commands/focused-fix.md create mode 100644 docs/commands/focused-fix.md create mode 100644 docs/skills/engineering/focused-fix.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 3a03ff4..cb3a4b1 100644 --- a/.claude-plugin/marketplace.json +++ b/.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" diff --git a/.claude/commands/focused-fix.md b/.claude/commands/focused-fix.md new file mode 100644 index 0000000..0f15a49 --- /dev/null +++ b/.claude/commands/focused-fix.md @@ -0,0 +1,17 @@ +--- +description: Deep-dive feature repair — systematically fix an entire feature/module. Usage: /focused-fix +--- + +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. diff --git a/agents/engineering/cs-senior-engineer.md b/agents/engineering/cs-senior-engineer.md index ef488ea..7bdaa5d 100644 --- a/agents/engineering/cs-senior-engineer.md +++ b/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 diff --git a/commands/focused-fix.md b/commands/focused-fix.md new file mode 100644 index 0000000..90ba532 --- /dev/null +++ b/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 +--- + +# /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: + 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 diff --git a/docs/agents/cs-senior-engineer.md b/docs/agents/cs-senior-engineer.md index 1c0037a..7d1a437 100644 --- a/docs/agents/cs-senior-engineer.md +++ b/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 diff --git a/docs/commands/focused-fix.md b/docs/commands/focused-fix.md new file mode 100644 index 0000000..8fefb9d --- /dev/null +++ b/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 . Slash command for Claude Code, Codex CLI, Gemini CLI." +--- + +# /focused-fix + +
+:material-console: Slash Command +:material-github: Source +
+ + +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: + 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 diff --git a/docs/commands/index.md b/docs/commands/index.md index d4a0e42..cc45265 100644 --- a/docs/commands/index.md +++ b/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." ---
# :material-console: Slash Commands -

21 commands for quick access to common operations

+

22 commands for quick access to common operations

@@ -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)** --- diff --git a/docs/skills/engineering/focused-fix.md b/docs/skills/engineering/focused-fix.md new file mode 100644 index 0000000..577d6a6 --- /dev/null +++ b/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 + +
+:material-rocket-launch: Engineering - POWERFUL +:material-identifier: `focused-fix` +:material-github: Source +
+ +
+Install: claude /plugin install engineering-advanced-skills +
+ + +## 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 -- ` +- [ ] Check if any recent commits might have broken something: `git log --oneline -5 --all -- ` + +**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 | diff --git a/docs/skills/engineering/index.md b/docs/skills/engineering/index.md index 93b9410..012f53f 100644 --- a/docs/skills/engineering/index.md +++ b/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." ---
# :material-rocket-launch: Engineering - POWERFUL -

43 skills in this domain

+

44 skills in this domain

@@ -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)** --- diff --git a/engineering/.claude-plugin/plugin.json b/engineering/.claude-plugin/plugin.json index af39bb2..8f4b177 100644 --- a/engineering/.claude-plugin/plugin.json +++ b/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", diff --git a/engineering/focused-fix/SKILL.md b/engineering/focused-fix/SKILL.md index af71cc9..b936b5a 100644 --- a/engineering/focused-fix/SKILL.md +++ b/engineering/focused-fix/SKILL.md @@ -1,17 +1,6 @@ --- 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]", - "this feature needs to work properly", "just make [feature] work". Not for quick single-bug fixes - (use systematic-debugging for that). This is for when an entire feature or module needs systematic - deep-dive repair across all its files and dependencies. -license: MIT -metadata: - version: 1.0.0 - author: avinashchby - category: engineering - updated: 2026-03-22 +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 diff --git a/mkdocs.yml b/mkdocs.yml index d0ac99f..fb1833b 100644 --- a/mkdocs.yml +++ b/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