skillstore-cli 1.0.0

package/data/shared/framework/skills/debugging-investigation/references/systematic-debugging.md

@@ -0,0 +1,197 @@
+# Systematic Debugging Techniques
+
+## The Scientific Method Applied to Debugging
+
+Every debugging session should follow the scientific method. This prevents random code changes and keeps investigation focused.
+
+```
+1. OBSERVE    — Collect symptoms, logs, error messages, reproduction steps
+2. HYPOTHESIZE — Form 2-4 ranked explanations for the observed behavior
+3. PREDICT    — For each hypothesis, predict what evidence you'd find if it's true
+4. TEST       — Gather that evidence (logs, breakpoints, profiling, experiments)
+5. CONCLUDE   — Accept or reject each hypothesis based on evidence
+6. REPEAT     — If all hypotheses rejected, return to step 1 with new information
+```
+
+### Hypothesis Template
+
+```
+Hypothesis: [Description of suspected root cause]
+If true, I expect: [Observable prediction]
+Test: [How to verify the prediction]
+Result: [What was actually observed]
+Verdict: CONFIRMED / REFUTED / INCONCLUSIVE
+```
+
+Always test at least 2 hypotheses. If you only have one, you're likely anchored to it.
+
+## Binary Search Debugging (Bisecting the Problem Space)
+
+The most efficient general-purpose technique. Divide the problem space in half repeatedly to locate the fault.
+
+### Code Bisection
+- Comment out half the code path, see if the bug persists
+- If yes: bug is in the remaining half. Repeat.
+- If no: bug is in the removed half. Restore and bisect that half.
+- Converges in O(log n) steps instead of O(n)
+
+### Git Bisect
+```bash
+git bisect start
+git bisect bad                    # current commit has the bug
+git bisect good <known-good-sha> # this commit was fine
+# Git checks out a midpoint. Test it, then:
+git bisect good  # or  git bisect bad
+# Repeat until git identifies the first bad commit
+git bisect reset                  # return to original HEAD
+```
+
+Automate with a test script:
+```bash
+git bisect run npm test -- --grep "failing test name"
+```
+
+### Data Bisection
+- For data-dependent bugs, bisect the input data
+- Process first half of records — bug present? Then it's in that half.
+- Useful for CSV imports, batch jobs, migration scripts
+
+### Configuration Bisection
+- Revert half the config changes between working and broken state
+- Especially useful for webpack/vite/bundler config debugging
+
+## Rubber Duck Debugging (Structured Articulation)
+
+Explaining the problem forces you to organize your understanding and often reveals gaps.
+
+### The Protocol
+1. State the expected behavior in one sentence
+2. State the actual behavior in one sentence
+3. Explain the code path from input to output, step by step
+4. At each step, state what you KNOW vs. what you ASSUME
+5. The bug is usually hiding in an assumption
+
+### When to Use
+- You've been staring at the code for more than 20 minutes
+- The bug "makes no sense" — this means your mental model is wrong
+- Before asking for help — articulate first, then ask
+
+### Written Variant
+Write a detailed bug report to yourself. Include:
+- Exact inputs that trigger the bug
+- Exact output (including off-by-one specifics)
+- The 3 most relevant code snippets
+- What you've already tried and ruled out
+
+## Time-Travel Debugging (Replay-Based Investigation)
+
+Record program execution and replay it backwards from the failure point.
+
+### Tools
+- **rr** (Linux): Record and replay with GDB. Step backwards through execution.
+- **Replay.io**: Record browser sessions, step through with DevTools retroactively
+- **Redux DevTools**: Time-travel through state changes in Redux apps
+- **Flutter DevTools Timeline**: Scrub through frame-by-frame rendering
+
+### When to Use
+- Bug that's hard to reproduce — record it once, replay many times
+- Bug that disappears when you add logging (Heisenbug)
+- Race condition where execution order matters
+- Understanding complex state transitions
+
+### Strategy
+1. Record the failing execution
+2. Start at the failure point (crash, wrong value, bad state)
+3. Work backwards: where did this wrong value come from?
+4. Follow the chain of causation to the root
+
+## Differential Debugging (What Changed?)
+
+Compare the working state against the broken state to isolate the change that caused the bug.
+
+### Git-Based Differential
+```bash
+# What changed since last known-good state?
+git diff <good-sha>..HEAD --stat
+git diff <good-sha>..HEAD -- src/
+
+# What was deployed?
+git log <deployed-sha>..HEAD --oneline
+
+# What dependencies changed?
+diff <(git show <good-sha>:package-lock.json) <(cat package-lock.json)
+```
+
+### Environment Differential
+- Compare environment variables between working and broken environments
+- Compare package versions (lock files)
+- Compare runtime versions (Node, Python, Java)
+- Compare OS-level differences (locale, timezone, file system)
+
+### Request Differential
+- Compare a working request vs. a failing request (headers, body, auth tokens)
+- Use diff on curl verbose output or HAR file exports
+
+## Decision Tree: Which Technique for Which Bug Type
+
+### Timing / Race Condition Bugs
+1. Add logging with timestamps to suspect operations
+2. Use time-travel debugging if available
+3. Introduce artificial delays to amplify the race
+4. Look for missing locks, unguarded shared state, or non-atomic operations
+
+### State / Data Bugs
+1. Trace the data from input to the point where it's wrong
+2. Binary search on the code path (where does the value diverge from expected?)
+3. Check boundary conditions: null, empty, zero, negative, max-int, unicode
+4. Compare working vs. broken request payloads
+
+### Rendering / Layout Bugs
+1. Inspect with browser DevTools Elements panel
+2. Disable CSS one section at a time (binary search)
+3. Check computed styles vs. expected styles
+4. Test in isolation: does the component work outside its parent?
+
+### Network / API Bugs
+1. Inspect actual request/response in Network panel or proxy
+2. Compare against API documentation
+3. Check headers: Content-Type, Authorization, CORS
+4. Test with curl to eliminate client-side code as a variable
+
+### Authentication / Authorization Bugs
+1. Decode and inspect tokens (JWT claims, expiry)
+2. Check clock skew between client and server
+3. Verify token refresh flow
+4. Compare request headers for working vs. failing calls
+
+### Performance Bugs
+1. Profile first, optimize second — never guess where the bottleneck is
+2. Use flame charts to identify the hot path
+3. Check for N+1 queries with query logging
+4. Measure: wall time, CPU time, memory allocation, I/O wait
+
+## Common Cognitive Biases in Debugging
+
+### Confirmation Bias
+- **Trap**: You decide it's a caching issue, then only look for cache-related evidence
+- **Fix**: Actively try to DISPROVE your hypothesis. What evidence would refute it?
+
+### Anchoring Bias
+- **Trap**: The first clue you find dominates your thinking, even if it's misleading
+- **Fix**: Always maintain 2+ hypotheses. Force yourself to investigate the less likely one too.
+
+### Recency Bias
+- **Trap**: You blame the most recent change, even if the bug was latent
+- **Fix**: Check: could this bug have existed before the recent change? Write a test and run it against an older commit.
+
+### Availability Bias
+- **Trap**: "Last time it was a database issue, so this must be too"
+- **Fix**: Let the symptoms drive the investigation, not past experience alone.
+
+### Sunk Cost Bias
+- **Trap**: You've spent 2 hours on one hypothesis and refuse to abandon it
+- **Fix**: Set a timebox (30 minutes). If no progress, switch hypotheses. Your time spent is gone either way.
+
+### The Heisenbug Trap
+- **Trap**: Adding debug logging changes the timing and makes the bug disappear
+- **Fix**: Use non-invasive observation (profilers, replay tools, OS-level tracing). Or add logging and look for a DIFFERENT failure mode.

