@tinkcarlos/skillora 0.2.0

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

@@ -0,0 +1,219 @@
+# Frontend Bug-Fixing Guide – 2025 Edition
+
+> Battle-tested guide for React, Vue, TypeScript, Next.js, Vite, and modern browsers.
+
+20 years of hard-won experience distilled into one playbook.
+
+## Core Philosophy
+> “A frontend bug is never just CSS or React — it’s always state, timing, or contract.”
+
+## The 5-Step Frontend Repair Phases
+
+### 1. Reproduce & Isolate – Ghost Hunting
+90% of “works on my machine” failures come from environment drift.
+
+| Check                 | How to verify                                          |
+|-----------------------|--------------------------------------------------------|
+| Browser + version     | Chrome 128+, Safari 18+, Firefox 131+, Edge 128+         |
+| Device / viewport     | DevTools toggle device toolbar                         |
+| Network               | 3G / Offline throttling                                |
+| Auth / cookies        | Incognito vs logged-in session                         |
+| Build mode            | `vite build` (then serve the built output) vs `vite dev` (HMR can hide bugs) |
+
+Tools: Chrome DevTools Recorder, Playwright trace, BrowserStack
+
+### 2. Root Cause Analysis – Follow the Data Flow
+Always trace backwards from the symptom:
+
+```
+DOM/Console error 
+  ↓
+Component that threw 
+  ↓
+Props → State → Hook → API response → Network tab
+```
+
+Common hidden culprits:
+- React 18+ StrictMode double-mount (useEffect runs twice in dev)
+- Next.js SSR vs CSR hydration mismatch
+- Vite/React Fast Refresh keeping stale closures
+- RTK Query / SWR stale cache
+
+### 3. Minimal Viable Fix – Surgical Precision
+Rules (non-negotiable):
+- Never refactor while fixing a bug
+- Change < 20 LOC if possible
+- No new dependencies
+- Keep old code path when under zero-risk protocol
+
+```tsx
+// Bad – over-engineering
+return user ? <Profile user={user} /> : <NotFound />
+
+// Good – minimal + safe
+if (!user) return <NotFoundPage />
+return <Profile user={user} />
+```
+
+### 4. Multi-Layer Validation – Ironclad Proof
+Must all be green before asking for review:
+
+| Layer               | Tool / Command                                   | Required |
+|---------------------|--------------------------------------------------|----------|
+| Unit                | Jest / Vitest                                    | Yes      |
+| Component           | React Testing Library / Vue Test Utils           | Yes      |
+| Snapshot            | `.toMatchSnapshot()` (only for stable UI)        | Yes      |
+| Visual regression   | Chromatic / Percy / Playwright screenshots       | Yes      |
+| E2E                 | Playwright / Cypress (against staging)           | Yes      |
+| Cross-browser       | BrowserStack / Sauce Labs matrix                 | Yes      |
+| Accessibility       | axe-core / eslint-plugin-jsx-a11y                | Yes      |
+| Performance       | Lighthouse CI (no regression >5%)                | Yes      |
+
+### 5. Immunization & Documentation
+After the fix ships:
+
+- Add the pattern to common-bugs.md
+- Add a failing test that would have caught it
+- Create a custom ESLint rule or TypeScript utility type if recurring
+- Write a short “How I fixed it” in PR description (template below)
+
+## Most Common Frontend Pitfalls (2025)
+
+| Category               | Symptom                                    | Root Cause                                    | Instant Fix / Prevention                              |
+|------------------------|--------------------------------------------|-----------------------------------------------|-------------------------------------------------------|
+| React Keys             | List items duplicate/wrong order           | Using index as key                            | `key={item.id}` or `key={item.uniqueStableId}`        |
+| Stale Closures         | Button click uses old state                | Missing dependency or captured stale value    | `setCount(c => c+1)` or `useCallback` + correct deps   |
+| Hydration Mismatch     | Next.js warning in console                 | Server rendered different than client         | Use `useEffect` for client-only code, suppress correctly |
+| Memory Leak            | "Can't perform state update on unmounted"  | Async fetch without cleanup                   | `AbortController` + cleanup or `isMounted` ref        |
+| Double API Call        | Data fetched twice in dev                  | React 18 StrictMode double mount              | Ignore in dev or use `useEffectEvent` (React 19)      |
+| CSS z-index fails      | Element stays behind                       | No stacking context                           | Add `position: relative/absolute/fixed` + z-index     |
+| Flex item won't shrink | Text overflows container                   | `min-width: 0` missing on flex child          | `min-w-0` (Tailwind) or `min-width: 0`                |
+| Image/layout shift     | CLS > 0.1 in Lighthouse                    | No width/height on `<img>`                    | `width` + `height` attributes + `aspect-ratio` CSS    |
+| Dark mode broken       | Colors wrong in dark                      | Using wrong token or missing `prefers-color-scheme` | Use CSS variables + `color-scheme: light dark`        |
+| **Popup clipped/hidden** | Context menu/tooltip cut off at viewport edge | No boundary detection for positioned element | Use `useLayoutEffect` + viewport bounds check + flip logic |
+| **Dropdown overflow**  | Select/dropdown options hidden at bottom   | Parent has `overflow: hidden` or no flip logic | Add boundary-aware positioning or use portal rendering |
+
+## 🔴 UI Boundary Detection (Popup/Tooltip/ContextMenu)
+
+**Common Symptom**: Right-click menu, tooltip, dropdown, or popover is clipped or hidden when triggered near viewport edges.
+
+**Root Cause**: Fixed/absolute positioned elements use click coordinates directly without checking viewport boundaries.
+
+**Detection Questions**:
+1. "If user clicks near the bottom of the viewport, will the popup be fully visible?"
+2. "If user clicks near the right edge, will the popup overflow outside the screen?"
+3. "Does the popup/dropdown have flip logic for edge cases?"
+
+### Standard Fix Pattern
+
+```tsx
+// 🔴 BUG: Direct positioning without boundary check
+style={{ left: position.x, top: position.y }}
+
+// ✅ FIX: Boundary-aware positioning with useLayoutEffect
+const [adjustedPosition, setAdjustedPosition] = useState(position);
+
+useLayoutEffect(() => {
+  if (isOpen && menuRef.current) {
+    const menu = menuRef.current;
+    const rect = menu.getBoundingClientRect();
+    const viewportHeight = window.innerHeight;
+    const viewportWidth = window.innerWidth;
+    
+    let newX = position.x;
+    let newY = position.y;
+    
+    // Bottom boundary: flip upward if overflow
+    if (position.y + rect.height > viewportHeight - 10) {
+      newY = position.y - rect.height;
+      if (newY < 10) newY = 10; // Ensure not above viewport
+    }
+    
+    // Right boundary: flip leftward if overflow
+    if (position.x + rect.width > viewportWidth - 10) {
+      newX = position.x - rect.width;
+      if (newX < 10) newX = 10; // Ensure not outside left
+    }
+    
+    setAdjustedPosition({ x: newX, y: newY });
+  }
+}, [isOpen, position]);
+
+// Use adjustedPosition instead of position
+style={{ left: adjustedPosition.x, top: adjustedPosition.y }}
+```
+
+### Boundary Detection Checklist
+
+| Element Type | Bottom Edge | Right Edge | Top Edge | Left Edge |
+|-------------|-------------|------------|----------|-----------|
+| Context Menu | Flip up | Flip left | Clamp to 0 | Clamp to 0 |
+| Tooltip | Flip to top | Flip to left | Flip to bottom | Flip to right |
+| Dropdown | Flip up (dropup) | Scroll or truncate | N/A | N/A |
+| Modal | Center + scroll | Center + scroll | Center + scroll | Center + scroll |
+| Popover | Flip direction | Flip direction | Flip direction | Flip direction |
+
+### Search Pattern for Similar Issues
+
+```bash
+# Find all fixed/absolute positioned popup components
+grep -rn "position: fixed\|position: absolute" --include="*.tsx" --include="*.css" | grep -i "menu\|popup\|tooltip\|dropdown\|popover"
+
+# Find components using clientX/clientY without boundary check
+grep -rn "clientX\|clientY\|pageX\|pageY" --include="*.tsx" -A 5 | grep -v "innerHeight\|innerWidth\|getBoundingClientRect"
+
+# Find context menu implementations
+grep -rn "ContextMenu\|onContextMenu\|rightClick" --include="*.tsx"
+```
+
+### Libraries with Built-in Boundary Detection
+
+- **Radix UI** (`@radix-ui/react-dropdown-menu`, `@radix-ui/react-popover`)
+- **Floating UI** (`@floating-ui/react`) - Best for custom positioning
+- **Headless UI** (`@headlessui/react`)
+- **React Popper** (`react-popper`)
+
+## Quick Copy-Paste Fixes
+
+```tsx
+// 1. Safe optional chaining
+user?.profile?.settings?.theme ?? 'light'
+
+// 2. Correct useEffect dependencies
+useEffect(() => { ... }, [dep1, dep2]) // never [obj] or [arr]
+
+// 3. Abort fetch on unmount
+useEffect(() => {
+  const controller = new AbortController();
+  fetch(url, { signal: controller.signal });
+  return () => controller.abort();
+}, []);
+
+// 4. Stable list keys
+items.map(item => <Item key={item.id} item={item} />)
+
+// 5. Prevent layout shift<img src="…" width="400" height="300" alt="…" className="aspect-video object-cover" />
+```
+
+## PR Template for Frontend Fixes
+
+```markdown
+## Bug Fix – Frontend
+
+**Bug ID**: BUG-XXXX  
+**Severity**: High / Medium / Low  
+**Reproduction**: (link to recording or steps)
+
+**Root Cause**: (one sentence)
+
+**Fix Approach**: Minimal change + feature flag (if zero-risk)
+
+**Validation**:
+- [x] Unit tests added / updated
+- [x] Component tests pass
+- [x] Playwright E2E green on staging
+- [x] No Lighthouse regressions
+- [x] Accessibility score unchanged
+- [x] Works on Chrome / Safari / Firefox mobile
+
+**Prevention**: Added to common-bugs.md + new ESLint rule

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

@@ -0,0 +1,123 @@
+# Fullstack (Joint) Bug-Fixing Guide – 2025 Edition
+
+> Strategic guide for fixing bugs that span frontend-backend boundaries.
+
+For bugs that cross the frontend-backend divide. "Dual-wielding" approach to eliminate systemic wounds.
+
+## Core Philosophy
+> "Joint bugs aren't fixed by one team—they're collaborative erasures. The entire chain must heal, or the wound reopens."
+
+## The 5-Step Joint Repair Process
+
+### 1. Reproduce & Isolate – Dual-End Visibility
+**Why**: Mocked data hides the truth. Front/back environments rarely align.
+
+**Steps**:
+1. **Dual Reproduction**: Front: Record interaction (Cypress/Playwright); Back: Log request/response (Postman/JMeter).
+2. **Interface Isolation**: Network tab inspection—200 OK with wrong shape? Front ignoring valid error?
+3. **★ Sync Point**: Front + back engineers verify together (screen share required).
+
+**Tools**: Storybook (front isolation), WireMock (back mock), Docker multi-service compose.
+
+**Common Pitfall**: Cache Shadows—Redis expires on back, but browser cache holds stale data.
+
+### 2. Root Cause Analysis – Cross-Link Excavation
+**Why**: Bugs hide in team assumptions.
+
+**Techniques**:
+- **Cross-Domain 5 Whys**: Why empty list? → API empty. Why? → Back filter bug. Why? → Schema mismatch.
+- **Full Trace**: React props → Network request → Back span → DB query.
+- **Swimlanes**: Visualize data flow across boundaries (Miro/Excalidraw).
+
+**Common Pitfall**: Version Hallucinations—Front uses old SDK for new API.
+
+### 3. Design & Implement – Parallel Execution
+**Why**: Solo fixes cause drift. Contracts must bind.
+
+**Guidelines**:
+- **Minimal Dual-Fix**: Back: Logic/schema. Front: Guard clauses + types.
+- **Contract First**: OpenAPI/Swagger auto-generate clients.
+- **Idempotency**: Retries safe—no duplicate effects.
+- **★ Sync Point**: Feature flags for rollout. Mutual code review.
+
+**Common Pitfall**: Serialization Mismatch—Back `camelCase`, front expects `snake_case`.
+
+### 4. Full-Stack Validation – Unified Testing
+**Why**: Green units on both sides ≠ working system.
+
+**Checklist**:
+- [ ] **Dual Unit**: Front components + back services.
+- [ ] **E2E**: Cypress/Playwright vs real back (staging).
+- [ ] **Contract Tests**: Pact/Spring Cloud Contract (schema verification).
+- [ ] **★ Sync Point**: Joint blind regression testing.
+
+**Common Pitfall**: Security Headers—CORS on back, but front fetch misses `credentials: 'include'`.
+
+### 5. Immunize & Legacy – The Firewall
+**Why**: Joint bugs spread fast.
+
+**Actions**:
+- **Pipeline**: CI/CD schema diff checks.
+- **Gateway**: API gateway validation layers.
+- **Documentation**: Joint post-mortem (shared Notion/Slack thread).
+
+**Common Pitfall**: Documentation Lag—Swagger updated, but not pushed to front team.
+
+## Common Joint Pitfalls Checklist (2025)
+
+| Bug Type              | Scenario & Root Cause                  | Fix Checklist & Prevention                  | Compatibility Traps                  |
+|-----------------------|----------------------------------------|---------------------------------------------|--------------------------------------|
+| **Interface Mismatch**| Field added/removed/type changed       | Schema gen + type guards. Sync iterations   | GraphQL null resolvers; OpenAPI enums|
+| **State/Async Lost**  | Front timeout vs back slow             | WebSocket heartbeats / retry sync           | Socket.io namespaces; Axios timeouts |
+| **Performance Chain** | Slow query + front polling             | Indexing + debounce. Peak load test         | N+1 queries; React Query staleTime   |
+| **Security Gaps**     | CORS/JWT expiry drift                  | Header checks + token refresh logic         | OAuth2 PKCE; CSRF mismatch           |
+| **Data Offset**       | Pagination (page vs offset)            | Align logic. Keyed UI lists                 | Vue keys; DB offset bugs             |
+| **Compatibility**     | Polyfills vs back output               | Babel + version pinning                     | ESM imports; SSR hydration           |
+| **Cache Avalanche**   | Redis/browser sync                     | Unified TTL / ETags                         | Cluster issues; RTK Query keys       |
+| **Error Handling**    | 500 as generic error                   | Detailed codes + error boundaries           | Missing handlers; React ErrorBoundary|
+
+## Quick Copy-Paste Fixes
+
+```tsx
+// Front: Safe API response guard
+const { data, error } = useQuery(userId);
+if (error || !data?.user) return <NotFound />;
+
+// Back: Proper error response
+if (!user) {
+  throw new HttpException('User not found', HttpStatus.NOT_FOUND);
+}
+
+// Contract: OpenAPI snippet
+responses:
+  404:
+    description: User not found
+    content:
+      application/json:
+        schema:
+          type: object
+          properties:
+            error: { type: string }
+```
+
+## PR Template for Joint Fixes
+
+```markdown
+## Joint Bug Fix – Fullstack
+
+**Bug ID**: BUG-XXXX  
+**Severity**: High / Medium / Low  
+**Reproduction**: (Cypress video + Postman collection)
+
+**Root Cause**: (e.g., Schema version mismatch between front SDK and back API)
+
+**Fix Approach**: Back schema update + front type guard + contract test
+
+**Validation**:
+- [x] Dual unit tests pass
+- [x] Pact contract verification green
+- [x] E2E on staging (real back)
+- [x] Mutual code review (front + back)
+- [x] No schema drift in CI
+
+**Prevention**: Added schema diff to CI + updated Swagger docs

