@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/ux-patterns.md

@@ -0,0 +1,158 @@
+# UX-Aware Bug Fix Patterns
+
+## Core Principle
+
+When fixing bugs, consider not just "technical correctness" but also "user experience".
+
+| Dimension | Question |
+|-----------|----------|
+| **Responsiveness** | Does UI remain smooth after fix? |
+| **Consistency** | Are frontend and backend states in sync? |
+| **Fault Tolerance** | How to degrade when network/DB fails? |
+| **Interruptibility** | Can user cancel long-running operations? |
+
+---
+
+## Pattern 1: Blocking → Async + Status Polling
+
+### Symptoms
+- UI freezes / becomes unresponsive
+- User cannot switch pages
+- Spinner never stops
+
+### Root Cause
+```
+User Action → Wait for Backend → Then Continue
+                  ↑
+            Blocking here
+```
+
+### Solution
+```
+User Action → Immediate UI Update → Background Task
+                                          ↓
+                              Frontend Polls Status
+                                          ↓
+                              Refresh on Complete
+```
+
+### Implementation
+
+**Backend: Task Manager**
+```python
+class BackgroundTaskManager:
+    def schedule(self, task_id, session_id, coro):
+        self._tasks[task_id] = Task(status="running")
+        asyncio.create_task(self._run(task_id, coro))
+    
+    def has_pending(self, session_id):
+        return any(t.status == "running" for t in self._tasks.values())
+```
+
+**Backend: Status API**
+```python
+@router.get("/sessions/{id}/save-status")
+def get_status(id):
+    return {"is_saving": task_manager.has_pending(id)}
+```
+
+**Frontend: Polling**
+```typescript
+const waitForComplete = async (sessionId, pollMs = 300) => {
+  while (await checkSaveStatus(sessionId)) {
+    await new Promise(r => setTimeout(r, pollMs));
+  }
+};
+```
+
+**Frontend: Loading Indicator**
+```tsx
+{isSaving && <div>Syncing messages...</div>}
+```
+
+---
+
+## Pattern 2: Connection Lost → Independent Connection
+
+### Symptoms
+- `no active connection` error
+- DB connection invalid in finally block
+- Async task uses closed connection
+
+### Root Cause
+After request completes, original DB connection may be closed, but background task still uses it.
+
+### Solution
+Background tasks use independent database connections.
+
+```python
+# ❌ Reuse caller's connection
+async def background_save(self):
+    await self.db.commit()  # Connection may be closed
+
+# ✅ Create new connection
+async def background_save():
+    async with async_session_maker() as new_db:
+        new_db.add(message)
+        await new_db.commit()
+```
+
+---
+
+## Pattern 3: State Loss → Local Cache + Sync
+
+### Symptoms
+- Data lost after user interrupts
+- Unsaved content disappears on navigation
+- State resets after page refresh
+
+### Solution
+```typescript
+// Immediately: Save to localStorage
+const handleInterrupt = () => {
+  localStorage.setItem('pending', JSON.stringify(messages));
+  stopGeneration();
+};
+
+// On return: Merge local and server data
+const loadSession = async (id) => {
+  const local = JSON.parse(localStorage.getItem('pending'));
+  const server = await fetchMessages(id);
+  
+  // Choose more complete version
+  if (local?.content.length > server?.content.length) {
+    return local;
+  }
+  return server;
+};
+```
+
+---
+
+## Pattern 4: Sequential → Parallel Execution
+
+### Symptoms
+- Slow page load
+- Multiple requests one after another
+
+### Solution
+```python
+# ❌ Sequential
+a = await fetch_a()
+b = await fetch_b()
+
+# ✅ Parallel
+a, b = await asyncio.gather(fetch_a(), fetch_b())
+```
+
+---
+
+## Checklist
+
+Before considering a fix complete, ask yourself:
+
+- [ ] Does UI remain smooth after fix?
+- [ ] Can long-running operations be cancelled?
+- [ ] How is network failure handled?
+- [ ] Are frontend and backend states consistent?
+- [ ] Will data be lost if user navigates away?

package/.claude/skills/bug-fixing/references/windows-terminal-hygiene.md

