@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/testing-strategy.md

@@ -0,0 +1,350 @@
+# Testing Strategy for Bug Fixes
+
+> Comprehensive testing approach to verify bug fixes and prevent regressions.
+
+## Table of Contents
+
+- [Testing Philosophy](#testing-philosophy)
+- [Test Pyramid for Bug Fixes](#test-pyramid-for-bug-fixes)
+- [Mandatory Test Types](#mandatory-test-types)
+- [Test Writing Guidelines](#test-writing-guidelines)
+- [Coverage Requirements](#coverage-requirements)
+- [Test Templates](#test-templates)
+
+---
+
+## Testing Philosophy
+
+1. **Prove the bug existed** - Write a test that fails before the fix
+2. **Prove the fix works** - Same test passes after the fix
+3. **Prove nothing broke** - All existing tests still pass
+4. **Prevent recurrence** - Test stays in the codebase forever
+
+---
+
+## Test Pyramid for Bug Fixes
+
+```
+                    ┌─────────────────┐
+                    │     E2E         │  ← Critical path only
+                    │   (Playwright)  │
+                    └────────┬────────┘
+                             │
+               ┌─────────────┴─────────────┐
+               │      Integration          │  ← API contracts, DB
+               │   (Testcontainers/MSW)    │
+               └────────────┬──────────────┘
+                            │
+        ┌───────────────────┴───────────────────┐
+        │              Unit Tests               │  ← Most bug fix tests
+        │         (Jest/Vitest/Pytest)          │
+        └───────────────────────────────────────┘
+```
+
+**For bug fixes, prioritize:**
+1. **Unit test** that reproduces the exact bug condition
+2. **Integration test** if bug involves multiple components
+3. **E2E test** only if bug is user-journey critical
+
+---
+
+## Mandatory Test Types
+
+### 1. Bug Reproduction Test
+
+Must be written **before** the fix:
+
+```typescript
+// ❌ This test should FAIL on main branch
+describe('BUG-1234: User profile crashes on null avatar', () => {
+  it('should handle missing avatar gracefully', () => {
+    const user = { name: 'John', avatar: null };
+    
+    // This would crash before fix
+    expect(() => renderProfile(user)).not.toThrow();
+    expect(screen.getByText('John')).toBeInTheDocument();
+  });
+});
+```
+
+### 2. Fix Verification Test
+
+Same test **passes** after fix:
+
+```typescript
+// ✅ This test should PASS after fix
+it('should display default avatar when user.avatar is null', () => {
+  const user = { name: 'John', avatar: null };
+  renderProfile(user);
+  
+  expect(screen.getByAltText('Default avatar')).toBeInTheDocument();
+});
+```
+
+### 3. Edge Case Tests
+
+Cover related edge cases discovered during RCA:
+
+```typescript
+describe('Avatar edge cases', () => {
+  it.each([
+    [null, 'default.png'],
+    [undefined, 'default.png'],
+    ['', 'default.png'],
+    ['valid-url.jpg', 'valid-url.jpg'],
+  ])('avatar=%s should display %s', (avatar, expected) => {
+    const user = { name: 'John', avatar };
+    renderProfile(user);
+    
+    expect(screen.getByRole('img').src).toContain(expected);
+  });
+});
+```
+
+### 4. Regression Tests
+
+Verify existing functionality unchanged:
+
+```typescript
+describe('Profile regression tests', () => {
+  it('should still display user name correctly', () => { /* ... */ });
+  it('should still allow avatar upload', () => { /* ... */ });
+  it('should still link to settings', () => { /* ... */ });
+});
+```
+
+---
+
+## Test Writing Guidelines
+
+### Do's ✅
+
+```typescript
+// ✅ Descriptive test name includes bug ID
+it('BUG-1234: should not crash when avatar is null');
+
+// ✅ Test the exact failure condition
+const user = { avatar: null }; // Exact trigger
+
+// ✅ Assert specific behavior, not just "no error"
+expect(component).toHaveAttribute('src', 'default.png');
+
+// ✅ Use realistic data
+const user = userFactory.build({ avatar: null });
+```
+
+### Don'ts ❌
+
+```typescript
+// ❌ Vague test name
+it('should work correctly');
+
+// ❌ Testing implementation, not behavior
+expect(useState).toHaveBeenCalledWith(null);
+
+// ❌ Multiple bugs in one test
+it('should handle null avatar and empty name and missing email');
+
+// ❌ Skipping cleanup
+afterEach(() => cleanup()); // Don't forget!
+```
+
+---
+
+## Coverage Requirements
+
+| Fix Scope | Required Coverage |
+|-----------|-------------------|
+| Single function | 100% on changed lines |
+| Multiple functions | 100% on changed + 80% on callers |
+| Cross-module | 100% on changed + integration tests |
+| Critical path | All above + E2E test |
+
+### Coverage Commands
+
+```bash
+# JavaScript/TypeScript
+npx vitest run --coverage --reporter=html
+npx jest --coverage --collectCoverageFrom='src/**/*.{ts,tsx}'
+
+# Python
+pytest --cov=src --cov-report=html
+coverage run -m pytest
+coverage report --fail-under=80
+
+# Go
+go test -coverprofile=coverage.out ./...
+go tool cover -html=coverage.out
+```
+
+---
+
+## Test Templates
+
+### Unit Test Template (TypeScript)
+
+```typescript
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { render, screen, cleanup } from '@testing-library/react';
+
+describe('BUG-XXXX: [Brief description]', () => {
+  beforeEach(() => {
+    // Setup: mock dependencies, reset state
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.restoreAllMocks();
+  });
+
+  describe('Bug reproduction', () => {
+    it('should [expected behavior] when [trigger condition]', () => {
+      // Arrange: setup the exact bug trigger
+      const input = { /* bug trigger data */ };
+
+      // Act: execute the buggy code path
+      const result = functionUnderTest(input);
+
+      // Assert: verify correct behavior
+      expect(result).toBe(expected);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it.each([
+      ['case 1', input1, expected1],
+      ['case 2', input2, expected2],
+    ])('%s', (name, input, expected) => {
+      expect(functionUnderTest(input)).toBe(expected);
+    });
+  });
+
+  describe('Regression', () => {
+    it('should still [existing behavior]', () => {
+      // Verify existing functionality unchanged
+    });
+  });
+});
+```
+
+### Integration Test Template (Python)
+
+```python
+import pytest
+from unittest.mock import patch, MagicMock
+
+class TestBugXXXX:
+    """BUG-XXXX: [Brief description]"""
+
+    @pytest.fixture(autouse=True)
+    def setup(self, db_session):
+        """Setup test fixtures."""
+        self.session = db_session
+        # Create test data
+
+    def test_bug_reproduction(self):
+        """Should [expected] when [trigger]."""
+        # Arrange
+        user = User(avatar=None)  # Bug trigger
+        
+        # Act
+        result = get_user_profile(user.id)
+        
+        # Assert
+        assert result.avatar_url == "default.png"
+
+    @pytest.mark.parametrize("avatar,expected", [
+        (None, "default.png"),
+        ("", "default.png"),
+        ("valid.jpg", "valid.jpg"),
+    ])
+    def test_edge_cases(self, avatar, expected):
+        """Edge case: avatar={avatar}."""
+        user = User(avatar=avatar)
+        result = get_user_profile(user.id)
+        assert result.avatar_url == expected
+
+    def test_regression_existing_users(self):
+        """Existing users should still work."""
+        user = User(avatar="existing.jpg")
+        result = get_user_profile(user.id)
+        assert result.avatar_url == "existing.jpg"
+```
+
+### E2E Test Template (Playwright)
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test.describe('BUG-XXXX: [Brief description]', () => {
+  test.beforeEach(async ({ page }) => {
+    // Login, navigate to page
+    await page.goto('/profile');
+  });
+
+  test('should display default avatar for user without avatar', async ({ page }) => {
+    // Setup: Create user without avatar via API
+    await api.createUser({ name: 'Test', avatar: null });
+    
+    // Navigate
+    await page.goto('/profile/test-user');
+    
+    // Assert
+    await expect(page.getByAltText('User avatar')).toHaveAttribute(
+      'src',
+      /default\.png/
+    );
+  });
+
+  test('regression: should still display custom avatar', async ({ page }) => {
+    await api.createUser({ name: 'Test', avatar: 'custom.jpg' });
+    await page.goto('/profile/test-user');
+    
+    await expect(page.getByAltText('User avatar')).toHaveAttribute(
+      'src',
+      /custom\.jpg/
+    );
+  });
+});
+```
+
+---
+
+## Test Execution Checklist
+
+Before submitting the fix:
+
+```markdown
+### Test Verification Checklist
+
+- [ ] Bug reproduction test written and fails on main
+- [ ] Fix applied and reproduction test now passes
+- [ ] Edge case tests added (null, undefined, empty, boundary)
+- [ ] Regression tests for affected callers pass
+- [ ] Full test suite green (`npm test` / `pytest`)
+- [ ] Coverage on changed files = 100%
+- [ ] No flaky tests introduced (run 3x to verify)
+- [ ] Test naming follows convention: `BUG-XXXX: should...`
+```
+
+---
+
+## Quick Reference: Test Commands
+
+```bash
+# Run specific test file
+npx vitest run src/components/Profile.test.tsx
+pytest tests/test_profile.py -v
+
+# Run tests matching pattern
+npx vitest run -t "BUG-1234"
+pytest -k "bug_1234"
+
+# Watch mode during development
+npx vitest watch
+pytest-watch
+
+# Coverage report
+npx vitest run --coverage
+pytest --cov --cov-report=term-missing
+```

package/.claude/skills/bug-fixing/references/tooling-build-scripts.md

@@ -0,0 +1,162 @@
+# Tooling & Build Scripts — Bug Fixing Guide (Zero Regression)
+
+Use this guide when the “bug” lives in:
+- build scripts (`.bat`, `.sh`, Makefiles)
+- packaging tools (Electron Builder, PyInstaller, installers)
+- CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.)
+
+The failure mode here is common: the fix “seems right” but breaks a different branch (interactive vs non-interactive, admin vs non-admin, CI vs local), or the output is too quiet so it looks “stuck”.
+
+---
+
+## 1) Triage (fast classifier)
+
+Ask 1–2 questions:
+- **Entry point**:
+  - (A) double-click / GUI runner
+  - (B) interactive terminal
+  - (C) CI job / pipeline step
+- **Final outcome**:
+  - (A) fails with an error
+  - (B) “hangs” / no progress output
+  - (C) succeeds but produces wrong artifact (wrong folder / missing files)
+
+Then capture **evidence**:
+- exact command line (or “double-click”)
+- working directory
+- tool versions (node/npm/python/electron-builder/pyinstaller if relevant)
+- last ~30 lines of output + **exit code**
+
+---
+
+## 2) Baseline (BEFORE fixing)
+
+### 2.1 Make the script observable (no “it looks stuck”)
+
+If output is too quiet:
+- remove silent flags (`-q`, `--silent`) for install/build steps
+- enable progress (`pip --progress-bar on`, package manager progress, verbose flags)
+- print step boundaries and timestamps
+
+### 2.2 Make runs deterministic (reduce flakiness)
+
+- avoid interactive prompts; provide non-interactive flags where possible
+- pin versions for toolchains when feasible
+- isolate caches (or document how to clear them)
+
+### 2.3 Baseline matrix (minimum)
+
+Record these as a table: **command → expected → actual → exit code → evidence**.
+
+Typical minimal set:
+- `script --help` (prints options, exits 0)
+- `script --check-only` (validates env, exits 0/1 deterministically)
+- “fast path” / “skip” flags (should not run heavy steps)
+- “full path” once (the real end-to-end build)
+
+---
+
+## 3) Windows Batch (`.bat`) pitfall checklist (common root causes)
+
+### 3.1 Control flow inside parentheses
+
+Avoid `goto` inside parenthesized blocks, e.g.:
+
+```bat
+if exist "X" (
+  goto :Label  REM fragile
+)
+```
+
+Prefer a flag variable and jump once outside the block.
+
+### 3.2 Delayed expansion and `!`
+
+If using `setlocal enabledelayedexpansion`, any `!` in values can be expanded unexpectedly.
+Be explicit about when delayed expansion is required, and avoid printing unescaped `!`.
+
+### 3.3 Special characters and quoting
+
+Windows batch is sensitive to `&`, `|`, `<`, `>`, `(`, `)`, `^`, `%`.
+Always quote paths with spaces and escape special characters when echoing commands.
+
+### 3.4 Encoding / non-ASCII
+
+Non-ASCII output can break in surprising ways depending on:
+- file encoding (UTF-8 with/without BOM)
+- code page (`chcp`)
+- console host
+
+Recommendation for robustness:
+- keep control keywords and critical command lines ASCII-only
+- if localized output is required, test on the real target console host
+
+### 3.5 “Double-click closes instantly”
+
+If users double-click the script, the window closes on completion or error.
+Options:
+- add a final `pause` (or a `--no-pause` flag)
+- instruct users to run from an existing terminal so output remains visible
+
+---
+
+## 4) Packaging toolchain pitfalls (general)
+
+### 4.1 Code signing on Windows
+
+If you do not have a code-signing certificate, **disable signing**.
+Otherwise tools may download signing helpers and fail due to permissions/symlink extraction, especially on locked-down machines.
+
+### 4.2 Symlink permissions (Windows)
+
+Creating symlinks often requires:
+- Administrator privileges, or
+- enabling Developer Mode
+
+If a tool tries to extract archives containing symlinks, prefer a no-symlink path or disable the feature that requires it.
+
+### 4.3 Caches
+
+Build tools cache downloads aggressively. When you see repeated failures with “cannot execute”, “corrupt archive”, “permission denied”, try clearing the tool’s cache directory and retry once.
+
+---
+
+## 5) Verification gate (tooling-specific)
+
+Don’t declare “fixed” until ALL pass:
+
+### 5.1 Correctness
+- original failing command now succeeds (or fails with the intended error message)
+- expected artifacts are produced in the expected location
+
+### 5.2 Regression
+- other entry points still work (double-click vs terminal vs CI)
+- “fast path” flags still skip heavy work
+
+### 5.3 Observability
+- progress is visible for long steps (no false “hang” reports)
+- error messages are actionable (tell user what to install/enable)
+
+### 5.4 Evidence (mandatory)
+
+Provide:
+- the exact commands used
+- exit codes
+- the relevant log tail for each command
+
+---
+
+## 6) Output template (copy/paste)
+
+```markdown
+## Tooling Verification Matrix
+
+| Case | Command / Entry point | Expected | Actual | Exit code | Evidence |
+|------|------------------------|----------|--------|----------:|----------|
+| 1 | `script --help` | prints help | | | |
+| 2 | `script --check-only` | env validated | | | |
+| 3 | fast path | skips heavy steps | | | |
+| 4 | full path | artifact produced | | | |
+```
+
+

package/.claude/skills/bug-fixing/references/user-input-validation.md

@@ -0,0 +1,77 @@
+# User Input & External Data Validation
+
+When bugs involve user input or external data (file imports, API responses, form data), incorrect assumptions about data format are the #1 cause of multi-fix loops.
+
+## Common Input Format Traps
+
+| Category | Trap | Reality | Prevention |
+|----------|------|---------|------------|
+| **Column/Field Names** | Names are plain identifiers | Users may use wrapper syntax, templates, or special chars | Normalize names at parse time; strip common wrappers |
+| **Data Types** | All values are strings | May be numbers, dates, booleans, nulls | Explicit type conversion with fallbacks |
+| **Empty Values** | Empty means empty string | Could be null, undefined, missing key, or whitespace-only | Define and handle all empty variants |
+| **Encoding** | File is UTF-8 | Could be UTF-8 BOM, UTF-16, ISO-8859-1 | Detect encoding or specify in docs |
+| **Line Endings** | LF only | Windows CRLF, old Mac CR | Normalize line endings at parse |
+| **Response Body** | HTTP success = business success | 200 with `{"code": -1, "error": "..."}` | Parse response body; check business status fields |
+
+## File Import Checklist
+
+### Parse Phase
+
+- [ ] **Column name normalization**: Strip wrapper syntax (e.g., `${name}` → `name`)
+- [ ] **Type detection**: Number, date, boolean, string
+- [ ] **Null handling**: Define what empty/missing values become
+- [ ] **Encoding handling**: BOM, charset detection
+
+### Validation Phase
+
+- [ ] **Required fields**: Check presence and non-empty
+- [ ] **Format validation**: Regex/pattern for constrained fields
+- [ ] **Range validation**: Min/max for numbers, length for strings
+
+### Integration Phase
+
+- [ ] **Data stored correctly**: Compare input → storage → retrieval
+- [ ] **Display matches input**: Compare original input → final render
+- [ ] **Edge cases work**: Special chars, very long values, unicode
+
+## API Response Validation
+
+### Common Response Patterns
+
+```
+Pattern A: { "code": 0, "message": "ok", "data": {...} }
+Pattern B: { "success": true, "result": {...} }
+Pattern C: { "status": "success", "payload": {...} }
+Pattern D: { "error": null, "data": {...} }
+```
+
+### Response Validation Checklist
+
+- [ ] **Identify response structure**: What fields indicate success/failure?
+- [ ] **Define success condition**: Not just HTTP 2xx, but also body fields
+- [ ] **Extract error info**: message/msg/error field for user display
+- [ ] **Handle edge cases**: Non-JSON response, empty body, timeout
+
+## Assumption Verification Template
+
+When fixing a bug involving external data, fill this table BEFORE coding:
+
+| Assumption | How to Verify | Evidence | Status |
+|------------|---------------|----------|--------|
+| Input format is X | Check actual sample data | | ⬜ |
+| Parser handles format Y | Read parser code | | ⬜ |
+| Data is normalized before use | Trace data flow | | ⬜ |
+| Edge case Z is handled | Test with edge case input | | ⬜ |
+| Response structure is A | Check API implementation | | ⬜ |
+
+## Red Flags (Trigger Deeper Investigation)
+
+If any of these appear, explicitly verify input handling:
+
+- Bug report mentions "sometimes works, sometimes doesn't"
+- Bug involves file upload/import functionality
+- Bug involves third-party API integration
+- User says "I followed the format exactly"
+- Error occurs only for certain users/inputs
+- Data looks correct in DB but wrong on display
+