codymaster 4.1.0

package/skills/cm-debugging/SKILL.md

@@ -0,0 +1,412 @@
+---
+name: cm-debugging
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+**Thinking principle (TRIZ):** Use structured cognitive tools — not just checklists — to see bugs from multiple dimensions. When linear investigation stalls, 9 Windows and Contradiction Analysis break the deadlock.
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## Bug Complexity Classifier
+
+Before entering the phases, classify the bug to determine which cognitive tools activate:
+
+```
+BUG enters cm-debugging
+  → Is reproduction straightforward AND error message points to exact cause?
+    → YES → SIMPLE PATH (standard Phase 0.5 → 1 → 2 → 3 → 4 → 5)
+    → NO  → COMPLEX PATH (all phases + TRIZ tools: 9 Windows, Contradiction, Troika)
+
+STALL DETECTOR (auto-triggers during any phase):
+  → Phase 1 investigation doesn't surface root cause after 2 attempts?
+  → Phase 3 hypothesis fails twice in a row?
+  → UPGRADE to Complex Path → activate TRIZ tools immediately
+```
+
+> **Why classify?** Simple bugs don't need heavy thinking tools. Complex bugs NEED them. The stall detector catches bugs that look simple but aren't.
+
+## The Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 0.5: Memory Integrity Check (BEFORE blaming code)
+
+> **BEFORE blaming code, ASK: "Could memory be causing this bug?"**
+
+1. **SUSPECT** — Identify relevant memories:
+   - What module/file is the bug in?
+   - Read `.cm/learnings.json` filtered by that scope
+   - List all active learnings + decisions for this area
+
+2. **INVESTIGATE** — Did AI follow a memory when writing buggy code?
+   - Check: Does the buggy code match a `prevention` pattern from any learning?
+   - Check: Does the buggy code follow a `decision` that may be outdated?
+   - If YES → that memory is a **suspect**
+
+3. **VERIFY** — Is the suspect memory still correct?
+   - Compare learning with current codebase (not when it was recorded)
+   - Has the dependency/pattern/architecture changed since learning was recorded?
+   - If memory is WRONG → proceed to HEAL
+
+4. **HEAL** (only if memory confirmed as cause):
+   - **Invalidate:** Set `status = "invalidated"` — learning is proven wrong
+   - **Correct:** Update `prevention` with correct info, set `status = "corrected"`
+   - **Scope-reduce:** Learning is right for smaller scope → narrow the scope
+   - **Record meta-learning** in `.cm/meta-learnings.json`
+
+```
+IF memory caused the bug:
+  → HEAL memory FIRST
+  → THEN proceed to Phase 1 to fix code
+  → The code fix will be correct because memory is now correct
+
+IF memory did NOT cause the bug:
+  → Proceed to Phase 1 normally
+```
+
+> **WHY PHASE 0.5?** Fix memory first → code fix will be correct.
+> Without fixing memory → bug will return next session (bug loop).
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+6. **9 Windows Analysis (TRIZ) — Complex Path / Stall Detector**
+
+   **WHEN standard investigation stalls OR bug classified as complex:**
+
+   Map the bug across 3 time periods × 3 system scopes:
+
+   ```
+   ┌──────────────────┬───────────────────────┬───────────────────────┬───────────────────────┐
+   │                  │  BEFORE bug           │  DURING bug           │  AFTER fix (target)   │
+   ├──────────────────┼───────────────────────┼───────────────────────┼───────────────────────┤
+   │  SUPER-SYSTEM    │  What was the system  │  What external        │  What system-level    │
+   │  (environment,   │  environment before?  │  conditions exist     │  changes prevent      │
+   │   CI, infra,     │  Any env/dep/infra    │  during the bug?      │  recurrence?          │
+   │   dependencies)  │  changes?             │  (timing, load, etc.) │                       │
+   ├──────────────────┼───────────────────────┼───────────────────────┼───────────────────────┤
+   │  SYSTEM          │  How did the module   │  What is the exact    │  How should the       │
+   │  (module/feature)│  work before the bug? │  broken behavior?     │  module work after?   │
+   │                  │  Last known good?     │  What's different     │  What invariant       │
+   │                  │  (git log, deploy)    │  from expected?       │  must hold?           │
+   ├──────────────────┼───────────────────────┼───────────────────────┼───────────────────────┤
+   │  SUB-SYSTEM      │  What were the        │  What specific        │  What component       │
+   │  (function, var, │  component values/    │  values/states are    │  changes fix this     │
+   │   config, state) │  states before?       │  wrong now?           │  at the root?         │
+   └──────────────────┴───────────────────────┴───────────────────────┴───────────────────────┘
+   ```
+
+   **Fill ALL 9 windows.** This reveals:
+   - **Temporal blind spots:** What changed between BEFORE and DURING?
+   - **Scope blind spots:** Is the root cause at a DIFFERENT level than the symptom?
+   - **Fix quality:** Does the target AFTER state prevent the class of bug, not just this instance?
+
+   > **WHY 9 WINDOWS?** Most debugging stalls happen because you're looking at the wrong time period OR the wrong system level. 9 Windows forces you to check ALL combinations.
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+5. **Contradiction Analysis (TRIZ) — Complex Path / Stall Detector**
+
+   **WHEN pattern analysis reveals conflicting behaviors or "impossible" states:**
+
+   Fill in this template:
+
+   ```
+   CONTRADICTION TEMPLATE:
+   ┌─────────────────────────────────────────────────────────────┐
+   │ System NEEDS:  [what the feature/module SHOULD do]         │
+   │ System DOES:   [what it ACTUALLY does]                     │
+   │ Conflict:      [WHY it can't do both — the hidden tension] │
+   │ Resolution:    [dissolve the contradiction, don't compromise]│
+   └─────────────────────────────────────────────────────────────┘
+   ```
+
+   **Common debugging contradictions:**
+   - "Function must be fast" vs "Function must be complete" → missing edge case in optimization
+   - "Config must be flexible" vs "Config must have safe defaults" → bad default caused the bug
+   - "Module must be independent" vs "Module needs shared state" → coupling created race condition
+
+   > **WHY CONTRADICTION?** Bugs often hide where two legitimate requirements CONFLICT. Standard pattern analysis compares code structure. Contradiction analysis compares system INTENTIONS.
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+5. **Troika Consulting (TRIZ) — Complex Path / When Hypothesis Stalls**
+
+   **WHEN you can't form a strong hypothesis OR 2 hypotheses have failed:**
+
+   Force yourself to generate hypotheses from **3 different lenses**:
+
+   ```
+   LENS 1 — Code Lens:
+     "What code path leads to this state?"
+     Focus: control flow, logic branches, exception handling, return values
+
+   LENS 2 — Data Lens:
+     "What data/input causes this? What data is missing, corrupt, or unexpected?"
+     Focus: input validation, data shape, null/undefined, encoding, type coercion
+
+   LENS 3 — Environment Lens:
+     "What environmental factor triggers this?"
+     Focus: timing, concurrency, config, network, filesystem, memory, OS differences
+   ```
+
+   **Rules:**
+   - You MUST generate at least 1 hypothesis from EACH lens
+   - If a lens seems "irrelevant" — that's exactly where the bug hides
+   - Test the hypothesis from the LEAST obvious lens first
+
+   > **WHY TROIKA?** When debugging stalls, it's because you're stuck in ONE perspective. Troika forces 3 fundamentally different viewpoints. The bug is almost always visible from a lens you haven't tried.
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - MUST have before fixing
+   - Use the `cm-tdd` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+### Step 5: Record Learning (MANDATORY)
+
+After fixing any bug, ALWAYS write to `.cm/CONTINUITY.md` → "Mistakes & Learnings":
+
+```
+- What Failed:      [exact error message or behavior]
+- Why It Failed:    [root cause from Phase 1]
+- How to Prevent:   [concrete pattern to avoid]
+- Scope:            [global | module:{name} | file:{path}]
+```
+
+**Scope rules:** Choose the SMALLEST scope that applies.
+- Bug in one file → `file:src/api/routes.ts`
+- Bug in module pattern → `module:auth`
+- Bug in project-wide practice → `global`
+
+**Anti-duplicate:** If a similar learning already exists in `.cm/learnings.json`,
+reinforce it (reinforceCount++) instead of creating a new entry.
+
+> **Token savings:** Next time same error pattern appears, AI reads the learning
+> (~50 tokens) instead of repeating full 4-phase debug cycle (~3,000 tokens).
+> **This is the #1 token saver in the entire kit.**
+
+---
+
+## Red Flags - STOP and Follow Process
+
+If you 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"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**When you see these user signals:** STOP. Return to Phase 1.
+- "Stop guessing"
+- "Ultrathink this"
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+
+## Quick Reference
+
+| Phase | Key Activities | TRIZ Tool (Complex Path) | Success Criteria |
+|-------|---------------|--------------------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | **9 Windows** — temporal × spatial analysis | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | **Contradiction Analysis** — conflicting requirements | Identify root differences |
+| **3. Hypothesis** | Form theory, test minimally | **Troika** — Code/Data/Environment lenses | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | — | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Integration
+
+**Related skills:**
+- **cm-tdd** - For creating failing test case (Phase 4, Step 1)
+- **cm-quality-gate** - Verify fix worked before claiming success
+- **cm-brainstorm-idea** - When 3+ fixes fail and bug reveals architectural problem → redirect to brainstorm
+
+**TRIZ tools used:**
+- **9 Windows** (Phase 1) — See bug across time × system scope
+- **Contradiction Analysis** (Phase 2) — Find hidden conflicts between requirements
+- **Troika Consulting** (Phase 3) — Force 3 different lenses on the same bug