@@ -0,0 +1,106 @@
+# Windows Terminal Hygiene (Command Discipline)
+
+Terminal “hygiene” is about making reproductions and verification trustworthy. On Windows (CMD/PowerShell), small input mistakes (stray characters, chained commands, mixed shells) can make you think a fix worked when you actually ran something else.
+
+This guide is cross-project and applies to any repo with CLI workflows.
+
+## Defaults (best practices)
+
+- Prefer **one command per prompt** (especially during bug reproduction/verification).
+- Prefer **separate steps** for `cd` and execution.
+- Ensure a **clean prompt** before typing the next command (no leftover characters from interrupts/exits).
+- Avoid “clever” command chaining unless you explicitly annotate why it’s safe.
+
+## 1) One command per prompt (default)
+
+During investigation, clarity beats brevity.
+
+### Good (separate steps)
+
+```bat
+cd path\to\project
+python -m pytest -q tests\test_example.py
+```
+
+### Avoid by default (chained commands)
+
+```bat
+cd path\to\project && python -m pytest -q tests\test_example.py
+```
+
+Why avoid chaining by default:
+
+- It hides which step failed (directory change vs execution).
+- Copy/paste artifacts can silently corrupt the command.
+- Logs become harder to interpret and reproduce.
+
+## 2) Keep the prompt “clean”
+
+### After interrupts
+
+If you press **Ctrl+C** to stop a process:
+
+- Wait until the shell returns to a normal prompt.
+- Then type the next command from a clean line.
+
+### After interactive exits / stray keystrokes
+
+Many tools use single-key commands to exit/quit (e.g., `q`). If you type `q` and then immediately type a command without a clean prompt, you can accidentally run something like `qpython ...`.
+
+Default practice:
+
+- If you suspect a stray character is present, **press Enter** to flush the line and get a new prompt.
+- If you see the command line starts with an unexpected prefix (e.g., `qpython`), **stop** and retype.
+
+Useful line-clearing shortcuts (varies by shell):
+
+- CMD: `Esc` often clears the current line
+- PowerShell (PSReadLine): `Ctrl+U` clears the line (if PSReadLine is enabled)
+
+## 3) Avoid copy/paste artifacts
+
+When copying commands from notes/chat:
+
+- Check for leading characters (`>`, `$`, stray letters)
+- Check quotes (smart quotes vs ASCII quotes)
+- Prefer short commands; avoid multi-line unless necessary
+
+## 4) Use explicit interpreters/tools when ambiguity exists
+
+When multiple versions are installed, prefer explicit paths or the environment’s executable.
+
+Examples:
+
+- Print the active Python:
+  - `python -c "import sys; print(sys.executable)"`
+- Find which Python is being resolved:
+  - `where python`
+
+If you use a virtual environment, prefer calling its Python directly (no activation drift):
+
+```bat
+venv\Scripts\python -m pytest -q
+```
+
+## 5) Record commands and outcomes (verification-grade logs)
+
+For every verification step, capture:
+
+- Command (exact)
+- Working directory (if relevant)
+- Exit code
+- Key output lines
+
+This makes later debugging and code review substantially faster.
+
+## 6) Exceptions (when chaining is acceptable)
+
+Chaining can be fine in stable automation scripts (CI) where:
+
+- The environment is controlled
+- Logs are captured per step
+- Fail-fast semantics are desired
+
+Even then, prefer readability and explicitness in investigation mode.
+
+

package/.claude/skills/bug-fixing/references/zero-regression-matrix.md