package/.claude/skills/bug-fixing/references/functional-breakage.md

@@ -0,0 +1,117 @@
+# Functional Breakage Detection
+
+> Detect features that "look complete but are actually unimplemented".
+
+## What is Functional Breakage?
+
+| Type | Description | Example | Detection Method |
+|------|-------------|---------|------------------|
+| **Placeholder Bug** | UI exists but functionality missing | Login page only has `<h1>Login</h1>` | Check component implementation |
+| **Integration Gap** | Backend exists but frontend doesn't call it | Auth API ready, frontend hardcoded | grep API calls |
+| **Flow Breakage** | Individual parts work but overall flow broken | Login succeeds but token not stored | Trace complete data flow |
+| **Contract Mismatch** | Frontend/backend field names differ | `{message}` vs `{content}` | Compare schemas |
+| **Silent Failure** | No errors but feature doesn't work | Button click does nothing | Check empty handlers |
+
+---
+
+## Detection Commands
+
+### Placeholder & Stub Code Detection
+
+```bash
+# 1. Find explicit placeholder markers
+grep -rn "Coming Soon\|TODO\|FIXME\|Not Implemented\|Placeholder" --include="*.tsx" --include="*.ts" --include="*.py"
+
+# 2. Find empty handlers (silent failures)
+grep -rn "onClick={() => {}}\|onChange={() => {}}\|onSubmit={() => {}}" --include="*.tsx"
+
+# 3. Find single-line placeholder pages (CRITICAL - catches fake pages)
+grep -rn "const.*=.*().*=>.*<div>.*</div>" --include="*.tsx" | grep -v "test\|spec\|mock"
+grep -rn "const.*=.*().*=>.*<h1>" --include="*.tsx" | grep -v "test\|spec"
+
+# 4. Find stub functions
+grep -rn "pass  # TODO\|raise NotImplementedError\|throw new Error.*not implemented" --include="*.py" --include="*.ts"
+
+# 5. Find commented-out code that should be active
+grep -rn "// api\.\|# api\.\|// fetch\|# requests\." --include="*.ts" --include="*.py"
+```
+
+### Authentication Flow Detection
+
+```bash
+# 6. Check login component implementation
+echo "=== Login Component ==="
+grep -rn "const.*Login\|function Login" --include="*.tsx" -A 15
+
+# 7. Check if login API is called
+echo "=== Login API Calls ==="
+grep -rn "auth/login\|/login" --include="*.ts" --include="*.tsx" | grep -v "route\|path\|href"
+
+# 8. Check token storage
+echo "=== Token Storage (SET) ==="
+grep -rn "localStorage.setItem.*token\|sessionStorage.setItem.*token\|setToken\|saveToken" --include="*.ts"
+
+echo "=== Token Usage (GET) ==="
+grep -rn "localStorage.getItem.*token\|sessionStorage.getItem.*token\|getToken" --include="*.ts"
+
+# 9. Check route guards
+echo "=== Route Guards ==="
+grep -rn "ProtectedRoute\|PrivateRoute\|AuthGuard\|RequireAuth\|isAuthenticated" --include="*.tsx"
+
+# 10. Check 401 error handling
+echo "=== 401 Handling ==="
+grep -rn "401\|Unauthorized\|not authenticated" --include="*.ts" --include="*.tsx"
+```
+
+### Frontend-Backend Contract Detection
+
+```bash
+# 11. Backend request models
+echo "=== Backend Request Models ==="
+grep -rn "class.*Request.*BaseModel\|class.*Schema" --include="*.py" -A 8
+
+# 12. Frontend request bodies
+echo "=== Frontend Request Bodies ==="
+grep -rn "JSON.stringify\|body:" --include="*.ts" --include="*.tsx" -B 2 -A 5
+
+# 13. SSE event sending (backend)
+echo "=== Backend SSE Events ==="
+grep -rn "event:.*data:\|yield.*event" --include="*.py" -A 3
+
+# 14. SSE event handling (frontend)
+echo "=== Frontend SSE Handlers ==="
+grep -rn "onmessage\|msg.event\|event ===" --include="*.ts" --include="*.tsx" -A 8
+```
+
+---
+
+## Classification Decision Matrix
+
+| Scenario | Evidence | Classification | Action |
+|----------|----------|----------------|--------|
+| Code exists, has defect | Logic/syntax error | **BUG** | Continue with fix workflow |
+| Component is placeholder | Single-line `<h1>` or `<div>` | **Missing Feature** | Escalate to product owner |
+| Code exists but not connected | No fetch/axios calls | **Integration Bug** | Add integration first |
+| Field names don't match | `message` vs `content` | **Contract Bug** | Fix field names |
+| API exists but not called | Backend works, frontend doesn't call | **Integration Bug** | Add API call |
+| Upstream dependency missing | Depends on unimplemented feature | **Blocked** | Fix dependency first |
+
+---
+
+## If It's Not a Real Bug
+
+```
+🛑 INVESTIGATION STOPPED
+
+Classification: [Missing Feature / Integration Bug / Contract Bug / Blocked]
+
+Evidence:
+- [Paste grep output or code screenshot]
+
+This is NOT a code defect. Required actions:
+- [ ] Route to development team for implementation
+- [ ] Create feature request ticket
+- [ ] Update documentation to reflect actual status
+
+Do NOT proceed with bug-fixing workflow for non-bugs.
+```

