hotfix

name	hotfix
description	Fix bugs or modify existing features with deep exploration, root-cause analysis, and quality-first long-term solutions
model	opus
argument-hint	<issue description>
hooks	{"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"if [[ -d \"backend\" ]]; then\n cd backend && go build ./... 2>&1 | head -10 && golangci-lint run ./... 2>&1 | head -20 || true\nfi\n","once":true}]}]}

YOU ARE EXECUTING THE /hotfix SKILL. The user triggered this skill. Follow ALL instructions below step by step. Do NOT treat this as a freeform conversation - execute the skill workflow.

Follow CLAUDE.md rules for Clean Architecture.

Quality-First Principle (CRITICAL)

This skill exists to find the best long-term solution, not the fastest patch. The recommended fix must score highest on:

• Elegance: clean, idiomatic, well-architected code
• Long-term maintainability: low technical debt, clear boundaries, testable
• Reasonable scalability: fits current scale and foreseeable growth without requiring a rewrite

Forbidden defaults

• Reflexively picking the shortest or easiest-to-implement path
• Proposing "quick wins" that create future debt without flagging the trade-off
• Optimizing the recommended option for token cost or implementation speed
• Treating symptoms instead of root cause

Calibration: do not over-engineer either

A lean / simple solution IS the right call when the scope is small and isolated, the logic is genuinely throwaway, or YAGNI clearly applies. But it must be the outcome of an explicit arbitration, not a reflex. When the trade-off is genuinely unclear, lean toward the more robust and maintainable option.

When presenting alternatives

When multiple approaches exist, the option tagged "Recommended" MUST:

1. Score highest on (elegance + maintainability + scalability) among the options
2. Be accompanied by a one-sentence justification of WHY each alternative is NOT the recommendation (what it sacrifices: robustness, scale ceiling, testability, isolation, etc.)
3. If it is also the simplest to implement, explicitly verify the simplicity is a genuine technical fit, not implementation-speed bias. State "simplicity is a genuine technical fit here because X" rather than leaving it implicit

A more economical variant CAN be proposed as an alternative, with trade-offs spelled out so the user can choose knowingly.

Ultra Think Strategy

Ultra think before each phase transition:

• After clarification: ensure you fully understand the issue
• After exploration results: reflect on completeness before analyzing
• Before fix plan: explicitly arbitrate between alternatives. If picking the simplest option, verify the simplicity is a genuine technical fit, not implementation-speed bias
• Before implementation: consider edge cases, patterns to follow, potential issues
• After validation: ensure the fix addresses root cause, not symptoms

---

1. PARSE ISSUE

From: $ARGUMENTS

Extract:

• Feature area: Which part of the app?
• Bug type: Logic error, UI, data, performance, error handling?
• Layers: Backend / Frontend / Both / Database?
• Database env: Detect from description (prod/dev) - default to DEV

---

2. CLARIFY ISSUE

Use AskUserQuestion to clarify before exploration:

Bug context (if not specified)

• Can you reproduce the bug? Steps to reproduce?
• What is the expected vs actual behavior?
• When did it start happening? (recent deploy, config change?)
• Are there error logs or screenshots available?

Impact & Priority (if not specified)

• Is this blocking production?
• Who/what is affected?
• Is there a temporary workaround in place?

Scope (if not specified)

• What constraints frame the solution (deadlines, blast radius, rollback risk)?
• Are there related issues to address as part of the same root-cause fix?
• Environment affected: dev, staging, prod?

Do not proceed until the issue is fully understood.

---

3. EXPLORE (PARALLEL)

Launch focused agents in a single message (parallel execution). There is no upper limit on agent count. Spawn one agent per distinct concern, area, or file-cluster the task actually has, and scale up freely with its breadth. The lists below are a starting menu, not a quota: add as many agents as full coverage requires.

Agent-count principle

• You decide the count from the actual scope. Assess how many distinct concerns / areas / file-clusters the task really spans on this codebase, and launch one focused agent for each. Do not anchor to a fixed number or to file counts.
• No ceiling, real floor. Use at least 2 agents per domain in scope (1 only for a genuinely trivial single-file change). Above that floor there is no maximum; on a large codebase the realistic count usually sits well above it.
• One distinct focus per agent. Split by concern so two agents never run the same search. Add agents to widen coverage, never to duplicate it.
• No batching. Launch them all in one message; the harness schedules them, so you never hold back to stay under a number.

Backend Agents (≥2 when backend in scope, one per distinct concern, no maximum)

1. Domain & data flow - explore-codebase: "Find entities, repository interfaces, value objects, and DTOs related to [feature] in backend/internal/domain/ and backend/internal/application/dto/"
2. Usecases & business logic - explore-codebase: "Find usecases related to [feature] in backend/internal/application/usecases/. Read their Execute methods, dependencies, and error handling"
3. Handlers & routing - explore-codebase: "Find HTTP handlers and routes related to [feature] in backend/internal/presentation/. Check middleware, validation, response patterns"
4. Infrastructure & services - explore-codebase: "Find repo implementations, external service adapters, and config related to [feature] in backend/internal/infrastructure/"
5. Similar patterns - explore-codebase: "Find the most similar existing feature to [feature] in backend/. I need to replicate its patterns"

Frontend Agents (≥2 when frontend in scope, one per distinct concern, no maximum)

