@tinkcarlos/skillora 0.2.0

package/.claude/skills/bug-fixing/references/knowledge-workflow.md

@@ -0,0 +1,212 @@
+# Knowledge Workflow for Bug Fixing
+
+This document describes the knowledge accumulation and utilization workflow for bug fixing.
+
+---
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│                      Knowledge Architecture                          │
+├─────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌──────────────────────┐      ┌──────────────────────┐             │
+│  │   PROJECT LEVEL      │      │     SKILL LEVEL      │             │
+│  │   (Project-specific) │      │  (Cross-project)     │             │
+│  ├──────────────────────┤      ├──────────────────────┤             │
+│  │                      │      │                      │             │
+│  │  bugRecord.md        │ ──►  │  bug-guide.md        │             │
+│  │  ────────────────    │      │  ────────────────    │             │
+│  │  • Specific bugs     │      │  • Pattern library   │             │
+│  │  • Exact symptoms    │      │  • Detection methods │             │
+│  │  • Actual fixes      │      │  • Fix strategies    │             │
+│  │  • Real file paths   │      │  • Verification tips │             │
+│  │                      │      │                      │             │
+│  └──────────────────────┘      └──────────────────────┘             │
+│         ▲                              │                            │
+│         │                              │                            │
+│         │  Record                      │  Reference                 │
+│         │                              ▼                            │
+│  ┌──────────────────────────────────────────────────────────────┐  │
+│  │                     BUG FIXING PROCESS                        │  │
+│  └──────────────────────────────────────────────────────────────┘  │
+│                                                                      │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Phase 0.7: Knowledge Check (Before Investigation)
+
+**Purpose**: Avoid repeating past mistakes and leverage existing knowledge.
+
+### Step 1: Check Project History
+
+```markdown
+1. Look for bugRecord.md in project root
+2. If exists, search for related keywords:
+   - Error messages from current bug
+   - Affected component/module names
+   - Similar symptom descriptions
+3. Note any relevant past bugs and their solutions
+```
+
+### Step 2: Review Universal Patterns
+
+```markdown
+1. Read references/bug-guide.md
+2. Match current symptom to known patterns
+3. Apply recommended detection and fix strategies
+```
+
+### Step 3: Document Known History
+
+In your triage summary, add:
+
+```markdown
+## Knowledge Check
+- Project bugRecord.md: [Found/Not found]
+- Related past bugs: [BUG-XXX, BUG-YYY] or [None]
+- Applicable patterns from bug-guide.md: [Pattern names] or [None identified]
+- Lessons to apply: [List any relevant lessons]
+```
+
+---
+
+## Phase 6: Knowledge Update (After Verification)
+
+**Purpose**: Record the fix for future reference and pattern extraction.
+
+### Step 1: Add Record to Project bugRecord.md
+
+If bugRecord.md doesn't exist, create it using the template from `references/bug-record-template.md`.
+
+Add a new entry with:
+- Bug ID (sequential)
+- Date
+- Symptom, Root Cause, Solution, Verification
+- Pattern notes
+
+### Step 2: Handle Failed Fix Retry
+
+If a previous fix attempt was wrong:
+
+```markdown
+1. Find the previous record in bugRecord.md
+2. Update status to "Superseded by BUG-XXX"
+3. Add new record with correct fix
+4. Note what was wrong with the previous attempt
+```
+
+### Step 3: Extract Patterns (Periodic)
+
+After every 5-10 bug records:
+
+```markdown
+1. Review recent bugs for common themes
+2. Abstract project-specific details to universal patterns
+3. Update references/bug-guide.md with new patterns
+4. Use the "Pattern Extraction Guide" in bug-guide.md
+```
+
+---
+
+## Record Format Reference
+
+### Minimal Record (Quick Bugs)
+
+```markdown
+## [BUG-NNN] Title
+
+**Date**: YYYY-MM-DD | **Severity**: P2 | **Category**: [Category]
+
+**Symptom**: [One sentence]
+**Root Cause**: [One sentence]
+**Solution**: [One sentence]
+**Verified**: [Yes/No]
+```
+
+### Full Record (Complex Bugs)
+
+Use the complete template from `references/bug-record-template.md`.
+
+---
+
+## Pattern Abstraction Rules
+
+When extracting patterns for bug-guide.md, follow these rules:
+
+### What to Remove (Project-Specific)
+
+- Actual file paths (`/src/components/UserForm.tsx`)
+- Specific variable/function names (`handleUserSubmit`)
+- Exact error messages (`TypeError: Cannot read property 'id'`)
+- Specific data values (`userId: 12345`)
+- Framework versions (`React 18.2.0`)
+
+### What to Keep (Universal)
+
+- Problem category (input handling, state management)
+- Symptom type (crash, wrong display, no response)
+- Root cause pattern (missing validation, stale closure)
+- Fix strategy (add normalization, refresh state)
+- Detection method (check parser, trace data flow)
+
+### Abstraction Examples
+
+| Project-Specific | Universal |
+|------------------|-----------|
+| "useState doesn't update in onClick callback" | "Stale closure captures old state in event handler" |
+| "Excel parser uses ${keywords} as column name" | "User input contains wrapper syntax that should be stripped" |
+| "POST /api/users returns 200 but code: -1" | "HTTP success but business error in response body" |
+
+---
+
+## Integration with Output Contract
+
+Add to your bug fix report:
+
+```markdown
+## Knowledge Update
+
+### Project Record
+- Added to: bugRecord.md
+- Bug ID: BUG-NNN
+- Category: [Category]
+
+### Pattern Extraction
+- New pattern identified: [Yes/No]
+- Pattern name: [If yes]
+- Added to bug-guide.md: [Yes/No]
+
+### Related Bugs
+- Similar past bugs: [List or None]
+- Applied lessons from: [List or None]
+```
+
+---
+
+## Workflow Checklist
+
+### Before Starting Fix
+
+- [ ] Checked project bugRecord.md for related history
+- [ ] Reviewed bug-guide.md for applicable patterns
+- [ ] Noted any lessons to apply
+
+### After Completing Fix
+
+- [ ] Added record to project bugRecord.md
+- [ ] If retry, updated previous record status
+- [ ] Considered if pattern should be extracted
+- [ ] Updated bug-guide.md if new pattern found
+
+### Periodic Maintenance (Every 5-10 Bugs)
+
+- [ ] Reviewed recent bug records
+- [ ] Identified recurring themes
+- [ ] Abstracted to universal patterns
+- [ ] Updated bug-guide.md pattern library
+- [ ] Updated verification checklist if needed
+