@@ -0,0 +1,239 @@
+# Zero-Regression Verification Matrix
+
+> The definitive checklist to ensure bug fixes don't break existing functionality or introduce new bugs.
+
+## Why This Matrix Exists
+
+| Problem | Impact | This Matrix Prevents |
+|---------|--------|---------------------|
+| Fix breaks other feature | User loses functionality | Regression verification |
+| Fix introduces new bug | Two bugs instead of one | Systematic validation |
+| Fix only addresses symptom | Bug returns later | Root cause verification |
+| Fix scope creeps | Unnecessary changes | Minimal change enforcement |
+
+---
+
+## The Complete Matrix
+
+### Section A: Pre-Fix Baseline (BEFORE writing any fix code)
+
+| # | Check | How | Evidence Required | Pass? |
+|---|-------|-----|-------------------|-------|
+| A1 | Bug reproduced | Follow exact repro steps | Screenshot/video/log | ☐ |
+| A2 | Test baseline captured | Run full test suite | Test output saved | ☐ |
+| A3 | Affected files identified | Impact analysis Layer 0-2 | File list (<5 ideal) | ☐ |
+| A4 | Working features listed | Manual check near bug area | Feature checklist | ☐ |
+| A5 | Root cause identified | 5 Whys / Data Flow / Timeline | One-sentence statement | ☐ |
+
+**STOP if any A-check fails. You are not ready to fix.**
+
+---
+
+### Section B: Fix Quality (DURING fix implementation)
+
+| # | Check | Criteria | Pass? |
+|---|-------|----------|-------|
+| B1 | Minimal LOC | ≤ 20 lines changed (ideal), ≤ 50 lines (max) | ☐ |
+| B2 | Single concern | Only the bug fixed, no refactoring | ☐ |
+| B3 | No new dependencies | No new packages added | ☐ |
+| B4 | No API contract changes | Existing callers unchanged | ☐ |
+| B5 | Config over hardcode | Used solution hierarchy correctly | ☐ |
+| B6 | Old path preserved | For critical: feature flag exists | ☐ |
+
+**If B4 fails (API change needed), document and get explicit approval.**
+
+---
+
+### Section C: Correctness Verification (AFTER fix, BEFORE commit)
+
+| # | Check | How | Expected | Pass? |
+|---|-------|-----|----------|-------|
+| C1 | Bug fixed | Reproduce original steps | Bug no longer occurs | ☐ |
+| C2 | Root cause addressed | Code review against RCA | Fix targets root cause | ☐ |
+| C3 | Null case | Test with null/undefined input | Handled gracefully | ☐ |
+| C4 | Empty case | Test with empty string/array | Handled gracefully | ☐ |
+| C5 | Boundary case | Test min/max/edge values | Handled gracefully | ☐ |
+| C6 | Error case | Simulate network/DB failure | Fails gracefully | ☐ |
+
+---
+
+### Section D: Regression Verification (CRITICAL — FROM IMPACT ANALYSIS)
+
+| # | Check | How | Expected | Pass? |
+|---|-------|-----|----------|-------|
+| D1 | Layer 1 (Direct callers) | Test each function calling fixed code | All still work | ☐ |
+| D2 | Layer 2 (Indirect callers) | Test callers of Layer 1 | All still work | ☐ |
+| D3 | Layer 3 (Cross-module) | Verify other modules | No breakage | ☐ |
+| D4 | Layer 4 (API surface) | Test API endpoints | Responses unchanged | ☐ |
+| D5 | Layer 5 (Data flow) | Verify data integrity | No corruption | ☐ |
+| D6 | UI Features | Manual test listed features | All still work | ☐ |
+| D7 | Baseline comparison | Run full test suite again | Same or better than A2 | ☐ |
+
+**D7 is the final gate. If tests regress, fix is not ready.**
+
+---
+
+### Section E: Code Quality Verification
+
+| # | Check | Command | Expected | Pass? |
+|---|-------|---------|----------|-------|
+| E1 | Linter clean | `read_lints` on modified files | Zero new errors | ☐ |
+| E2 | Type check | Language-specific typecheck | Pass | ☐ |
+| E3 | Build succeeds | Full build command | Success | ☐ |
+| E4 | Unit tests | Run affected test files | All pass | ☐ |
+| E5 | Integration tests | Run integration suite | All pass | ☐ |
+| E6 | E2E tests (if applicable) | Run E2E suite | All pass | ☐ |
+
+---
+
+### Section F: Completeness Check
+
+| # | Check | How | Pass? |
+|---|-------|-----|-------|
+| F1 | Similar bugs searched | IDE content search or `rg -n` for the same pattern | All found fixed | ☐ |
+| F2 | Documentation updated | If behavior changed | Docs reflect change | ☐ |
+| F3 | Test for bug added | New test prevents recurrence | Test exists | ☐ |
+| F4 | Commit message clear | Includes bug ID and root cause | Message written | ☐ |
+
+---
+
+## Quick Verification Commands by Stack
+
+### Frontend (React/Vue/TypeScript)
+
+```bash
+# E1-E3: Code quality
+npm run lint
+npm run typecheck  # or: npx tsc --noEmit
+npm run build
+
+# E4-E6: Tests
+npm test -- --coverage
+npm run test:e2e
+```
+
+### Backend (Python)
+
+```bash
+# E1-E3: Code quality
+ruff check .
+mypy .
+pip install -e .  # or poetry install
+
+# E4-E6: Tests
+pytest --cov=src
+pytest tests/integration/
+```
+
+### Backend (Node.js)
+
+```bash
+# E1-E3: Code quality
+npm run lint
+npm run build
+
+# E4-E6: Tests
+npm test
+npm run test:integration
+```
+
+### Backend (Go)
+
+```bash
+# E1-E3: Code quality
+go vet ./...
+golangci-lint run
+go build ./...
+
+# E4-E6: Tests
+go test ./... -cover
+go test ./... -tags=integration
+```
+
+### Backend (Java)
+
+```bash
+# E1-E6: All in one
+./gradlew check test integrationTest
+# or
+mvn verify
+```
+
+---
+
+## Verification Report Template
+
+Copy and fill after completing the matrix:
+
+```markdown
+## Bug Fix Verification Report
+
+**Bug ID**: BUG-XXXX
+**Date**: YYYY-MM-DD
+**Fixed By**: [Name]
+
+### Summary
+- **Root Cause**: [One sentence]
+- **Fix Approach**: [One sentence]
+- **Files Changed**: [Count] files, [LOC] lines
+
+### Matrix Results
+
+| Section | Checks | Passed | Notes |
+|---------|--------|--------|-------|
+| A: Pre-Fix Baseline | 5 | 5/5 | |
+| B: Fix Quality | 6 | 6/6 | |
+| C: Correctness | 6 | 6/6 | |
+| D: Regression | 7 | 7/7 | |
+| E: Code Quality | 6 | 6/6 | |
+| F: Completeness | 4 | 4/4 | |
+| **TOTAL** | **34** | **34/34** | ✅ Ready to merge |
+
+### Evidence
+- [ ] Screenshot/log of bug fixed
+- [ ] Test baseline before: [link/output]
+- [ ] Test baseline after: [link/output]
+- [ ] Similar bugs found and fixed: [count]
+
+### Sign-off
+- [ ] All matrix checks pass
+- [ ] No new lint errors
+- [ ] Test suite green
+- [ ] Ready for review
+```
+
+---
+
+## When to Use Zero-Risk Protocol Instead
+
+Escalate to `references/zero-risk-protocol.md` if ANY of these apply:
+
+| Condition | Action |
+|-----------|--------|
+| Production incident | Zero-Risk Protocol |
+| Payment/Auth/User data affected | Zero-Risk Protocol |
+| Impact analysis reaches Layer 4-5 | Zero-Risk Protocol |
+| Team lead requests "zero-risk" | Zero-Risk Protocol |
+| >50 LOC change required | Zero-Risk Protocol |
+| API contract must change | Zero-Risk Protocol |
+
+---
+
+## Common Failures and How to Recover
+
+| Failure | Symptom | Recovery |
+|---------|---------|----------|
+| D7 fails (tests regress) | New test failures | Revert, investigate, re-fix |
+| B1 fails (too many LOC) | Change >50 lines | Split into smaller changes |
+| C1 fails (bug not fixed) | Bug still occurs | Review RCA, find actual root |
+| F1 fails (similar bugs) | Pattern found elsewhere | Fix all before declaring done |
+
+---
+
+## The Golden Rule
+
+> **If you cannot pass Section D (Regression), the fix is NOT ready.**
+>
+> No exceptions. No "it should be fine". No "I'll fix it later".
+>
+> A broken fix is worse than no fix.