1. Components & UI - explore-codebase: "Find components related to [feature] in frontend/src/components/. Check props, state, Shadcn UI usage"
2. Hooks & state - explore-codebase: "Find hooks, React Query calls, and state management related to [feature] in frontend/src/hooks/ and frontend/src/lib/"
3. Pages & routing - explore-codebase: "Find pages and layouts related to [feature] in frontend/src/app/. Check route structure, data fetching, i18n"
4. Types & API layer - explore-codebase: "Find TypeScript types, API client functions related to [feature] in frontend/src/types/ and frontend/src/lib/"
5. Similar patterns - explore-codebase: "Find the most similar existing feature to [feature] in frontend/src/. I need to replicate its patterns"

The supporting agents below fan out the SAME way as the code agents: one agent per distinct concern, no maximum. None of them is capped at a single instance.

Database Agents (≥1 when DB in scope, one per distinct concern, no maximum)

Launch one explore-db per distinct DB concern in the same single message. One agent is enough for a single-table lookup; scale up freely when the task spans multiple table clusters, both dev and prod, or several concerns. First token of each prompt selects the env (dev/prod, defaults to dev).

1. Schema & relationships - explore-db: "dev - Map tables and foreign keys related to [feature]: columns, types, FK relationships"
2. Constraints & policies - explore-db: "dev - Inspect constraints and RLS policies (if used) on tables related to [feature]"
3. Migrations & advisors - explore-db: "dev - List migrations touching [feature] tables, run get_advisors for security/perf issues"

Add one agent per distinct table cluster, or to cover prod alongside dev.

Documentation Agents (≥1 when external docs needed, one per library/feature, no maximum)

Launch one explore-docs per distinct library or per distinct feature within a library. One agent is enough for a single lib question; scale up when the fix touches multiple libraries or several independent features of one.

1. [library A] - explore-docs: "[library A] [specific feature] documentation"
2. [library B] - explore-docs: "[library B] [specific feature] documentation"

Web-research Agents (≥1 when external research needed, one per topic, no maximum)

Launch one websearch per distinct external question. One agent is enough for a single topic; scale up when there are several independent questions.

1. [topic A] - websearch: "[topic A] best practices 2025 2026"
2. [topic B] - websearch: "[topic B] ..."

---

3.5 POST-EXPLORATION CHECK

After agents return, verify coverage across all dimensions:

1. Full code path traced? Can I trace handler -> usecase -> repository -> DB (backend) and page -> hook -> API -> component (frontend)? If gaps -> launch targeted explore-codebase
2. Similar patterns identified? Do I have a reference implementation to follow? If not -> launch explore-codebase
3. Data model complete? Tables, columns, relationships, policies known? If not -> launch additional parallel explore-db agents (one per missing concern / cluster / env)
4. Library docs sufficient? If not -> launch additional parallel explore-docs agents (one per missing library / feature)

Do NOT proceed with incomplete context.

---

4. ANALYZE

Produce analysis:

## Bug Analysis

### Current Behavior
[What the code currently does]

### Expected Behavior
[What it should do]

### Root Cause
[Why the bug happens - with file:line references]

### Files Affected
- `path/to/file.go:123` - [how it's affected]

---

5. SHOW FIX PLAN (MANDATORY CHECKPOINT)

Create and display the complete fix strategy, then STOP. Do NOT proceed without user validation.

## Fix Strategy

### Root Cause Summary
[One sentence]

### Approach (Recommended)
[2-3 sentences describing the chosen approach and WHY it is the long-term, quality-first answer (elegance + maintainability + scalability).]

### Alternatives Considered
- **[Alt A]**: [What it does]. Rejected because [what it sacrifices: robustness, scale ceiling, testability, etc.].
- **[Alt B]**: [What it does]. Rejected because [...].

(Skip this section ONLY if there is genuinely no alternative worth mentioning, and state so explicitly.)

### Changes Required

**Backend:**
- `path/to/file.go:XX` - [specific change]

**Frontend:**
- `path/to/file.tsx:XX` - [specific change]

### Patterns to Follow
[From exploration - exact code snippets]

### Risks & Mitigations
- [Risk]: [Mitigation]

---

6. VALIDATE (BLOCKING)

MANDATORY: You MUST wait for user approval before ANY implementation.

Ask with AskUserQuestion: "Validate this fix approach?"

• "Apply fix"
• "Investigate more"
• "Modify approach"

DO NOT proceed to implementation without explicit user selection.

---

7. IMPLEMENT

ONLY after user selects "Apply fix", implement:

1. Backend changes first
2. Frontend changes second

Rules:

• Stay in scope - change only what's needed
• Fix root cause, not symptoms
• Add defensive checks where appropriate
• Write a regression test for the bug being fixed: backend *_test.go for Go fixes, *.test.ts / *.test.tsx for frontend fixes
• The test must reproduce the original failure and verify the fix

For significant UI: Skill(skill="frontend-design:frontend-design")

---

8. VERIFY

cd backend && go build ./... && go vet ./... && golangci-lint run ./... && go test ./...
cd frontend && npm run test:run && npm run build

Backend and frontend tests are MANDATORY: All existing tests must pass (zero regressions). The regression test for the fix must also pass.

Database verification (if schema/policies changed): run get_advisors via explore-db (dev/prod).

---

9. SUMMARY

## Fix Complete

### Issue
[Original issue]

### Root Cause
[What was wrong]

### Changes Made
- `path/to/file.go` - [change]

### Testing Recommendation
- [How to verify]

---

Rules

• CLARIFY FIRST - fully understand the issue before exploring
• EXPLORE SECOND - never assume, always investigate
• ROOT CAUSE - fix the cause, not the symptom
• QUALITY-FIRST - the recommended fix maximizes elegance + maintainability + scalability; economy is an explicit trade-off, never a reflex
• VALIDATE IS BLOCKING - NEVER implement without explicit user approval on the fix plan
• STAY IN SCOPE - change only what's needed (no incidental refactors, no premature abstractions)