@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/backend-guide.md

@@ -0,0 +1,132 @@
+# Backend Bug-Fixing Guide – 2025 Edition
+
+> Enterprise-grade guide for Java, Python, Go, Node.js, SQL, and distributed systems.
+
+20+ years of production war stories → one unbreakable playbook.
+
+## Core Philosophy
+> "Backend bugs aren't just code—they're concurrency, transactions, or hidden state. Fix the system, not the symptom."
+
+## The 5-Step Backend Repair Process
+
+### 1. Reproduce & Isolate – Capture the Culprit
+80% of "intermittent" bugs are environmental ghosts.
+
+| Check                  | Verification Method                                      |
+|------------------------|----------------------------------------------------------|
+| Load (QPS)             | Artillery / k6 load test to match prod traffic           |
+| Database state         | Dump prod-like data to local (anonymized)                |
+| Config drift           | `diff dev/prod` for env vars, Spring profiles, etc.      |
+| Concurrency            | Run with 10+ parallel threads/users                      |
+| Logs / Traces          | Full Jaeger/OpenTelemetry spans (not just console logs)  |
+
+Tools: Docker Compose (mirror prod env), Postman Newman (replay requests), Prometheus (metrics baseline)
+
+### 2. Root Cause Analysis – Deep Dive
+99% of re-opened bugs missed the true root.
+
+Techniques:
+- **5 Whys**: Why transaction failed? → Rollback timeout. Why? → Isolation level wrong.
+- **Full Trace**: Controller → Service → Repo → DB (check locks, deadlocks)
+- **Concurrency Detector**: Go race detector, Java ThreadMXBean dumps
+
+Common traps:
+- Async ghosts: Node Promise chains break, Go goroutine leaks
+- Resource exhaustion: Unclosed connections → pool starvation
+
+### 3. Surgical Fix – Minimal Invasion
+Guidelines:
+- Touch only the failure point (≤20 LOC)
+- Preserve old paths under feature flags
+- Idempotent: Retries must be safe
+- Rollback-friendly: No schema changes without migration
+
+```java
+// Bad – rewrites entire service
+@Transactional
+public User getUser(Long id) { ... }
+
+// Good – minimal guard
+@Transactional(readOnly = true)
+public User getUser(Long id) {
+    User user = repo.findById(id);
+    if (user == null) throw new UserNotFoundException(id); // Only this line added
+    return user;
+}
+```
+
+### 4. Full-Stack Validation – Iron Testing
+Unit green ≠ system stable.
+
+Checklist:
+- [ ] Unit: JUnit/Pytest (happy + edges + fault injection)
+- [ ] Integration: Testcontainers (real DB/Redis)
+- [ ] E2E/Load: k6/JMeter (network failures + peak load)
+- [ ] Staging: Prod-like env (exact Java/Go/Python versions)
+- [ ] Security: OWASP ZAP / Bandit static scan
+- [ ] Blind Regression: QA re-tests original steps blindly
+
+Pitfall: Local "Read Committed" hides prod Phantom Reads under concurrency.
+
+### 5. Future-Proofing – Immunize the System
+- AOP guards: Spring Interceptors for null checks
+- CI hooks: Linting for common patterns
+- Docs: PR tags "Bug #123 | Root: Concurrency | Fix: Lock"
+
+## Common Backend Pitfalls Checklist (2025)
+
+| Bug Type          | Scenario & Root Cause                          | Fix & Prevention                                      | Framework Traps                          |
+|-------------------|------------------------------------------------|-------------------------------------------------------|------------------------------------------|
+| **Logic/Data**    | N+1 queries, missing transaction rollback      | Fetch joins / pagination. Verify isolation levels     | Hibernate lazy init vs SQLAlchemy dialects |
+| **Concurrency**   | Shared state no lock, Go channel deadlock      | Mutex / optimistic locking. Run race detector         | Go sync.Map copies; Java Virtual Threads pinning |
+| **Performance**   | O(n²) loops, cache penetration                 | Indexing + Bloom filters. Redis rate limiting         | Node cluster imbalance; Python GIL on CPU |
+| **Security**      | SQL injection, JWT no signature                | Parameterized queries. OWASP scans                    | Spring Security scopes; FastAPI Pydantic |
+| **Resource Leak** | Unclosed connections, memory leaks             | RAII / try-with-resources. Profiling (Valgrind)       | Go defer close(); Java DirectByteBuffer |
+| **Compatibility** | Dep conflicts, serialization mismatch          | Version pinning. Protobuf schemas                     | Go mod vendor; Python AST changes        |
+| **Async/Net**     | Unhandled Promise rejects, timeouts            | Await coverage + timeouts. Mock externals             | Node AbortController; Gin middleware    |
+| **Observability** | Sensitive logs, missing trace IDs              | Structured + MDC. ELK tracing                         | Log4j vulns; Zap logger hooks            |
+| **Config Drift**  | Env fallback missing                           | Unified config (Viper). Smoke tests                   | Spring @Value defaults; Make ifdefs      |
+
+## Quick Copy-Paste Fixes
+
+```python
+# Atomic balance update (race-proof)
+cursor.execute(
+    "UPDATE accounts SET balance = balance - %s WHERE id = %s AND balance >= %s",
+    (amount, account_id, amount)
+)
+
+# Go error handling (no swallow)
+err := db.QueryRow("SELECT ...").Scan(&user)
+if err != nil {
+    return fmt.Errorf("query failed: %w", err) // Wrap, don't ignore
+}
+
+# Java try-with-resources (no leaks)
+try (Connection conn = dataSource.getConnection();
+     PreparedStatement stmt = conn.prepareStatement("...")) {
+    // Use stmt
+} // Auto-close
+```
+
+## PR Template for Backend Fixes
+
+```markdown
+## Bug Fix – Backend
+
+**Bug ID**: BUG-XXXX  
+**Severity**: High / Medium / Low  
+**Reproduction**: (Postman collection or k6 script link)
+
+**Root Cause**: (e.g., Missing row lock in concurrent update)
+
+**Fix Approach**: Atomic SQL update + feature flag (if zero-risk)
+
+**Validation**:
+- [x] Unit tests with fault injection
+- [x] Integration with Testcontainers
+- [x] Load test: 10k QPS no failures
+- [x] Staging smoke tests green
+- [x] No security scan regressions
+
+**Prevention**: Added to common-bugs.md + new linter rule

package/.claude/skills/bug-fixing/references/bug-guide.md

@@ -0,0 +1,354 @@
+# Bug Fixing Universal Guide
+
+This document provides cross-project bug patterns, detection methods, and fix strategies. Updated periodically by extracting patterns from project-level bug records.
+
+---
+
+## Common Bug Pattern Library
+
+### Category 1: Input Handling Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Format assumption mismatch** | User input doesn't match expected format | Check parser/validator logic | Add input normalization at parse time |
+| **Missing input validation** | Crash or unexpected behavior on edge input | Test with empty/null/special chars | Add validation before processing |
+| **Encoding issues** | Garbled text, truncation | Check charset handling | Ensure consistent UTF-8 throughout |
+| **Whitespace sensitivity** | Matching fails unexpectedly | Compare with trimmed values | Normalize whitespace at input |
+
+### Category 2: Status/State Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Status mismatch** | UI says success but operation failed | Check both HTTP and business status | Parse full response body |
+| **Stale state** | Shows outdated data after updates | Check state invalidation | Refresh state after mutations |
+| **Race condition** | Intermittent failures, order-dependent | Add timing logs, stress test | Add proper synchronization |
+| **Orphaned state** | Cleanup not triggered | Check cleanup paths | Ensure cleanup on all exit paths |
+
+### Category 3: API Integration Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Missing timeout** | Request hangs forever | Check timeout config | Add explicit timeout |
+| **No retry logic** | Transient failures cause permanent errors | Check retry implementation | Add retry with backoff |
+| **Response shape assumption** | Crash on unexpected API response | Check response parsing | Add defensive parsing |
+| **Missing error propagation** | Errors silently swallowed | Trace error flow | Ensure errors surface |
+
+### Category 4: Data Flow Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Transform mismatch** | Data displays incorrectly | Trace data path end-to-end | Fix transformation logic |
+| **Missing null check** | Crash on undefined/null | Check optional chaining | Add null guards |
+| **Off-by-one errors** | Pagination/indexing issues | Check boundary conditions | Verify index calculations |
+| **Type coercion** | Unexpected comparison results | Check type handling | Use explicit type conversion |
+| **State-Display Mismatch** | UI doesn't reflect state changes | Compare write format vs read logic | Ensure read logic handles all write formats |
+| **Parent-Child Selection Inconsistency** | Parent checked but children unchecked | Trace selection cascade logic | Read logic must check parent state |
+
+### Category 5: Configuration Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Environment mismatch** | Works in dev, fails in prod | Compare env configurations | Ensure config parity |
+| **Missing default** | Crash when config not set | Check fallback values | Add sensible defaults |
+| **Config priority confusion** | Wrong value used | Trace config loading order | Document config precedence |
+| **Secret exposure** | Secrets in logs/UI | Search for sensitive data | Redact before logging |
+
+### Category 5.1: 🔴 Multi-Environment Configuration Bugs (CRITICAL)
+
+> **This is the #1 cause of "fix doesn't work" scenarios!**
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Partial env file fix** | Fix works in prod, fails in dev | Check ALL .env* files | Update ALL environment files |
+| **Startup script mismatch** | bat/sh uses different env | Check startup scripts | Verify which env file each script uses |
+| **Config loading order** | Wrong value overrides correct one | Trace config loading | Document and fix precedence |
+| **Missing env variable** | Feature works locally, fails in CI/CD | Compare local vs CI env | Add variable to all environments |
+
+**Real-World Case Study:**
+```
+Problem: User's bat script used dev env file, but bug fix only added production env config
+Result: Bug persisted when running in dev mode
+
+Root Cause Analysis:
+- dev.bat → loads .env.development
+- npm run start → loads .env.production
+- Fix only updated .env.production
+- Dev mode never got the fix!
+
+Correct Fix:
+1. Identify ALL env files: .env, .env.development, .env.production, .env.test
+2. Identify ALL startup scripts: dev.bat, start.bat, npm scripts
+3. Map: script → env file → variable
+4. Apply fix to ALL relevant env files
+5. Verify in ALL modes
+```
+
+**Environment File Checklist (MANDATORY for config bugs):**
+
+| File | Check | Updated |
+|------|-------|---------|
+| `.env` | [ ] | [ ] |
+| `.env.local` | [ ] | [ ] |
+| `.env.development` | [ ] | [ ] |
+| `.env.development.local` | [ ] | [ ] |
+| `.env.test` | [ ] | [ ] |
+| `.env.staging` | [ ] | [ ] |
+| `.env.production` | [ ] | [ ] |
+| `.env.production.local` | [ ] | [ ] |
+
+**Startup Script Checklist:**
+
+| Script | Mode | Env File Used | Verified |
+|--------|------|---------------|----------|
+| `npm run dev` | Development | ? | [ ] |
+| `npm run start` | Production | ? | [ ] |
+| `dev.bat` / `dev.sh` | Development | ? | [ ] |
+| `start.bat` / `start.sh` | Production | ? | [ ] |
+| Docker Compose | Various | ? | [ ] |
+
+**Quick Detection Commands:**
+```bash
+# Find all env files
+find . -name ".env*" -o -name "*.env" 2>/dev/null
+
+# Search for a config key across all files
+grep -rn "YOUR_CONFIG_KEY" . --include="*.env*" --include="*.yml" --include="*.json"
+
+# Find startup scripts
+grep -rn "NODE_ENV\|VITE_\|REACT_APP_" . --include="*.sh" --include="*.bat" --include="package.json"
+```
+
+### Category 5.2: 🔴 JSON/Regex Processing Bugs (CRITICAL)
+
+> **This is a common cause of "hook error" or "parsing failed" scenarios!**
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------
+| **Unnecessary JSON preprocessing** | JSON parsing fails after "fix" | Check if input is already valid JSON | Remove unnecessary regex/preprocessing |
+| **Double-escaping backslashes** | `\\path` becomes `\\\path` | Compare input vs processed output | Trust the source, don't over-process |
+| **Regex breaking valid escapes** | Valid `\\` becomes invalid `\\\` | Test with Windows paths containing `\` | Verify regex doesn't match already-escaped chars |
+
+**Real-World Case Study:**
+```
+Problem: PowerShell hook script tried to "fix" Windows paths in JSON
+Result: Valid JSON like {"cwd":"D:\\test\\path"} became invalid {"cwd":"D:\\test\\\path"}
+
+Root Cause Analysis:
+- Claude Code passes properly escaped JSON (backslashes are already \\)
+- Script used regex to "fix" unescaped backslashes
+- Regex matched the second \ in \\ and added another \
+- Result: Triple backslash \\\ which is invalid JSON
+
+Correct Fix:
+1. Trust the input - Claude Code sends valid JSON
+2. Remove unnecessary preprocessing regex
+3. Parse JSON directly without modification
+```
+
+**JSON Processing Checklist (MANDATORY for hook scripts):**
+
+| Check | Action |
+|-------|--------|
+| Is input already valid JSON? | Test with `ConvertFrom-Json` directly first |
+| Does preprocessing break valid input? | Test with Windows paths like `D:\test\path` |
+| Is regex necessary? | Usually NO - trust the source |
+
+### Category 6: Platform-Specific Bugs
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **API not available** | Feature fails in specific environment | Check platform compatibility | Add feature detection/fallback |
+| **Permission denied** | Operation blocked | Check security config | Configure required permissions |
+| **Path handling** | File operations fail across OS | Check path separators | Use platform-agnostic paths |
+| **Binary vs text** | File corruption | Check read/write modes | Use correct mode for file type |
+
+---
+
+### Category 7: State-Display Consistency Bugs (NEW)
+
+These bugs occur when the **write path** (how data is stored) and **read path** (how data is displayed) use inconsistent logic.
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Write-Read Format Mismatch** | Action succeeds but UI doesn't update | Compare storage format vs display query | Align read query to handle all write formats |
+| **Derived State Inconsistency** | Parent/child selection out of sync | Trace state derivation chain | Derive child state from parent, not vice versa |
+| **Implicit vs Explicit State** | Checked item appears unchecked | Check if read assumes explicit storage | Read must handle implicit states (e.g., inherited from parent) |
+| **Partial Update** | Some UI elements update, others don't | Trace all consumers of the state | Ensure all consumers react to state changes |
+
+**Key Detection Questions:**
+1. **What format does the WRITE function store?** (e.g., `{ type: 'folder', id }`)
+2. **What format does the READ function expect?** (e.g., `t.type === 'interface'`)
+3. **Do they match?** If not, the read must be extended to handle write's format.
+
+**Common Scenario (Tree Selection):**
+- Write: Store parent selection → `[{ type: 'folder', id: 1 }]`
+- Read (buggy): Only checks `type === 'interface'` → Child shows unchecked
+- Read (fixed): Checks `type === 'interface' || parentIsSelected(id)` → Child shows checked
+
+---
+
+### Category 8: Component Integration & Feature Propagation (NEW)
+
+These bugs occur when a shared component is updated or reused, but not all consumers provide the required context or props.
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Incomplete Prop Propagation** | Feature works in one place, broken in others | Grep all component usages | Ensure all parents pass required props (or use Context) |
+| **Partial Feature Rollout** | New behavior only active in some views | Search for old pattern usage | Global search & replace / Centralize logic |
+| **Context Tunneling** | Component needs data not available in parent | Check component hierarchy | Lift state up or use Global Store/Context |
+| **Style/Theme Inconsistency** | Component looks different in different places | Check CSS inheritance/props | Standardize base styles or use design tokens |
+
+**Case Study: Variable Highlighting**
+- **Issue**: Added "gray out missing variables" feature to base `Highlight` component.
+- **Bug**: Only worked in Main Editor, not in Modal/Sidebar.
+- **Root Cause**: `availableVariables` prop was required but not passed by all parent components.
+- **Fix**: Created `useAvailableVariables` hook and updated ALL consumers (`BodyEditor`, `ParamEditor`, `HeaderEditor`) to pass the data.
+
+---
+
+### Category 9: UI Display Completeness Bugs (NEW)
+
+These bugs occur when backend returns data fields but frontend doesn't display them, or displays the wrong field for the context.
+
+| Pattern | Typical Symptom | Detection | Fix Strategy |
+|---------|-----------------|-----------|--------------|
+| **Missing Display Component** | Data exists but not shown in UI | Compare API response fields vs UI elements | Add UI component for missing fields |
+| **Wrong Field Priority** | Shows irrelevant data instead of expected | Check field selection logic | Use context-aware field selection |
+| **Destructured but Unused** | Variable destructured but not rendered | Search for destructured-but-unused vars | Add render logic for all destructured data |
+| **Method-agnostic Display** | Same logic for all HTTP methods | Check if display considers method type | Use method-aware logic (e.g., POST→body, GET→params) |
+
+**Case Study: Scheduled Task Report**
+- **Issue**: Report missing request headers; request body showing wrong data
+- **Bug 1**: `request_headers` destructured but no `RequestHeadersBlock` component
+- **Bug 2**: `content={request_params || request_body}` always prioritized params
+- **Fix 1**: Added `RequestHeadersBlock` component with table display
+- **Fix 2**: Method-aware priority: POST/PUT/PATCH→body first, GET/DELETE→params first
+
+**Display Priority Pattern for HTTP Requests:**
+```
+Method         Priority Display
+----------     ----------------
+GET            request_params > request_body
+DELETE         request_params > request_body
+POST           request_body > request_params
+PUT            request_body > request_params
+PATCH          request_body > request_params
+```
+
+---
+
+## High-Frequency Root Causes (Top 13)
+
+1. **Assumption without verification**: Assumed API/feature works without checking docs
+2. **Incomplete status checking**: Only checked HTTP status, not business status
+3. **Missing edge case handling**: Didn't consider empty/null/boundary inputs
+4. **Stale closure/state**: Captured old values in callbacks/effects
+5. **Missing cleanup**: Resources not released on error paths
+6. **Environment differences**: Dev/prod config mismatch
+7. **Type misunderstanding**: Wrong assumptions about data types
+8. **Async ordering**: Assumed sequential execution of async operations
+9. **Cache invalidation**: Stale cached data served
+10. **Error swallowing**: Caught errors but didn't surface them
+11. **State-Display Format Mismatch**: Write stores X, read expects Y
+12. **Incomplete Prop Propagation**: Updated base component but missed some consumers
+13. **UI Display Incompleteness**: Backend returns field but frontend doesn't render it (NEW)
+
+---
+
+## Universal Verification Checklist
+
+Before marking any bug as fixed:
+
+### Core Checks
+
+- [ ] **Original scenario**: Bug no longer reproduces with exact same steps
+- [ ] **Related features**: Adjacent features still work correctly
+- [ ] **Error paths**: Error cases handled gracefully
+- [ ] **Console/logs**: No new errors or warnings
+- [ ] **Build/lint**: Code passes all static checks
+
+### Edge Case Checks
+
+- [ ] **Empty input**: Handles empty/null/undefined
+- [ ] **Boundary values**: Handles min/max/zero values
+- [ ] **Concurrent access**: No race conditions introduced
+- [ ] **Resource cleanup**: No leaks on any exit path
+
+### Regression Checks
+
+- [ ] **Existing tests**: All tests still pass
+- [ ] **New tests**: Added tests for the bug scenario
+- [ ] **Similar patterns**: Checked for same bug elsewhere (Global Search)
+- [ ] **Prop consistency**: Verified all consumers of modified components
+
+---
+
+## Pattern Extraction Guide
+
+When you have 5-10 bug records in your project's `bugRecord.md`, extract common patterns:
+
+### Step 1: Identify Recurring Themes
+
+Group bugs by:
+- Root cause type (input handling, state, API, etc.)
+- Component/module affected
+- Symptom similarity
+
+### Step 2: Abstract to Universal Pattern
+
+Transform project-specific details to generic patterns:
+
+| Project-Specific | Universal Pattern |
+|------------------|-------------------|
+| "Excel column name ${keywords}" | "Wrapper syntax in user input" |
+| "API returns code: -1" | "Business status code in response body" |
+| "React state not updated" | "Stale closure in async callback" |
+
+### Step 3: Document in This Guide
+
+Add new patterns to the appropriate category table above with:
+- Pattern name
+- Typical symptom
+- Detection method
+- Fix strategy
+
+### Step 4: Update Verification Checklist
+
+If the pattern reveals a new verification need, add it to the checklist.
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why It's Bad | Better Approach |
+|--------------|--------------|-----------------|
+| **Fixing symptoms** | Root cause remains, bug recurs | Trace to true root cause |
+| **Massive refactor** | High regression risk | Minimal surgical fix |
+| **No verification** | Bug may not be fixed | Always test before claiming fixed |
+| **Silent fix** | Lost learning opportunity | Document for future reference |
+| **Assumption-based fix** | May introduce new bugs | Verify assumptions first |
+| **Partial Fix** | Similar bugs remain in codebase | Perform Global Search & Pattern Matching |
+
+---
+
+## Quick Reference
+
+### When Bug Recurs After "Fix"
+
+1. Re-read the original root cause analysis
+2. Check if fix addressed the actual root cause
+3. Verify fix was applied to the correct code path
+4. Consider if there are multiple entry points
+
+### When Similar Bug Appears
+
+1. Check if it's the same pattern as a previous bug
+2. Look for systemic fix (fix all instances, not just one)
+3. Update this guide with the pattern if new
+
+### When Unsure of Root Cause
+
+1. Add more logging/tracing
+2. Reproduce in debugger
+3. Compare working vs. broken scenarios
+4. Bisect to find the change that introduced it

package/.claude/skills/bug-fixing/references/bug-record-template.md

@@ -0,0 +1,134 @@
+# Bug Record Template (bugRecord.md)
+
+This template defines the standard format for project-level bug records. Create `bugRecord.md` in your project root directory using this structure.
+
+## File Header
+
+```markdown
+# Bug Record
+
+This document tracks bugs fixed in this project to prevent recurrence and enable pattern extraction.
+
+Last Updated: [YYYY-MM-DD]
+Total Records: [N]
+```
+
+## Record Entry Format
+
+Each bug fix should be documented using the following structure:
+
+```markdown
+---
+
+## [BUG-NNN] Brief Title
+
+**Date**: YYYY-MM-DD
+**Status**: Fixed | Reopened | Superseded by BUG-XXX
+**Severity**: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
+**Category**: [See categories below]
+
+### Symptom (What was observed)
+
+- User-visible behavior or error message
+- Steps to reproduce
+- Environment/context where it occurred
+
+### Root Cause (Why it happened)
+
+- One-sentence root cause statement
+- Technical explanation (file/function/line if helpful)
+- What assumption was wrong
+
+### Solution (How it was fixed)
+
+- Summary of the fix (what changed)
+- Key code changes (brief description, not full code)
+- Why this solution was chosen over alternatives
+
+### Verification (How we confirmed it's fixed)
+
+- [ ] Bug scenario no longer reproduces
+- [ ] Related features still work
+- [ ] No new errors in console/logs
+- [ ] Tests pass (if applicable)
+
+### Pattern Notes (For future reference)
+
+- Is this a recurring pattern? (Y/N)
+- Related bugs: [BUG-XXX, BUG-YYY]
+- Prevention suggestion for similar cases
+
+---
+```
+
+## Bug Categories
+
+Use one of the following categories:
+
+| Category | Description |
+|----------|-------------|
+| **Input Handling** | User input parsing, validation, normalization |
+| **State Management** | State sync, race conditions, stale data |
+| **API Integration** | External API calls, response handling, timeouts |
+| **Data Flow** | Data transformation, mapping, display |
+| **Error Handling** | Missing error handling, wrong error messages |
+| **Configuration** | Config mismatch, environment issues |
+| **UI/UX** | Layout, interaction, accessibility |
+| **Performance** | Slow operations, memory leaks, N+1 queries |
+| **Security** | Auth bypass, data exposure, injection |
+| **Platform** | Browser/OS specific, native app issues |
+
+## Example Entry
+
+```markdown
+---
+
+## [BUG-001] Success message shown but operation actually failed
+
+**Date**: 2025-01-05
+**Status**: Fixed
+**Severity**: P1 (High)
+**Category**: Error Handling
+
+### Symptom
+
+- User clicks "Save" button
+- UI shows "Saved successfully" toast
+- But data is not actually persisted
+- Only discovered when page is refreshed
+
+### Root Cause
+
+The code only checked HTTP status code (200) but ignored business status code in response body. The API returns 200 OK with `{"code": -1, "message": "..."}` for business errors.
+
+### Solution
+
+Added response body parsing to check business status code before showing success message:
+- Modified response handler to parse body
+- Added error display for business error codes
+- Updated all similar API calls
+
+### Verification
+
+- [x] Original scenario now shows error message correctly
+- [x] Successful saves still show success message
+- [x] No new console errors
+- [x] Unit tests added for both paths
+
+### Pattern Notes
+
+- Recurring pattern: Yes
+- Related bugs: None yet
+- Prevention: Always check response body for business status, not just HTTP status
+
+---
+```
+
+## Maintenance Guidelines
+
+1. **Add new entries at the top** (most recent first)
+2. **Update status** if a fix turns out to be wrong (mark as "Superseded")
+3. **Link related bugs** to track patterns
+4. **Review periodically** to extract common patterns for `bug-guide.md`
+5. **Keep entries concise** - focus on actionable information
+