package/skills/cm-deep-search/SKILL.md

@@ -0,0 +1,242 @@
+---
+name: cm-deep-search
+description: "Optional power-up — detects oversized codebases/docs and suggests tobi/qmd for local semantic search. Bridges cm-continuity (working memory) with long-term document retrieval. Zero-config detection, non-intrusive suggestion."
+---
+
+# Deep Search — Semantic Memory Power-Up
+
+> **When your project outgrows AI's context window, bring the search engine to your docs.**
+> Optional integration with [tobi/qmd](https://github.com/tobi/qmd) — BM25 + Vector + LLM re-ranking, 100% local.
+
+## When to Trigger
+
+**This skill is NOT invoked directly.** It is triggered automatically by other skills when they detect an oversized project.
+
+### Detection Thresholds
+
+During codebase scan (Phase 1a of `cm-brainstorm-idea`, Step 2 of `cm-dockit`, etc.), check:
+
+```
+TRIGGER if ANY of these are true:
+  → docs/ folder contains >50 markdown files
+  → Project has >200 source files total
+  → User mentions "meeting notes", "historical PRDs", "old specs"
+  → User asks "find that file that talked about X from before"
+  → cm-dockit just generated >30 doc files
+```
+
+### What to Say (Non-Intrusive)
+
+When threshold is met, suggest naturally — DO NOT block or force:
+
+```markdown
+💡 **Pro Tip: Deep Search**
+
+This project has [X doc files / Y source files] — quite large for AI to read directly.
+You can install **[qmd](https://github.com/tobi/qmd)** to create semantic search
+across all your documentation, helping AI find the right context faster.
+
+Quick install:
+\`\`\`bash
+npm install -g @tobilu/qmd
+qmd collection add ./docs --name project-docs
+qmd context add qmd://project-docs "Project documentation for [project-name]"
+qmd embed
+\`\`\`
+
+Then AI can search using: `qmd query "your question"`
+```
+
+---
+
+## Setup Guide (when user agrees to install)
+
+### Step 1: Install
+
+```bash
+# Node.js
+npm install -g @tobilu/qmd
+
+# Or Bun
+bun install -g @tobilu/qmd
+```
+
+### Step 2: Index project docs
+
+```bash
+# Add collections
+qmd collection add ./docs --name docs
+qmd collection add ./src --name source --mask "**/*.{ts,tsx,js,jsx,py,go,rs}"
+
+# Add context (helps AI understand each collection's purpose)
+qmd context add qmd://docs "Technical documentation for [project-name]"
+qmd context add qmd://source "Source code for [project-name]"
+
+# Create vector embeddings
+qmd embed
+```
+
+### Step 3: Setup MCP Server (for Claude/Cursor/Antigravity)
+
+Add to MCP config:
+
+```json
+{
+  "mcpServers": {
+    "qmd": {
+      "command": "qmd",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+Or run HTTP mode for shared server:
+
+```bash
+qmd mcp --http --daemon
+```
+
+### Step 4: Verify
+
+```bash
+# Check index
+qmd status
+
+# Test search
+qmd query "authentication flow"
+```
+
+---
+
+## Usage with CodyMaster Skills
+
+### With `cm-brainstorm-idea` (Phase 1: DISCOVER)
+
+When AI needs to understand the full picture of a large project:
+
+```bash
+# Find all docs related to the topic being brainstormed
+qmd query "user authentication redesign" --json -n 10
+
+# Get full content of important docs
+qmd get "docs/architecture.md" --full
+```
+
+### With `cm-planning` (Phase A: Brainstorm)
+
+When searching for specs, PRDs, or past decisions related to the feature being planned:
+
+```bash
+qmd query "payment integration decisions" --files --min-score 0.4
+```
+
+### With `cm-dockit` (Post-generation)
+
+After `cm-dockit` finishes generating docs, index them so AI can search from any session:
+
+```bash
+qmd collection add ./docs --name project-knowledge
+qmd embed
+```
+
+### With `cm-continuity` (Tier 4: External Memory)
+
+`cm-continuity` manages working memory (500 words). `qmd` extends it with long-term semantic search:
+
+```
+Tier 1: Sensory Memory     → temporary variables in session (not persisted)
+Tier 2: Working Memory      → CONTINUITY.md (~500 words)
+Tier 3: Long-Term Memory    → learnings.json, decisions.json
+Tier 4: External Semantic   → qmd (optional, used when project is large)
+```
+
+---
+
+## 🛑 Staleness Prevention
+
+The biggest risk of Semantic Search is **stale index / new source**. If AI reads outdated docs and generates incorrect code, the consequences are severe.
+
+CodyMaster handles this with 3 mechanisms:
+
+### 1. The "Post-Execution" Sync
+Whenever AI completes a task that changes/creates a large number of files (e.g., `cm-dockit` generates docs, `cm-execution` refactors source code):
+```bash
+# This runs quickly because qmd only embeds changed files (incremental)
+qmd embed
+```
+> **AI Rule:** If the project has qmd enabled, AI must automatically run `qmd embed` via terminal before finishing a task.
+
+### 2. The "Pre-Flight" Check
+Before starting `cm-brainstorm-idea` or `cm-planning` on a project using qmd, AI calls the MCP tool to perform a health check:
+```json
+// AI auto-runs this MCP tool
+{
+  "name": "status",
+  "arguments": {}
+}
+```
+If status reports files pending/un-embedded, AI will run `qmd embed` in terminal before searching.
+
+### 3. Git Hook (Recommended for User)
+For 100% safety beyond AI's control (when end-user modifies code directly):
+AI should suggest the user install a **Git Post-Commit Hook**:
+```bash
+# Add file .git/hooks/post-commit
+#!/bin/sh
+qmd embed > /dev/null 2>&1 &
+```
+This ensures every commit triggers QMD to silently update the index in the background.
+
+---
+
+## Position in CodyMaster Lifecycle
+
+```
+cm-continuity (memory) ─────────────── always active
+cm-deep-search (search) ──── optional ─┤
+                                       ├── feeds context to ──→ cm-brainstorm-idea
+                                       │                   ──→ cm-planning
+cm-dockit (generate docs) ── produces ─┤                   ──→ cm-execution
+```
+
+## Integration
+
+| Skill | Relationship |
+|-------|-------------|
+| `cm-continuity` | COMPLEMENT: continuity = RAM, qmd = semantic disk search |
+| `cm-brainstorm-idea` | TRIGGERED BY: Phase 1a codebase scan detects large corpus |
+| `cm-dockit` | TRIGGERED AFTER: docs generated, suggest indexing |
+| `cm-planning` | CONSUMER: uses qmd results for context during planning |
+| `cm-execution` | CONSUMER: searches for related code/docs during execution |
+
+---
+
+## Requirements
+
+```
+System: macOS / Linux / Windows (WSL)
+Runtime: Node.js 20+ or Bun 1.0+
+VRAM: ~2-4GB for GGUF models (embedding + reranking)
+Disk: ~2-5GB for models (downloaded on first run)
+```
+
+## Rules
+
+```
+✅ DO:
+- Suggest qmd ONLY when detection threshold is met
+- Keep suggestion non-intrusive (Pro Tip format, never blocking)
+- Always include context command (qmd context add) — this is qmd's killer feature
+- Guide user to setup MCP server for seamless AI integration
+
+❌ DON'T:
+- Force installation on every project
+- Suggest qmd for small projects (<50 docs, <200 src files)
+- Replace cm-continuity — they solve DIFFERENT problems
+- Assume qmd is installed — always check first
+```
+
+## The Bottom Line
+
+**`cm-continuity` = "remembers what you're doing." `cm-deep-search` = "finds what was written before." Together = complete memory system.**