package/.claude/skills/bug-fixing/references/zero-risk-protocol.md

@@ -0,0 +1,102 @@
+# Zero-Risk Bug Fixing Protocol
+
+> Mandatory protocol for critical, high-severity, or production-impacting bugs.
+
+Used whenever any of the following applies:
+- Production incident / customer-facing outage
+- Critical or High severity bug
+- Fix touches payment, auth, order, user data, finance, or any “no-downtime” system
+- Impact analysis reaches Layer 4 or Layer 5
+- Team lead / on-call explicitly requests “zero-risk”
+
+If in doubt → use this protocol.
+
+## Core Principle
+> “We would rather move slowly and safely than move fast and cause another incident.”
+
+## The 7 Non-Negotiable Steps
+
+### 1. Immediate Isolation & Safety Perimeter
+- Create a dedicated branch: `hotfix/bug-XXXX-zero-risk`
+- Open a temporary feature flag (even if it doesn’t exist yet):
+  ```ts
+  // Example (LaunchDarkly / Unleash / ConfigCat / self-hosted)
+  const USE_ZERO_RISK_FIX = flags['zero-risk-fix-bug-XXXX'] ?? false;
+  ```
+- Default = `false` (old code path remains active)
+
+### 2. Minimal Viable Surgical Fix
+Rules:
+- Change ≤ 15 lines whenever possible
+- Never refactor, rename, or upgrade dependencies in the same PR
+- Add defensive guards only around the exact failure point
+- Keep the old code path intact and reachable when flag is off
+
+```diff
+- return user; // buggy
++ if (!USE_ZERO_RISK_FIX) return user;           // old path preserved
++ if (!user) throw new NotFoundError('User not found');
++ return user;                                   // new safe path
+```
+
+### 3. 100% Automated Safety Net (must all pass before any human review)
+Run locally and in CI:
+- Bug reproduction test → must fail on main, pass with flag ON
+- Full unit test suite → unchanged
+- Integration/E2E tests covering the affected user journey
+- Load test (if performance-related)
+- Coverage on changed files = 100%
+
+### 4. Canary + Instant Rollback Plan
+Deployment order:
+1. Deploy to Staging → verify smoke tests
+2. Deploy to 0.5–1% of production traffic (or dogfood/internal tenants)
+3. Enable flag for canary traffic only
+4. Monitoring dashboard with these alerts ready:
+   - Error rate increase > 0.1%
+   - 5xx spike
+   - Latency p95 > 2× baseline
+   - Specific exception name count > 0
+
+Rollback actions (≤ 30 seconds):
+- Turn flag OFF globally → instant
+- Or emergency revert commit if flag cannot be toggled fast enough
+
+### 5. Real-Time Observation Window
+Minimum 15–30 minutes (longer for payment/auth paths) with:
+- Engineer watching error dashboard live
+- On-call notified and standing by
+- Slack/Teams war room open
+
+### 6. Gradual Rollout
+Only after canary is green:
+- 1% → 10% → 25% → 50% → 100% (each step waits 10–30 min)
+- Keep flag in code until full confidence (usually 24–48h)
+
+### 7. Post-Mortem & Hardening
+Mandatory within 24h:
+- Add the bug pattern to common-bugs.md
+- Add automated test that would have caught it
+- Add linter / pre-commit hook if pattern is repeatable
+- Remove or clean up the feature flag (or leave it permanently if useful)
+
+## Quick Checklist (copy-paste into PR description)
+
+```markdown
+### Zero-Risk Protocol Checklist
+- [ ] Dedicated hotfix branch created
+- [ ] Feature flag added, default OFF
+- [ ] Old code path preserved
+- [ ] Change ≤ 15 LOC
+- [ ] Bug reproduction test fails on main, passes with flag ON
+- [ ] Full test suite green
+- [ ] Coverage 100% on changed files
+- [ ] Canary rollout plan written
+- [ ] Rollback procedure ≤ 30 s
+- [ ] Monitoring alerts configured
+- [ ] War room ready
+- [ ] Post-mortem actions listed
+```
+
+## One-Liner for PR Title
+`fix(bug-XXXX): zero-risk fix behind feature flag (canary → gradual rollout)`