package/data/shared/framework/skills/debugging-investigation/references/tool-specific-guides.md

@@ -0,0 +1,202 @@
+# Tool-Specific Debugging Guides
+
+## Chrome DevTools
+
+### Performance Panel
+- **Recording**: Click record, reproduce the issue, stop. Shorter recordings are easier to analyze.
+- **Flame Chart**: Read top-down. Wide bars = long tasks. Look for unexpected width (blocking calls).
+- **Main Thread**: Yellow = scripting, purple = rendering, green = painting. A wall of yellow means JavaScript is blocking.
+- **Long Tasks**: Any task >50ms blocks the main thread. Look for these as the cause of janky UI.
+- **Bottom-Up Tab**: Sort by "Self Time" to find the actual functions consuming CPU, not just callers.
+- **User Timing marks**: Add `performance.mark('start')` and `performance.measure('operation', 'start')` to your code for custom markers in the timeline.
+
+### Memory Panel
+- **Heap Snapshot**: Take two snapshots (before and after the suspected leak). Use "Comparison" view to see what was allocated between them.
+- **Allocation Timeline**: Shows allocations over time. Blue bars that persist = potential leaks. Grey bars = garbage collected (fine).
+- **Retained Size vs Shallow Size**: Retained size includes all objects kept alive by this reference. A small object with huge retained size is holding a reference chain.
+- **Detached DOM nodes**: Filter by "Detached" in the snapshot. These are DOM nodes removed from the tree but still referenced in JavaScript.
+
+### Network Panel
+- **Waterfall**: Long blue bars = waiting for server (TTFB). Long green bars = downloading (payload size).
+- **Throttling**: Simulate slow connections to find race conditions hidden by fast local networks.
+- **Request Blocking**: Right-click a domain to block it. Useful for testing fallback behavior and third-party impact.
+- **Copy as cURL**: Right-click any request to get an exact curl command for reproduction outside the browser.
+- **Preserve log**: Enable to keep requests across page navigations — essential for debugging redirects.
+
+### Sources Panel
+- **Conditional Breakpoints**: Right-click line number → "Add conditional breakpoint". Only breaks when expression is true. Example: `userId === 'abc123'`.
+- **Logpoints**: Right-click → "Add logpoint". Logs without modifying code or pausing execution. Example: `'Request:', JSON.stringify(req.body)`.
+- **XHR Breakpoints**: Break on any request matching a URL pattern. Useful for finding which code triggers an API call.
+- **Event Listener Breakpoints**: Under "Event Listener Breakpoints" panel, expand categories (Mouse, Keyboard, Timer). Breaks when events fire.
+- **Blackboxing**: Right-click a library file → "Add script to ignore list". Debugger skips over blackboxed code when stepping.
+
+## Node.js Debugging
+
+### Built-in Inspector
+```bash
+# Start with inspector
+node --inspect src/server.js
+
+# Break on first line
+node --inspect-brk src/server.js
+
+# Then open chrome://inspect in Chrome and connect
+```
+
+### Clinic.js Suite
+```bash
+# Doctor — overall health check (event loop, CPU, memory, I/O)
+npx clinic doctor -- node src/server.js
+# Then generate load with autocannon or ab, and stop the process. Opens HTML report.
+
+# Flame — CPU profiling as flame graph
+npx clinic flame -- node src/server.js
+# Wide bars at the bottom = hot path. Look for your code, not Node internals.
+
+# Bubbleprof — async flow visualization
+npx clinic bubbleprof -- node src/server.js
+# Shows async operation relationships. Large bubbles = long async delays.
+```
+
+### 0x Flame Graphs
+```bash
+npx 0x src/server.js
+# Generate load, then Ctrl+C. Opens interactive flame graph in browser.
+# Click to zoom into stack frames. Look for "plateaus" — flat wide areas are bottlenecks.
+```
+
+### Useful Flags
+```bash
+# Trace warnings with stack traces
+node --trace-warnings src/server.js
+
+# Track promise rejections
+node --unhandled-rejections=strict src/server.js
+
+# Expose GC for memory debugging
+node --expose-gc --inspect src/server.js
+```
+
+## React DevTools
+
+### Profiler
+- **Commit Chart**: Each bar is a render commit. Tall bars = slow renders. Click to see which components rendered.
+- **Ranked Chart**: Components sorted by render time. Focus optimization on the top items.
+- **"Why did this render?"**: Enable in Profiler settings. Shows whether a render was caused by props change, state change, hooks change, or parent re-render.
+- **Highlight Updates**: In settings, enable "Highlight updates when components render". Blue = infrequent, yellow/red = too frequent.
+
+### Component Inspector
+- Click any component to see current props, state, and hooks values
+- Edit props/state live to test different scenarios without changing code
+- "Rendered by" shows the parent chain — useful for understanding why something re-rendered
+- "Source" link jumps to the component definition in the Sources panel
+
+### why-did-you-render (Library)
+```javascript
+// In development entry point:
+import React from 'react';
+if (process.env.NODE_ENV === 'development') {
+  const whyDidYouRender = require('@welldone-software/why-did-you-render');
+  whyDidYouRender(React, { trackAllPureComponents: true });
+}
+```
+Logs to console when a component re-renders with unchanged props (wasted render).
+
+## Flutter DevTools
+
+### Widget Inspector
+- Select widgets in the app to see the widget tree, render object properties, and constraints
+- "Select Widget Mode": tap on any widget in the running app to jump to it in the inspector
+- Layout explorer: visualize flex layouts, see main axis / cross axis alignment and overflow
+
+### Timeline (Performance)
+- **Frame Chart**: Each bar is a frame. Bars exceeding 16ms (for 60fps) cause jank.
+- **UI thread vs Raster thread**: UI = widget build/layout. Raster = painting to GPU. Identify which thread is the bottleneck.
+- **Shader compilation jank**: First-run jank often caused by shader compilation. Use `flutter run --profile --cache-sksl` to warm shaders.
+
+### Memory
+- **Dart heap**: Shows current allocations. Take snapshots to compare over time.
+- **GC events**: Frequent GC = high allocation rate. Reduce object churn.
+- **Leaks**: Objects that survive multiple GC cycles and keep growing indicate leaks. Check for undisposed controllers, streams, and animation controllers.
+
+### CPU Profiler
+- Record CPU profile during a specific interaction
+- Bottom-up view shows which Dart functions consumed the most CPU
+- Filter to "My Code" to hide framework internals
+
+## Database Debugging
+
+### EXPLAIN ANALYZE (PostgreSQL)
+```sql
+EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) SELECT ...;
+```
+- **Seq Scan**: Full table scan. Fine for small tables, problematic for large ones. Consider adding an index.
+- **Nested Loop**: For each row in outer, scans inner. Acceptable for small sets, disastrous for large ones (N+1 at DB level).
+- **actual time**: First number = time to first row, second = time to all rows. Large gap means streaming is possible.
+- **Buffers: shared hit vs read**: Hit = in cache, read = from disk. High read count = cold cache or working set exceeds memory.
+- **rows=X vs actual rows=Y**: Large discrepancy means stale statistics. Run `ANALYZE tablename`.
+
+### pg_stat_statements
+```sql
+SELECT query, calls, mean_exec_time, total_exec_time
+FROM pg_stat_statements
+ORDER BY total_exec_time DESC
+LIMIT 20;
+```
+Shows the most expensive queries across the entire database.
+
+### Slow Query Log (MySQL)
+```ini
+# my.cnf
+slow_query_log = 1
+long_query_time = 1   # seconds
+log_queries_not_using_indexes = 1
+```
+Then analyze with `mysqldumpslow` or `pt-query-digest`.
+
+## VS Code Debugger
+
+### Node.js launch.json
+```jsonc
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "name": "Debug Server",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/src/server.js",
+      "env": { "NODE_ENV": "development" },
+      "console": "integratedTerminal"
+    },
+    {
+      "name": "Debug Current Test",
+      "type": "node",
+      "request": "launch",
+      "program": "${workspaceFolder}/node_modules/.bin/jest",
+      "args": ["--runInBand", "--no-coverage", "${relativeFile}"],
+      "console": "integratedTerminal"
+    }
+  ]
+}
+```
+
+### Compound Debugging (Frontend + Backend)
+```jsonc
+{
+  "compounds": [
+    {
+      "name": "Full Stack",
+      "configurations": ["Debug Server", "Debug Client"],
+      "stopAll": true
+    }
+  ]
+}
+```
+Launches both debuggers simultaneously. Set breakpoints across client and server code in one session.
+
+### Useful Features
+- **Data Breakpoints**: Right-click a variable in the Variables panel → "Break on Value Change". Stops when the value changes anywhere.
+- **Inline Values**: Shows variable values inline in the editor during debugging (enabled by default).
+- **Debug Console**: Evaluate expressions in the current scope. Full REPL access at breakpoints.
+- **Call Stack**: Click frames to jump between call sites. "Restart Frame" re-executes from that point.