package/.claude/skills/bug-fixing/references/ide-lint-errors-guide.md

@@ -0,0 +1,176 @@
+# IDE Lint Errors Detection and Resolution Guide
+
+IDE red squiggly lines (lint errors) indicate code quality issues that must be resolved before code can be considered complete. This guide provides a systematic approach to detecting, categorizing, and fixing these errors.
+
+## Overview
+
+Red underlines in code editors represent diagnostics from language servers, linters, and type checkers. They indicate issues ranging from simple syntax errors to complex type mismatches. Treating these as blocking issues prevents bugs from reaching production.
+
+## Error Categories
+
+### 1. Syntax Errors (P0 - Must Fix Immediately)
+
+**Symptoms**: Code won't compile/parse; immediate red underlines on basic code structure.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Missing semicolons, commas, colons | Parser error at specific line | Add missing punctuation |
+| Unmatched brackets/braces/parentheses | Error often at end of block | Use editor bracket matching to find pair |
+| Typos in keywords (`fucntion`, `retrun`) | "Unknown identifier" error | Correct spelling |
+| Invalid syntax constructs | "Unexpected token" error | Check language syntax rules |
+
+### 2. Type Errors (P0/P1 - Critical)
+
+**Symptoms**: Type checker reports mismatches; often shows expected vs actual types.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Type mismatch in assignment | "Type X not assignable to Y" | Cast, convert, or fix source type |
+| Undefined type reference | "Cannot find type X" | Import type or define it |
+| Wrong generic parameters | "Expected N type arguments" | Check generic signature |
+| Null/undefined not handled | "Object possibly undefined" | Add null checks or assertions |
+| Incorrect function return type | "Return type mismatch" | Fix return statement or signature |
+
+### 3. Import/Module Errors (P1 - Must Fix)
+
+**Symptoms**: Imports highlighted red; "module not found" messages.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Missing import statement | "X is not defined" | Add import for the symbol |
+| Wrong import path | "Cannot find module X" | Check relative/absolute path |
+| Circular dependencies | Complex error, often runtime | Refactor to break cycle |
+| Package not installed | "Cannot find module X" | Install package via package manager |
+| Wrong export/import style | "X has no default export" | Match import style to export |
+
+### 4. Linting Rule Violations (P2/P3 - Should Fix)
+
+**Symptoms**: Warnings or errors from ESLint, Pylint, Ruff, etc.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Unused variables/imports | "X is defined but never used" | Remove or use the symbol |
+| Code style violations | Various formatting warnings | Auto-fix or manual adjustment |
+| Deprecated API usage | "X is deprecated" | Update to recommended API |
+| Unsafe patterns | Security/safety warnings | Refactor to safe pattern |
+| Complexity warnings | "Function too complex" | Refactor to simpler structure |
+
+### 5. Declaration Errors (P1 - Must Fix)
+
+**Symptoms**: Variables or functions highlighted as undefined.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Using before declaration | "X used before defined" | Move declaration before use |
+| Missing variable declaration | "X is not defined" | Add let/const/var or import |
+| Scope issues | "X is not accessible" | Check variable scope |
+| Missing function definition | "X is not a function" | Define or import function |
+
+### 6. Configuration Issues (P1 - Must Fix)
+
+**Symptoms**: Errors not related to specific code lines; often project-wide.
+
+| Common Causes | Detection | Fix Approach |
+|---------------|-----------|--------------|
+| Missing tsconfig.json | TypeScript errors everywhere | Create/fix tsconfig.json |
+| Wrong compiler options | Unexpected type behavior | Check and fix compiler settings |
+| Missing type definitions | "Cannot find type X" for packages | Install @types/X package |
+| ESLint/Pylint misconfiguration | Inconsistent linting | Check linter config files |
+| Python virtual env issues | Import errors for installed packages | Activate correct venv |
+
+## Detection Workflow
+
+### Step 1: Run `read_lints` Tool
+
+```
+read_lints(paths: ["path/to/modified/file.ts"])
+```
+
+This returns all diagnostics (errors, warnings, hints) for the specified files.
+
+### Step 2: Categorize Errors
+
+Group errors by category using the table above:
+- **P0 (Syntax, Critical Type)**: Fix immediately, blocks execution
+- **P1 (Import, Declaration, Type, Config)**: Fix before commit
+- **P2 (Linting warnings)**: Fix or document suppression
+- **P3 (Style nits)**: Optional, follow team conventions
+
+### Step 3: Fix in Priority Order
+
+1. Fix all P0 errors first (code won't work otherwise)
+2. Fix all P1 errors (code may have runtime issues)
+3. Fix P2 errors or add justified suppressions
+4. Optionally fix P3 style issues
+
+### Step 4: Verify Resolution
+
+Run `read_lints` again to confirm:
+- No new errors introduced
+- Original errors resolved
+- No cascading issues from fixes
+
+## Resolution Strategies by Language
+
+### TypeScript/JavaScript
+
+| Error Pattern | Quick Fix |
+|---------------|-----------|
+| "Cannot find name 'X'" | Add import: `import { X } from 'module'` |
+| "Type 'X' is not assignable to 'Y'" | Check types, add cast if intentional |
+| "Object is possibly 'undefined'" | Add optional chaining `?.` or null check |
+| "Property 'X' does not exist" | Check spelling, add property to interface |
+| "Module has no exported member 'X'" | Check export name, use correct import |
+
+### Python
+
+| Error Pattern | Quick Fix |
+|---------------|-----------|
+| "Undefined name 'X'" | Add import or define variable |
+| "X is not defined" (Pylint) | Import missing module |
+| "Missing type annotation" | Add type hint: `def f(x: int) -> str:` |
+| "Incompatible types" (mypy) | Fix type mismatch or add cast |
+| "Module 'X' has no attribute 'Y'" | Check module API, fix import |
+
+### General Patterns
+
+| Error Pattern | Quick Fix |
+|---------------|-----------|
+| Unmatched brackets | Use editor bracket matching |
+| Trailing whitespace | Configure editor auto-trim |
+| Unused imports | Remove or add usage |
+| Undefined symbol | Add import or declaration |
+| Type assertion needed | Add type annotation or cast |
+
+## Verification Checklist
+
+Before marking code as complete:
+
+- [ ] Run `read_lints` on ALL modified files
+- [ ] Zero P0 errors (syntax, critical type)
+- [ ] Zero P1 errors (imports, declarations, config)
+- [ ] P2 errors fixed or documented with justification
+- [ ] No new errors introduced during fixes
+- [ ] Related files also checked (imports may cascade)
+
+## Common Pitfalls
+
+| Pitfall | Why It Happens | Prevention |
+|---------|----------------|------------|
+| Fixing one error creates another | Type changes cascade | Check all usages before changing types |
+| Ignoring warnings | "It still runs" mentality | Treat warnings as errors in CI |
+| Suppressing without reason | Quick fix habit | Always document suppression reason |
+| Not checking related files | Focus on single file | Run lints on entire changed set |
+| Missing transitive dependencies | Import from imported module | Check full dependency chain |
+
+## Integration with Bug-Fixing Workflow
+
+This guide is part of the verification gate (Phase 5). After applying a fix:
+
+1. Run `read_lints` on all modified files
+2. Treat any red underlines as potential regressions
+3. Verify fix didn't introduce new type/import issues
+4. Document any intentional lint suppressions in PR
+
+→ Return to main workflow: Phase 5 Verification Gate
+