ai-qakit 1.0.0

package/templates/.claude/skills/debugging/references/systematic-debugging.md

@@ -0,0 +1,102 @@
+# Systematic Debugging
+
+Four-phase debugging framework that ensures root cause investigation before attempting fixes.
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If haven't completed Phase 1, cannot propose fixes.
+
+## The Four Phases
+
+Must complete each phase before proceeding to next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully** - Don't skip past errors/warnings, read stack traces completely
+2. **Reproduce Consistently** - Can trigger reliably? Exact steps? If not reproducible → gather more data
+3. **Check Recent Changes** - What changed? Git diff, recent commits, new dependencies, config changes
+4. **Gather Evidence in Multi-Component Systems**
+   - For EACH component boundary: log data entering/exiting, verify environment propagation
+   - Run once to gather evidence showing WHERE it breaks
+   - THEN analyze to identify failing component
+5. **Trace Data Flow** - Where does bad value originate? Trace up call stack until finding source (see root-cause-tracing.md)
+
+### Phase 2: Pattern Analysis
+
+**Find pattern before fixing:**
+
+1. **Find Working Examples** - Locate similar working code in same codebase
+2. **Compare Against References** - Read reference implementation COMPLETELY, understand fully before applying
+3. **Identify Differences** - List every difference however small, don't assume "that can't matter"
+4. **Understand Dependencies** - What other components, settings, config, environment needed?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis** - "I think X is root cause because Y", be specific not vague
+2. **Test Minimally** - SMALLEST possible change to test hypothesis, one variable at a time
+3. **Verify Before Continuing** - Worked? → Phase 4. Didn't work? → NEW hypothesis. DON'T add more fixes
+4. **When Don't Know** - Say "I don't understand X", don't pretend, ask for help
+
+### Phase 4: Implementation
+
+**Fix root cause, not symptom:**
+
+1. **Create Failing Test Case** - Simplest reproduction, automated if possible, MUST have before fixing
+2. **Implement Single Fix** - Address root cause identified, ONE change, no "while I'm here" improvements
+3. **Verify Fix** - Test passes? No other tests broken? Issue actually resolved?
+4. **If Fix Doesn't Work**
+   - STOP. Count: How many fixes tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question architecture**
+5. **If 3+ Fixes Failed: Question Architecture**
+   - Pattern: Each fix reveals new shared state/coupling problem elsewhere
+   - STOP and question fundamentals: Is pattern sound? Wrong architecture?
+   - Discuss with human partner before more fixes
+
+## Red Flags - STOP and Follow Process
+
+If catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "One more fix attempt" (when already tried 2+)
+
+**ALL mean:** STOP. Return to Phase 1.
+
+## Human Partner Signals You're Doing It Wrong
+
+- "Is that not happening?" - Assumed without verifying
+- "Will it show us...?" - Should have added evidence gathering
+- "Stop guessing" - Proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Approach isn't working
+
+**When see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too |
+| "Emergency, no time for process" | Systematic is FASTER than guess-and-check |
+| "Just try this first, then investigate" | First fix sets pattern. Do right from start |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem |
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common

package/templates/.claude/skills/debugging/references/verification.md