package/.claude/skills/bug-fixing/references/post-edit-quality-gate.md

@@ -0,0 +1,30 @@
+# Post-Edit Quality Gate
+
+Every code modification must pass format + lint check before proceeding.
+
+## Workflow
+
+```
+Code Change → Format → Lint Check → Fix P0/P1 → Proceed
+```
+
+## Scripts
+
+| Script | Command |
+|--------|---------|
+| Format | `python scripts/format_code.py <file>` |
+| Format (dir) | `python scripts/format_code.py --dir src/` |
+| Lint | `python scripts/lint_check.py <file>` |
+| Lint + Fix | `python scripts/lint_check.py <file> --fix` |
+| IDE Lints | `read_lints(paths: ["<file>"])` |
+
+## Priority
+
+| Level | Examples | Action |
+|-------|----------|--------|
+| 🔴 P0 | Syntax errors | Must fix immediately |
+| 🟠 P1 | Type/import errors | Must fix before commit |
+| 🟡 P2 | Unused vars, warnings | Should fix |
+| ⚪ P3 | Style nits | Optional |
+
+**Rule**: Zero P0/P1 before proceeding.

package/.claude/skills/bug-fixing/references/python-env-and-testing.md

@@ -0,0 +1,126 @@
+# Python Environment & Testing Discipline
+
+Bug fixes are only “done” if the verification signal is trustworthy. In Python, the most common source of false confidence is running tests/scripts under the **wrong interpreter** or **outside the intended environment**.
+
+This guide is cross-project and applies to any Python backend, tooling repo, or hybrid monorepo.
+
+## Core principles (default best practices)
+
+- **Always know which Python you are using** (version + executable path).
+- **Prefer environment-managed execution** (venv/poetry/uv/conda) over global Python.
+- **Avoid command chaining by default** when reproducing/verifying (one command per run, capture outputs clearly).
+- **Record a repro matrix**: commands, environment, and outcomes.
+
+## Preflight checklist (before running tests)
+
+### 1) Identify the project’s intended environment tool
+
+Look for one of these and follow that tool’s “golden path”:
+
+- `pyproject.toml` (often Poetry/uv/pip-tools)
+- `requirements.txt` / `requirements-dev.txt`
+- `Pipfile` / `Pipfile.lock`
+- `environment.yml` (conda)
+
+If the project already uses a tool (e.g., Poetry), do not mix it with ad-hoc `pip install` unless you must.
+
+### 2) Confirm the active interpreter
+
+Run a small self-check and **paste the output** into your verification notes:
+
+```bash
+python -c "import sys,platform; print(sys.version); print(sys.executable); print(platform.platform())"
+```
+
+Common OS-specific helpers:
+
+- Windows (CMD/PowerShell):
+  - `where python`
+- macOS/Linux:
+  - `which python`
+
+If there are multiple Pythons, make sure the intended one is first in PATH *or* call the target interpreter explicitly.
+
+### 3) Confirm dependency context (pip points to the same interpreter)
+
+Run:
+
+```bash
+python -m pip --version
+```
+
+The printed path should match the interpreter you intend to use (same environment directory).
+
+## Virtual environment workflows
+
+### Option A (recommended): Call the environment’s Python directly
+
+This avoids “activation drift” and works well in automation.
+
+- Windows venv:
+  - `venv\Scripts\python -m pytest ...`
+- macOS/Linux venv:
+  - `venv/bin/python -m pytest ...`
+
+### Option B: Activate venv (interactive work)
+
+Activation commands vary by shell:
+
+- Windows CMD:
+  - `venv\Scripts\activate`
+- Windows PowerShell:
+  - `venv\Scripts\Activate.ps1`
+  - If blocked, you may need to adjust execution policy for the current session.
+- macOS/Linux:
+  - `source venv/bin/activate`
+
+After activation, confirm:
+
+```bash
+python -c "import sys; print(sys.executable)"
+```
+
+## Running tests (repeatable and debuggable)
+
+### Prefer module execution
+
+Use `python -m ...` to ensure you are using the correct environment:
+
+- `python -m pytest -q`
+- `python -m unittest`
+- `python -m <your_module>`
+
+### Run one command per step (default)
+
+To make logs and failures unambiguous:
+
+1. `cd` into the correct directory
+2. Run exactly one command
+3. Capture exit code + key output
+
+Avoid chained commands by default (e.g., `&&`, `;`, `|`) unless there is a clear reason and you annotate it.
+
+### Minimal verification matrix template
+
+Record the following for every bug fix:
+
+| Step | Command | Expected | Actual | Exit code | Notes |
+|---|---|---|---|---|---|
+| Preflight | (print sys.executable) | points to venv | … | 0 | … |
+| Target test | (pytest file) | pass | … | … | … |
+| Regression | (smoke test) | pass | … | … | … |
+
+## Common pitfalls & quick diagnoses
+
+- **Tests import the wrong dependency version**
+  - Verify `python -m pip --version` matches the active interpreter.
+- **pytest missing inside venv**
+  - Install test deps into the same environment, not globally.
+- **Multiple Python installs cause non-determinism**
+  - Call the target interpreter explicitly (Option A) and avoid relying on PATH.
+- **Interactive shell is “dirty” (stray characters, partial commands)**
+  - Use a clean prompt; see `windows-terminal-hygiene.md`.
+- **Tests hang**
+  - Reduce scope (single test), disable network, add timeouts, and verify background services are not required.
+
+