package/data/shared/framework/skills/debugging-investigation/references/troubleshooting-patterns.md

@@ -0,0 +1,196 @@
+# Troubleshooting Patterns
+
+Common bug patterns with their symptoms, diagnosis strategies, and fixes.
+
+## Race Conditions
+
+### Symptoms
+- Bug is intermittent — works most of the time, fails unpredictably
+- Bug disappears when you add logging or use a debugger (timing changes)
+- Different results on fast vs. slow machines or under load
+- "It works on my machine" across team members
+
+### Diagnosis
+1. Add timestamps to all operations in the suspect area
+2. Introduce artificial delays (`setTimeout`, `sleep`) to amplify the race window
+3. Run under high concurrency: `autocannon -c 50 -d 10 http://localhost:3000/api/endpoint`
+4. Use thread/race sanitizers when available (`go run -race`, `tsc --strict`)
+5. Search for shared mutable state accessed without synchronization
+
+### Fix Patterns
+- **Mutex/Lock**: Serialize access to shared state. Use `async-mutex` for Node.js, `synchronized` for Java, `sync.Mutex` for Go.
+- **Atomic Operations**: For simple counters/flags, use atomic primitives instead of locks.
+- **Idempotent Operations**: Design operations so running them twice produces the same result (database upserts, unique constraints).
+- **Optimistic Concurrency**: Use version columns or ETags. Retry on conflict instead of locking.
+
+## Memory Leaks
+
+### Symptoms
+- Application memory grows steadily over hours/days
+- Garbage collection pauses become longer and more frequent
+- Eventually: OOM kills, process restarts, or swap thrashing
+- Performance degrades proportionally to uptime
+
+### Diagnosis
+1. Take heap snapshots at regular intervals (e.g., every 30 minutes)
+2. Compare snapshots: sort by "Delta" to find growing object types
+3. Check event listener counts: `require('events').EventEmitter.listenerCount(emitter, 'event')`
+4. Look for detached DOM nodes (browser) or orphaned references (server)
+5. Check for growing caches, maps, or arrays without eviction
+
+### Fix Patterns
+- **Event Listeners**: Always `removeEventListener` or use `{ once: true }`. In React, clean up in `useEffect` return.
+- **Closures**: Beware closures in long-lived callbacks that capture large scopes. Nullify references when done.
+- **Caches**: Always implement a max size or TTL eviction. Use `lru-cache` or `Map` with periodic cleanup.
+- **Timers**: Clear intervals/timeouts when the owner is destroyed. `clearInterval(id)` in cleanup.
+- **Streams**: Always handle `error` events on streams. Unpipe/destroy streams when no longer needed.
+
+## Deadlocks
+
+### Symptoms
+- Application hangs — no errors, no progress, no CPU usage
+- Database queries that never return
+- Threads/goroutines stuck in waiting state
+- Timeouts that all trigger simultaneously
+
+### Diagnosis
+```sql
+-- PostgreSQL: Find blocked queries
+SELECT pid, state, query, wait_event_type, wait_event
+FROM pg_stat_activity
+WHERE state = 'active' AND wait_event IS NOT NULL;
+
+-- PostgreSQL: Find lock dependencies
+SELECT blocked.pid AS blocked_pid, blocked.query AS blocked_query,
+       blocking.pid AS blocking_pid, blocking.query AS blocking_query
+FROM pg_stat_activity blocked
+JOIN pg_locks bl ON bl.pid = blocked.pid
+JOIN pg_locks kl ON kl.locktype = bl.locktype AND kl.relation = bl.relation AND kl.pid != bl.pid
+JOIN pg_stat_activity blocking ON blocking.pid = kl.pid
+WHERE NOT bl.granted;
+```
+
+### Fix Patterns
+- **Consistent Lock Ordering**: Always acquire locks in the same global order (e.g., alphabetically by table name).
+- **Lock Timeouts**: Set `SET lock_timeout = '5s'` to fail fast instead of hanging forever.
+- **Reduce Lock Scope**: Hold locks for the shortest time possible. Do computation outside the lock, only lock for the mutation.
+- **Advisory Locks**: Use application-level locks (`pg_advisory_lock`) for business-logic-level serialization.
+
+## N+1 Queries
+
+### Symptoms
+- Page load has dozens or hundreds of identical queries differing only by ID
+- Response time scales linearly with the number of records
+- Database shows high query count but each query is individually fast
+
+### Diagnosis
+1. Enable query logging and count queries per request
+2. Search for queries inside loops: `for (const item of items) { await db.query(...) }`
+3. Use ORM-level logging: Prisma (`DEBUG="prisma:query"`), Sequelize (`logging: console.log`)
+4. Monitor with `pg_stat_statements`: sort by `calls` column
+
+### Fix Patterns
+- **Eager Loading**: Include related data in the initial query. `User.findAll({ include: [Post] })` instead of loading posts separately.
+- **DataLoader**: Batch and deduplicate requests within a single tick. Ideal for GraphQL resolvers.
+- **JOIN**: Replace N+1 SELECT with a single JOIN or subquery.
+- **WHERE IN**: Collect IDs first, then fetch all at once: `WHERE id = ANY($1::int[])`
+
+## Infinite Loops / Re-renders
+
+### Symptoms
+- Browser tab freezes or shows "page unresponsive"
+- 100% CPU usage on one core
+- React DevTools shows thousands of renders per second
+- Console fills with repeated log messages
+
+### Diagnosis
+1. **Infinite Loop**: Add a counter inside the loop. If it exceeds a threshold, break and log the state.
+2. **React Re-renders**: Enable "Highlight updates" in React DevTools. Components flashing rapidly are the problem.
+3. **useEffect Dependency Loop**: An effect updates state that's in its own dependency array.
+4. **Redux**: Check for actions dispatching in a cycle (action A triggers reducer that dispatches action B that triggers action A).
+
+### Fix Patterns
+- **useEffect Dependencies**: Never include objects/arrays created during render in deps. Memoize with `useMemo` or extract to `useRef`.
+- **State Update Guards**: Add a condition before `setState`: `if (newValue !== currentValue)`.
+- **useMemo / useCallback**: Stabilize references passed as props or effect dependencies.
+- **Break Cycles**: If A triggers B triggers A, introduce a flag or refactor to a single combined state update.
+
+## Async/Await Pitfalls
+
+### Symptoms
+- `UnhandledPromiseRejection` warnings or crashes
+- Operations silently fail with no error logs
+- Data corruption from concurrent mutations
+- Stale state in closures (React, event handlers)
+
+### Diagnosis
+1. Search for `async` functions without `try/catch` or `.catch()`
+2. Search for `Promise.all` without error handling on individual items
+3. Check for `await` inside loops that should run concurrently
+4. Look for closures capturing variables that change between `await` points
+
+### Fix Patterns
+- **Always Handle Rejections**: Wrap `await` in `try/catch`. Use global handler: `process.on('unhandledRejection', handler)`.
+- **Concurrent Mutations**: Use transactions or optimistic locking when multiple async operations modify the same data.
+- **Stale Closures**: In React, use `useRef` for values that change between renders but are read in async callbacks.
+- **Sequential vs Parallel**: Use `Promise.all([a(), b()])` for independent operations, `await a(); await b()` only when b depends on a.
+
+## Timezone Bugs
+
+### Symptoms
+- Dates off by hours (often exactly N hours where N is UTC offset)
+- Bugs that appear only for users in certain timezones
+- Daylight saving transitions cause records to duplicate or disappear
+- Date comparisons fail near midnight
+
+### Diagnosis
+1. Log the raw date value, its timezone, and the formatted output at each transformation point
+2. Check database column type: `TIMESTAMP` (no timezone) vs `TIMESTAMPTZ` (with timezone)
+3. Test with dates near DST transitions (March, November in US; last Sunday of March/October in EU)
+4. Compare server timezone (`TZ` env var) with database timezone and client timezone
+
+### Fix Patterns
+- **Store UTC**: Always store dates in UTC. Convert to local timezone only at the display layer.
+- **Use TIMESTAMPTZ**: In PostgreSQL, always prefer `TIMESTAMPTZ` over `TIMESTAMP`.
+- **Explicit Timezones**: Never rely on system timezone. Pass timezone explicitly: `dayjs.tz(date, 'America/New_York')`.
+- **Test DST**: Include DST boundary dates in your test suite.
+
+## Encoding Issues
+
+### Symptoms
+- Characters display as `?`, `???`, or `\ufffd` (replacement character)
+- Emoji breaks string operations or database inserts
+- URL parameters with special characters cause 400 errors
+- File content looks correct in one editor but corrupted in another
+
+### Diagnosis
+1. Check the raw bytes: `hexdump -C file.txt | head` or inspect with a hex editor
+2. Verify Content-Type headers include charset: `Content-Type: application/json; charset=utf-8`
+3. Check database column collation and charset: `SHOW CREATE TABLE tablename`
+4. Test with known problematic inputs: emoji, CJK characters, RTL text, combining characters
+
+### Fix Patterns
+- **UTF-8 Everywhere**: Set UTF-8 at every layer: database, connection string, HTTP headers, HTML meta.
+- **BOM**: Remove BOM from files (`sed -i '1s/^\xEF\xBB\xBF//' file.txt`). Some parsers choke on it.
+- **URL Encoding**: Use `encodeURIComponent()` for query parameters, not `encodeURI()`.
+- **Database**: Use `utf8mb4` in MySQL (not `utf8` which only supports 3-byte sequences, breaking emoji).
+
+## Floating Point Precision
+
+### Symptoms
+- `0.1 + 0.2 !== 0.3` — equality checks on decimal results fail
+- Money calculations are off by fractions of a cent
+- Accumulating rounding errors over many iterations
+- Different results on different platforms for the same calculation
+
+### Diagnosis
+1. Log the full-precision value: `console.log(value.toPrecision(20))`
+2. Check for equality comparisons on floats (`===` instead of tolerance check)
+3. Look for money stored as float instead of integer cents
+4. Check for mixed integer/float arithmetic in accumulated calculations
+
+### Fix Patterns
+- **Integer Cents**: Store money as integer cents (or smallest currency unit). $19.99 = 1999. Do arithmetic on integers.
+- **Decimal Libraries**: Use `decimal.js`, `big.js`, or `Decimal` types in languages that support them.
+- **Epsilon Comparison**: `Math.abs(a - b) < Number.EPSILON` for float equality, or a domain-appropriate tolerance.
+- **Database NUMERIC**: Use `NUMERIC(10,2)` or `DECIMAL` types, never `FLOAT` or `DOUBLE` for money.