@@ -0,0 +1,123 @@
+# Verification Before Completion
+
+Run verification commands and confirm output before claiming success.
+
+## Core Principle
+
+**Evidence before claims, always.**
+
+Claiming work complete without verification is dishonesty, not efficiency.
+
+## The Iron Law
+
+```
+NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE
+```
+
+If haven't run verification command in this message, cannot claim it passes.
+
+## The Gate Function
+
+```
+BEFORE claiming any status or expressing satisfaction:
+
+1. IDENTIFY: What command proves this claim?
+2. RUN: Execute FULL command (fresh, complete)
+3. READ: Full output, check exit code, count failures
+4. VERIFY: Does output confirm claim?
+   - If NO: State actual status with evidence
+   - If YES: State claim WITH evidence
+5. ONLY THEN: Make claim
+
+Skip any step = lying, not verifying
+```
+
+## Common Failures
+
+| Claim | Requires | Not Sufficient |
+|-------|----------|----------------|
+| Tests pass | Test command output: 0 failures | Previous run, "should pass" |
+| Linter clean | Linter output: 0 errors | Partial check, extrapolation |
+| Build succeeds | Build command: exit 0 | Linter passing, logs look good |
+| Bug fixed | Test original symptom: passes | Code changed, assumed fixed |
+| Regression test works | Red-green cycle verified | Test passes once |
+| Agent completed | VCS diff shows changes | Agent reports "success" |
+| Requirements met | Line-by-line checklist | Tests passing |
+
+## Red Flags - STOP
+
+- Using "should", "probably", "seems to"
+- Expressing satisfaction before verification ("Great!", "Perfect!", "Done!")
+- About to commit/push/PR without verification
+- Trusting agent success reports
+- Relying on partial verification
+- Thinking "just this once"
+- Tired and wanting work over
+- **ANY wording implying success without having run verification**
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "Should work now" | RUN verification |
+| "I'm confident" | Confidence ≠ evidence |
+| "Just this once" | No exceptions |
+| "Linter passed" | Linter ≠ compiler |
+| "Agent said success" | Verify independently |
+| "Partial check is enough" | Partial proves nothing |
+
+## Key Patterns
+
+**Tests:**
+```
+✅ [Run test command] [See: 34/34 pass] "All tests pass"
+❌ "Should pass now" / "Looks correct"
+```
+
+**Regression tests (TDD Red-Green):**
+```
+✅ Write → Run (pass) → Revert fix → Run (MUST FAIL) → Restore → Run (pass)
+❌ "I've written regression test" (without red-green verification)
+```
+
+**Build:**
+```
+✅ [Run build] [See: exit 0] "Build passes"
+❌ "Linter passed" (linter doesn't check compilation)
+```
+
+**Requirements:**
+```
+✅ Re-read plan → Create checklist → Verify each → Report gaps or completion
+❌ "Tests pass, phase complete"
+```
+
+**Agent delegation:**
+```
+✅ Agent reports success → Check VCS diff → Verify changes → Report actual state
+❌ Trust agent report
+```
+
+## When To Apply
+
+**ALWAYS before:**
+- ANY variation of success/completion claims
+- ANY expression of satisfaction
+- ANY positive statement about work state
+- Committing, PR creation, task completion
+- Moving to next task
+- Delegating to agents
+
+**Rule applies to:**
+- Exact phrases
+- Paraphrases and synonyms
+- Implications of success
+- ANY communication suggesting completion/correctness
+
+## The Bottom Line
+
+**No shortcuts for verification.**
+
+Run command. Read output. THEN claim result.
+
+Non-negotiable.

package/templates/.claude/skills/debugging/scripts/find-polluter.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+# Bisection script to find which test creates unwanted files/state
+# Usage: ./find-polluter.sh <file_or_dir_to_check> <test_pattern>
+# Example: ./find-polluter.sh '.git' 'src/**/*.test.ts'
+
+set -e
+
+if [ $# -ne 2 ]; then
+  echo "Usage: $0 <file_to_check> <test_pattern>"
+  echo "Example: $0 '.git' 'src/**/*.test.ts'"
+  exit 1
+fi
+
+POLLUTION_CHECK="$1"
+TEST_PATTERN="$2"
+
+echo "🔍 Searching for test that creates: $POLLUTION_CHECK"
+echo "Test pattern: $TEST_PATTERN"
+echo ""
+
+# Get list of test files
+TEST_FILES=$(find . -path "$TEST_PATTERN" | sort)
+TOTAL=$(echo "$TEST_FILES" | wc -l | tr -d ' ')
+
+echo "Found $TOTAL test files"
+echo ""
+
+COUNT=0
+for TEST_FILE in $TEST_FILES; do
+  COUNT=$((COUNT + 1))
+
+  # Skip if pollution already exists
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo "⚠️  Pollution already exists before test $COUNT/$TOTAL"
+    echo "   Skipping: $TEST_FILE"
+    continue
+  fi
+
+  echo "[$COUNT/$TOTAL] Testing: $TEST_FILE"
+
+  # Run the test
+  npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+  # Check if pollution appeared
+  if [ -e "$POLLUTION_CHECK" ]; then
+    echo ""
+    echo "🎯 FOUND POLLUTER!"
+    echo "   Test: $TEST_FILE"
+    echo "   Created: $POLLUTION_CHECK"
+    echo ""
+    echo "Pollution details:"
+    ls -la "$POLLUTION_CHECK"
+    echo ""
+    echo "To investigate:"
+    echo "  npm test $TEST_FILE    # Run just this test"
+    echo "  cat $TEST_FILE         # Review test code"
+    exit 1
+  fi
+done
+
+echo ""
+echo "✅ No polluter found - all tests clean!"
+exit 0

package/templates/.claude/skills/debugging/scripts/find-polluter.test.md

@@ -0,0 +1,102 @@
+# find-polluter.sh Test Documentation
+
+## Purpose
+Bisection script to find which test creates unwanted files or state pollution.
+
+## Manual Test Procedure
+
+### Setup Test Scenario
+```bash
+# Create test directory
+mkdir -p /tmp/polluter-test && cd /tmp/polluter-test
+
+# Create clean test
+cat > test1.test.js << 'EOF'
+console.log('Test 1: clean');
+EOF
+
+# Create polluter test
+cat > test2.test.js << 'EOF'
+const fs = require('fs');
+fs.mkdirSync('.git', { recursive: true });
+console.log('Test 2: creates pollution');
+EOF
+
+# Create another clean test
+cat > test3.test.js << 'EOF'
+console.log('Test 3: clean');
+EOF
+```
+
+### Run Script
+```bash
+# For projects with npm test
+/path/to/find-polluter.sh '.git' 'src/**/*.test.ts'
+
+# For node-only tests (modify script to use 'node' instead of 'npm test')
+./find-polluter.sh '.git' '*.test.js'
+```
+
+### Expected Output
+```
+🔍 Searching for test that creates: .git
+Test pattern: *.test.js
+
+Found 3 test files
+
+[1/3] Testing: ./test1.test.js
+[2/3] Testing: ./test2.test.js
+
+🎯 FOUND POLLUTER!
+   Test: ./test2.test.js
+   Created: .git
+```
+
+### Cleanup
+```bash
+rm -rf /tmp/polluter-test
+```
+
+## Test Results
+
+✅ Script logic verified (2025-11-11)
+- Correctly iterates through test files
+- Detects pollution creation
+- Reports the polluting test file
+- Exits early when polluter found
+
+## Usage Notes
+
+**Prerequisites:**
+- Test runner (npm test) must be configured in project
+- Test pattern must match actual test files
+- Pollution path must be accurate
+
+**Customization:**
+If your project doesn't use `npm test`, modify line 42:
+```bash
+# Replace
+npm test "$TEST_FILE" > /dev/null 2>&1 || true
+
+# With your test command
+node "$TEST_FILE" > /dev/null 2>&1 || true
+# Or
+jest "$TEST_FILE" > /dev/null 2>&1 || true
+```
+
+## Common Use Cases
+
+1. **Find test creating .git directory:**
+   ```bash
+   ./find-polluter.sh '.git' 'src/**/*.test.ts'
+   ```
+
+2. **Find test creating node_modules:**
+   ```bash
+   ./find-polluter.sh 'node_modules' 'test/**/*.spec.js'
+   ```
+
+3. **Find test creating specific file:**
+   ```bash
+   ./find-polluter.sh 'unwanted-file.txt' '**/*.test.js'
+   ```

package/templates/.claude/skills/docs-discovery/COMPARISON.md

@@ -0,0 +1,313 @@
+# Before vs After: docs-discovery Skill Refactoring
+
+## Metrics
+
+| Metric | Before (v3.x) | After (v4.0) | Improvement |
+|--------|---------------|--------------|-------------|
+| **Total LOC** | 600+ lines (scripts) | 211 lines (prompts) | 65% reduction |
+| **Files** | 15+ files | 2 files | 87% reduction |
+| **Dependencies** | Node.js + packages | curl + grep | Zero deps |
+| **Language support** | English only (regex) | Any language | Universal |
+| **Flexibility** | Hardcoded patterns | LLM reasoning | Infinite |
+| **Maintenance** | Code changes | Markdown edits | Simple |
+
+## Complexity Comparison
+
+### Before: detect-topic.js (171 lines)
+
+```javascript
+const TOPIC_PATTERNS = [
+  /how (?:do i|to|can i) (?:use|implement|add|setup|configure) (?:the )?(.+?) (?:in|with|for) (.+)/i,
+  /(.+?) (.+?) (?:strategies|patterns|techniques|methods|approaches)/i,
+  /(.+?) (.+?) (?:documentation|docs|guide|tutorial)/i,
+  // ... 6 more hardcoded patterns
+];
+
+const GENERAL_PATTERNS = [
+  /(?:documentation|docs) for (.+)/i,
+  // ... 4 more patterns
+];
+
+function normalizeTopic(topic) {
+  return topic
+    .toLowerCase()
+    .trim()
+    .replace(/[^a-z0-9\s-]/g, '')
+    .replace(/\s+/g, '-')
+    .split('-')[0]
+    .slice(0, 20);
+}
+
+// Complex pattern matching logic...
+for (const pattern of TOPIC_PATTERNS) {
+  const match = trimmedQuery.match(pattern);
+  if (match) {
+    // Extract and normalize...
+  }
+}
+```
+
+**Problems:**
+- Only works with exact English patterns
+- Fails on: "shadcn의 date picker 사용법?" (Korean)
+- Fails on: "datepickr in shdcn" (typo)
+- Needs code update for new patterns
+- 171 lines to detect 2 pieces of information
+
+### After: SKILL.md Prompt
+
+```markdown
+**Your task:** Identify library and optional topic from user query.
+
+**Questions to ask yourself:**
+- Is this about a specific feature/component? → Topic-specific
+- Is this about general library docs? → General search
+- What's the library name?
+- What's the topic keyword (if any)?
+
+**Examples:**
+- "How do I use date picker in shadcn?" → Library: shadcn/ui, Topic: date
+- "Next.js caching strategies" → Library: next.js, Topic: cache
+```
+
+**Benefits:**
+- Works with any language
+- Handles typos naturally
+- Adapts to creative phrasing
+- Updates require markdown edits
+- 10 lines for same functionality
+
+## Real-World Examples
+
+### Example 1: Non-English Query
+
+**Query:** "Next.jsのキャッシュ戦略" (Japanese: "Next.js caching strategies")
+
+**Before (v3.x):**
+```bash
+node scripts/detect-topic.js "Next.jsのキャッシュ戦略"
+# Output: {"isTopicSpecific": false}
+# ❌ FAILED - No regex pattern matches Japanese
+```
+
+**After (v4.0):**
+```
+Claude analyzes: "This is about Next.js caching, written in Japanese"
+- Library: next.js → vercel/next.js
+- Topic: cache (キャッシュ)
+✅ SUCCESS - LLM understands intent across languages
+```
+
+### Example 2: Typo/Creative Phrasing
+
+**Query:** "datepickr component in shdcn pls"
+
+**Before (v3.x):**
+```bash
+node scripts/detect-topic.js "datepickr component in shdcn pls"
+# Output: {"isTopicSpecific": false}
+# ❌ FAILED - Pattern expects "shadcn" not "shdcn"
+```
+
+**After (v4.0):**
+```
+Claude analyzes: "User likely means shadcn/ui date picker despite typos"
+- Library: shdcn → shadcn-ui/ui (corrected)
+- Topic: datepickr → date (normalized)
+✅ SUCCESS - LLM handles typos and informal language
+```
+
+### Example 3: New Framework (Zero Code Changes)
+
+**Query:** "How to use signals in Solid.js?"
+
+**Before (v3.x):**
+```bash
+node scripts/fetch-docs.js "How to use signals in Solid.js?"
+# ❌ FAILED - "Solid.js" not in knownRepos mapping
+# Required: Update code, add to knownRepos, redeploy
+```
+
+**After (v4.0):**
+```
+Claude analyzes: "Solid.js is a framework, likely on GitHub"
+- Tries: solidjs/solid
+- If fails, tries: websites/solidjs
+✅ SUCCESS - No code update needed, Claude figures it out
+```
+
+## Architecture Philosophy
+
+### Before: Programmatic Intelligence
+
+```
+User Query → Regex Match → URL Builder → HTTP Fetch → Parser → Categorizer → Output
+              ↑              ↑                           ↑          ↑
+         Hardcoded      Hardcoded                  Hardcoded  Hardcoded
+```
+
+**Problem:** Every step requires code. Zero flexibility.
+
+### After: LLM-First Design
+
+```
+User Query → Claude Reasoning → Simple Tools (curl/grep) → Claude Synthesis → Output
+                    ↑                      ↑                      ↑
+                 Guided by             Data only            Guided by
+                 prompts                retrieval            prompts
+```
+
+**Benefit:** Claude does intelligent work, tools do dumb retrieval.
+
+## Maintenance Burden
+
+### Adding a New Library Mapping
+
+**Before (v3.x):**
+```javascript
+// File: scripts/fetch-docs.js
+// Line 87-95: Update knownRepos object
+
+const knownRepos = {
+  'next.js': 'vercel/next.js',
+  'remix': 'remix-run/remix',
+  // ... existing entries ...
+  'solid.js': 'solidjs/solid', // ← ADD THIS LINE
+};
+
+// Save file → Run tests → Commit → Push → Deploy
+```
+
+**After (v4.0):**
+```markdown
+# File: SKILL.md
+# Just add to table
+
+| solid.js | solidjs/solid |
+
+# Save → Done (no deployment needed)
+```
+
+### Adding a New Priority Keyword
+
+**Before (v3.x):**
+```javascript
+// File: scripts/analyze-llms-txt.js
+// Line 17-30: Update PRIORITY_KEYWORDS
+
+const PRIORITY_KEYWORDS = {
+  critical: [
+    'getting-started', 'quick-start',
+    'hooks', // ← ADD THIS
+  ],
+};
+
+// Save → Run tests → Update tests → Commit → Push → Deploy
+```
+
+**After (v4.0):**
+```markdown
+# Claude already knows "hooks" is important for React
+# No update needed - LLM reasons about priority contextually
+```
+
+## Testing Complexity
+
+### Before: Unit Tests Required
+
+```javascript
+// File: scripts/tests/test-detect-topic.js (82 lines)
+// File: scripts/tests/test-fetch-docs.js (103 lines)
+// File: scripts/tests/test-analyze-llms.js (67 lines)
+
+describe('detect-topic', () => {
+  it('should detect topic-specific query', () => {
+    const result = detectTopic('How do I use date picker in shadcn?');
+    expect(result.topic).toBe('date');
+    expect(result.library).toBe('shadcn-ui/ui');
+  });
+  // ... 20+ more test cases
+});
+```
+
+**Total: 252 lines of test code**
+
+### After: Prompt Validation Only
+
+```markdown
+# No unit tests needed
+# Validate by running actual queries with Claude
+# Self-correcting: Claude adapts based on results
+```
+
+**Total: 0 lines of test code**
+
+## Token Efficiency
+
+### Before: Script Overhead
+
+```bash
+# Execute 3 separate scripts
+node scripts/detect-topic.js "query"      # ~200ms
+node scripts/fetch-docs.js "query"        # ~500ms + network
+cat llms.txt | node scripts/analyze-llms-txt.js  # ~150ms
+
+# Total overhead: ~850ms + 3 shell executions
+# Context switches between Node and Claude
+```
+
+### After: Integrated Reasoning
+
+```bash
+# Claude reasons + single curl
+# Reasoning: ~0ms (parallel with planning)
+curl "https://context7.com/..."           # ~500ms network only
+
+# Total overhead: ~500ms + 1 shell execution
+# No context switches - pure Claude workflow
+```
+
+## Error Handling
+
+### Before: Rigid Error Paths
+
+```javascript
+if (res.statusCode === 404) {
+  return {
+    success: false,
+    error: 'Documentation not found on context7.com',
+    suggestion: 'Try repository analysis or web search',
+  };
+}
+```
+
+**Problem:** Generic error message, no adaptation
+
+### After: Contextual Fallback
+
+```markdown
+**If context7.com returns 404:**
+1. Try alternate path format (websites/ vs org/repo)
+2. Search for "{library} llms.txt" via web search
+3. Analyze GitHub repo README for doc links
+4. Use official website + manual curation
+```
+
+**Benefit:** Claude chooses best fallback based on context
+
+## Conclusion
+
+**Key Insight:** Skills should teach Claude HOW to think, not WHAT to execute.
+
+**Rule of Thumb:**
+- LLM is better at: Reasoning, pattern recognition, context understanding
+- Scripts are better at: HTTP requests, file I/O, data transformation
+
+**The simplified approach:**
+- Guides Claude's intelligence with prompts
+- Uses minimal bash tools for data retrieval
+- Eliminates 65% of code while adding infinite flexibility
+- Maintains zero dependencies
+- Self-adapting to new frameworks, languages, edge cases
+
+**Bottom line:** 211 lines of prompts > 600+ lines of scripts