package/data/shared/framework/skills/frontend-development/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: frontend-development
+description: React/Vue/Svelte development — component design, state management, performance optimization, responsive design, debugging
+---
+
+# Frontend Development
+
+## Triggers
+
+Activate this skill when:
+- Building or refactoring UI components
+- Fixing frontend bugs (rendering, state, layout)
+- Optimizing frontend performance (bundle size, Core Web Vitals)
+- Implementing responsive or accessible design
+- Setting up state management (local, global, server state)
+- Integrating data fetching or caching layers
+- Working with SSR, RSC (React Server Components), or streaming patterns
+- Configuring routing (file-based or config-based), layouts, or navigation
+- Implementing real-time features (WebSocket, SSE, polling)
+- Building forms with validation (React Hook Form, VeeValidate)
+- Setting up tRPC or optimistic UI updates
+
+## Process
+
+### 1. Requirement Review
+- Clarify the UI spec: wireframe, Figma, or written description
+- Identify target browsers/devices and breakpoints
+- List data dependencies (API endpoints, real-time feeds)
+- Note accessibility requirements (WCAG level)
+
+### 2. Component Design
+- Break the UI into a component tree (container vs. presentational)
+- Define props, events, and slots/children for each component
+- Choose state strategy: local state, lifted state, context/store, or server state
+- Identify shared components that belong in a design system
+
+### 3. Implementation
+- Scaffold components with TypeScript types/interfaces
+- Implement data fetching with loading, error, and empty states
+- Apply styling approach (CSS Modules, Tailwind, styled-components)
+- Wire up routing and navigation
+- Add form validation (client-side + server-side error display)
+
+### 4. Testing
+- Unit test pure logic and utility functions
+- Component tests with Testing Library (render, interaction, assertion)
+- Visual regression tests for key layouts (Chromatic, Percy)
+- E2E smoke tests for critical user flows (Cypress, Playwright)
+
+### 5. Optimization
+- Audit bundle with `webpack-bundle-analyzer` or `source-map-explorer`
+- Apply code splitting at route and feature level
+- Optimize images (responsive `srcset`, WebP/AVIF, lazy loading)
+- Measure Core Web Vitals (LCP < 2.5s, FID < 100ms, CLS < 0.1)
+- Set up performance budgets in CI
+
+## References
+
+- [Component Patterns](references/component-patterns.md) — design principles, hooks, composition API, state strategies
+- [Performance Guide](references/performance-guide.md) — Core Web Vitals, bundle optimization, rendering, caching
+- [SSR & RSC Patterns](references/ssr-rsc-patterns.md) — Server Components, Server Actions, streaming, ISR, middleware
+- [Routing, Forms & Real-Time](references/routing-forms-realtime.md) — file-based routing, form validation, WebSocket/SSE, tRPC
+- [Troubleshooting](references/troubleshooting.md) — hydration errors, re-render storms, memory leaks, CORS, bundle bloat, performance regression
+
+## Assets
+
+- [Sample Output](assets/sample-output.md) — example component implementation plan