cokit-cli 1.3.0 → 1.4.0

package/skills/context-engineering/SKILL.md

@@ -1,107 +0,0 @@
----
-name: context-engineering
-description: >-
-  Check context usage limits, monitor time remaining, optimize token consumption, debug context failures.
-  Use when asking about context percentage, rate limits, usage warnings, context optimization, agent architectures, memory systems.
-argument-hint: "[topic or question]"
----
-
-# Context Engineering
-
-Context engineering curates the smallest high-signal token set for LLM tasks. The goal: maximize reasoning quality while minimizing token usage.
-
-## When to Activate
-
-- Designing/debugging agent systems
-- Context limits constrain performance
-- Optimizing cost/latency
-- Building multi-agent coordination
-- Implementing memory systems
-- Evaluating agent performance
-- Developing LLM-powered pipelines
-
-## Core Principles
-
-1. **Context quality > quantity** - High-signal tokens beat exhaustive content
-2. **Attention is finite** - U-shaped curve favors beginning/end positions
-3. **Progressive disclosure** - Load information just-in-time
-4. **Isolation prevents degradation** - Partition work across sub-agents
-5. **Measure before optimizing** - Know your baseline
-
-**IMPORTANT:**
-- Sacrifice grammar for the sake of concision.
-- Ensure token efficiency while maintaining high quality.
-- Pass these rules to subagents.
-
-## Quick Reference
-
-| Topic | When to Use | Reference |
-|-------|-------------|-----------|
-| **Fundamentals** | Understanding context anatomy, attention mechanics | [context-fundamentals.md](./references/context-fundamentals.md) |
-| **Degradation** | Debugging failures, lost-in-middle, poisoning | [context-degradation.md](./references/context-degradation.md) |
-| **Optimization** | Compaction, masking, caching, partitioning | [context-optimization.md](./references/context-optimization.md) |
-| **Compression** | Long sessions, summarization strategies | [context-compression.md](./references/context-compression.md) |
-| **Memory** | Cross-session persistence, knowledge graphs | [memory-systems.md](./references/memory-systems.md) |
-| **Multi-Agent** | Coordination patterns, context isolation | [multi-agent-patterns.md](./references/multi-agent-patterns.md) |
-| **Evaluation** | Testing agents, LLM-as-Judge, metrics | [evaluation.md](./references/evaluation.md) |
-| **Tool Design** | Tool consolidation, description engineering | [tool-design.md](./references/tool-design.md) |
-| **Pipelines** | Project development, batch processing | [project-development.md](./references/project-development.md) |
-| **Runtime Awareness** | Usage limits, context window monitoring | [runtime-awareness.md](./references/runtime-awareness.md) |
-
-## Key Metrics
-
-- **Token utilization**: Warning at 70%, trigger optimization at 80%
-- **Token variance**: Explains 80% of agent performance variance
-- **Multi-agent cost**: ~15x single agent baseline
-- **Compaction target**: 50-70% reduction, <5% quality loss
-- **Cache hit target**: 70%+ for stable workloads
-
-## Four-Bucket Strategy
-
-1. **Write**: Save context externally (scratchpads, files)
-2. **Select**: Pull only relevant context (retrieval, filtering)
-3. **Compress**: Reduce tokens while preserving info (summarization)
-4. **Isolate**: Split across sub-agents (partitioning)
-
-## Anti-Patterns
-
-- Exhaustive context over curated context
-- Critical info in middle positions
-- No compaction triggers before limits
-- Single agent for parallelizable tasks
-- Tools without clear descriptions
-
-## Guidelines
-
-1. Place critical info at beginning/end of context
-2. Implement compaction at 70-80% utilization
-3. Use sub-agents for context isolation, not role-play
-4. Design tools with 4-question framework (what, when, inputs, returns)
-5. Optimize for tokens-per-task, not tokens-per-request
-6. Validate with probe-based evaluation
-7. Monitor KV-cache hit rates in production
-8. Start minimal, add complexity only when proven necessary
-
-## Runtime Awareness
-
-The system automatically injects usage awareness via PostToolUse hook:
-
-```xml
-<usage-awareness>
-AI Usage Limits: 5h=45%, 7d=32%
-Context Window Usage: 67%
-</usage-awareness>
-```
-
-**Thresholds:**
-- 70%: WARNING - consider optimization/compaction
-- 90%: CRITICAL - immediate action needed
-
-**Data Sources:**
-- Usage limits: Anthropic OAuth API (`https://api.anthropic.com/api/oauth/usage`)
-- Context window: Statusline temp file (`/tmp/ck-context-{session_id}.json`)
-
-## Scripts
-
-- [context_analyzer.py](./scripts/context_analyzer.py) - Context health analysis, degradation detection
-- [compression_evaluator.py](./scripts/compression_evaluator.py) - Compression quality evaluation

package/skills/cook/SKILL.md

@@ -1,155 +0,0 @@
----
-name: cook
-description: "ALWAYS activate this skill before implementing EVERY feature, plan, or fix."
-argument-hint: "[task|plan-path] [--interactive|--fast|--parallel|--auto|--no-test]"
----
-
-# Cook - Smart Feature Implementation
-
-End-to-end implementation with automatic workflow detection.
-
-**Principles:** YAGNI, KISS, DRY | Token efficiency | Concise reports
-
-## Usage
-
-```
-/ck-cook <natural language task OR plan path>
-```
-
-**IMPORTANT:** If no flag is provided, the skill will use the `interactive` mode by default for the workflow.
-
-**Optional flags to select the workflow mode:** 
-- `--interactive`: Full workflow with user input (**default**)
-- `--fast`: Skip research, scout→plan→code
-- `--parallel`: Multi-agent execution
-- `--no-test`: Skip testing step
-- `--auto`: Auto-approve all steps
-
-**Example:**
-```
-/ck-cook "Add user authentication to the app" --fast
-/ck-cook path/to/plan.md --auto
-```
-
-<HARD-GATE>
-Do NOT write implementation code until a plan exists and has been reviewed.
-This applies regardless of task simplicity. "Simple" tasks are where unexamined assumptions waste the most time.
-Exception: `--fast` mode skips research but still requires a plan step.
-User override: If user explicitly says "just code it" or "skip planning", respect their instruction.
-</HARD-GATE>
-
-## Anti-Rationalization
-
-| Thought | Reality |
-|---------|---------|
-| "This is too simple to plan" | Simple tasks have hidden complexity. Plan takes 30 seconds. |
-| "I already know how to do this" | Knowing ≠ planning. Write it down. |
-| "Let me just start coding" | Undisciplined action wastes tokens. Plan first. |
-| "The user wants speed" | Fastest path = plan → implement → done. Not: implement → debug → rewrite. |
-| "I'll plan as I go" | That's not planning, that's hoping. |
-| "Just this once" | Every skip is "just this once." No exceptions. |
-
-## Smart Intent Detection
-
-| Input Pattern | Detected Mode | Behavior |
-|---------------|---------------|----------|
-| Path to `plan.md` or `phase-*.md` | code | Execute existing plan |
-| Contains "fast", "quick" | fast | Skip research, scout→plan→code |
-| Contains "trust me", "auto" | auto | Auto-approve all steps |
-| Lists 3+ features OR "parallel" | parallel | Multi-agent execution |
-| Contains "no test", "skip test" | no-test | Skip testing step |
-| Default | interactive | Full workflow with user input |
-
-See `references/intent-detection.md` for detection logic.
-
-## Process Flow (Authoritative)
-
-```mermaid
-flowchart TD
-    A[Intent Detection] --> B{Has plan path?}
-    B -->|Yes| F[Load Plan]
-    B -->|No| C{Mode?}
-    C -->|fast| D[Scout → Plan → Code]
-    C -->|interactive/auto| E[Research → Review → Plan]
-    E --> F
-    D --> F
-    F --> G[Review Gate]
-    G -->|approved| H[Implement]
-    G -->|rejected| E
-    H --> I[Review Gate]
-    I -->|approved| J{--no-test?}
-    J -->|No| K[Test]
-    J -->|Yes| L[Finalize]
-    K --> L
-    L --> M[Report + Journal]
-```
-
-**This diagram is the authoritative workflow.** Prose sections below provide detail for each node. If prose conflicts with this flow, follow the diagram.
-
-## Workflow Overview
-
-```
-[Intent Detection] → [Research?] → [Review] → [Plan] → [Review] → [Implement] → [Review] → [Test?] → [Review] → [Finalize]
-```
-
-**Default (non-auto):** Stops at `[Review]` gates for human approval before each major step.
-**Auto mode (`--auto`):** Skips human review gates, implements all phases continuously.
-**Tasks:** Utilize `TaskCreate`, `TaskUpdate`, `TaskGet`, `TaskList` during implementation step. **Fallback:** These are CLI-only tools — unavailable in VSCode extension. If they error, use `TodoWrite` for progress tracking instead.
-
-| Mode | Research | Testing | Review Gates | Phase Progression |
-|------|----------|---------|--------------|-------------------|
-| interactive | ✓ | ✓ | **User approval at each step** | One at a time |
-| auto | ✓ | ✓ | Auto if score≥9.5 | All at once (no stops) |
-| fast | ✗ | ✓ | **User approval at each step** | One at a time |
-| parallel | Optional | ✓ | **User approval at each step** | Parallel groups |
-| no-test | ✓ | ✗ | **User approval at each step** | One at a time |
-| code | ✗ | ✓ | **User approval at each step** | Per plan |
-
-## Step Output Format
-
-```
-✓ Step [N]: [Brief status] - [Key metrics]
-```
-
-## Blocking Gates (Non-Auto Mode)
-
-Human review required at these checkpoints (skipped with `--auto`):
-- **Post-Research:** Review findings before planning
-- **Post-Plan:** Approve plan before implementation
-- **Post-Implementation:** Approve code before testing
-- **Post-Testing:** 100% pass + approve before finalize
-
-**Always enforced (all modes):**
-- **Testing:** 100% pass required (unless no-test mode)
-- **Code Review:** User approval OR auto-approve (score≥9.5, 0 critical)
-- **Finalize (MANDATORY - never skip):**
-  1. `project-manager` subagent → run full plan sync-back (all completed tasks/steps across all `phase-XX-*.md`, not only current phase), then update `plan.md` status/progress
-  2. `docs-manager` subagent → update `./docs` if changes warrant
-  3. `TaskUpdate` → mark all Tasks complete after sync-back verification (skip if Task tools unavailable)
-  4. Ask user if they want to commit via `git-manager` subagent
-  5. Run `/ck-journal` to write a concise technical journal entry upon completion
-
-## Required Subagents (MANDATORY)
-
-| Phase | Subagent | Requirement |
-|-------|----------|-------------|
-| Research | `researcher` | Optional in fast/code |
-| Scout | `scout` | Optional in code |
-| Plan | `planner` | Optional in code |
-| UI Work | `ui-ux-designer` | If frontend work |
-| Testing | `tester`, `debugger` | **MUST** spawn |
-| Review | `code-reviewer` | **MUST** spawn |
-| Finalize | `project-manager`, `docs-manager`, `git-manager` | **MUST** spawn all 3 |
-
-**CRITICAL ENFORCEMENT:**
-- Steps 4, 5, 6 **MUST** use Task tool to spawn subagents
-- DO NOT implement testing, review, or finalization yourself - DELEGATE
-- If workflow ends with 0 Task tool calls, it is INCOMPLETE
-- Pattern: `Task(subagent_type="[type]", prompt="[task]", description="[brief]")`
-
-## References
-
-- `references/intent-detection.md` - Detection rules and routing logic
-- `references/workflow-steps.md` - Detailed step definitions for all modes
-- `references/review-cycle.md` - Interactive and auto review processes
-- `references/subagent-patterns.md` - Subagent invocation patterns

package/skills/cook/references/workflow-steps.md

@@ -1,192 +0,0 @@
-# Unified Workflow Steps
-
-All modes share core steps with mode-specific variations.
-
-**Task Tool Fallback:** `TaskCreate`/`TaskUpdate`/`TaskGet`/`TaskList` are CLI-only — unavailable in VSCode extension. If they error, use `TodoWrite` for progress tracking. All workflow steps remain functional without Task tools.
-
-## Step 0: Intent Detection & Setup
-
-1. Parse input with `intent-detection.md` rules
-2. Log detected mode: `✓ Step 0: Mode [X] - [reason]`
-3. If mode=code: detect plan path, set active plan
-4. Use `TaskCreate` to create workflow step tasks (with dependencies if complex)
-
-**Output:** `✓ Step 0: Mode [interactive|auto|fast|parallel|no-test|code] - [detection reason]`
-
-## Step 1: Research (skip if fast/code mode)
-
-**Interactive/Auto:**
-- Spawn multiple `researcher` agents in parallel
-- Use `/ck-scout ext` or `scout` agent for codebase search
-- Keep reports ≤150 lines
-
-**Parallel:**
-- Optional: max 2 researchers if complex
-
-**Output:** `✓ Step 1: Research complete - [N] reports gathered`
-
-### [Review Gate 1] Post-Research (skip if auto mode)
-- Present research summary to user
-- Use asking the user to ask: "Proceed to planning?" / "Request more research" / "Abort"
-- **Auto mode:** Skip this gate
-
-## Step 2: Planning
-
-**Interactive/Auto/No-test:**
-- Use `planner` agent with research context
-- Create `plan.md` + `phase-XX-*.md` files
-
-**Fast:**
-- Use `/ck-plan --fast` with scout results only
-- Minimal planning, focus on action
-
-**Parallel:**
-- Use `/ck-plan --parallel` for dependency graph + file ownership matrix
-
-**Code:**
-- Skip - plan already exists
-- Parse existing plan for phases
-
-**Output:** `✓ Step 2: Plan created - [N] phases`
-
-### [Review Gate 2] Post-Plan (skip if auto mode)
-- Present plan overview with phases
-- Use asking the user to ask: "Validate the plan or approve plan to start implementation?" - "Validate" / "Approve" / "Abort" / "Other" ("Request revisions")
-  - "Validate": run `/ck-plan validate` skill invocation
-  - "Approve": continue to implementation
-  - "Abort": stop the workflow
-  - "Other": revise the plan based on user's feedback
-- **Auto mode:** Skip this gate
-
-## Step 3: Implementation
-
-**IMPORTANT:**
-1. `TaskList` first — check for existing tasks (hydrated by planning skill in same session)
-2. If tasks exist → pick them up, skip re-creation
-3. If no tasks → read plan phases, `TaskCreate` for each unchecked `[ ]` item with priority order and metadata (`phase`, `planDir`, `phaseFile`)
-4. Tasks can be blocked by other tasks via `addBlockedBy`
-
-**All modes:**
-- Use `TaskUpdate` to mark tasks as `in_progress` immediately.
-- Execute phase tasks sequentially (Step 3.1, 3.2, etc.)
-- Use `ui-ux-designer` for frontend
-- Use `ai-multimodal` (if available) for image assets
-- Run type checking after each file
-
-**Parallel mode:**
-- Utilize all tools of Tasks: `TaskCreate`, `TaskUpdate`, `TaskGet` and `TaskList`
-- Launch multiple `fullstack-developer` agents
-- When agents pick up a task, use `TaskUpdate` to assign task to agent and mark tasks as `in_progress` immediately.
-- Respect file ownership boundaries
-- Wait for parallel group before next
-
-**Output:** `✓ Step 3: Implemented [N] files - [X/Y] tasks complete`
-
-### [Review Gate 3] Post-Implementation (skip if auto mode)
-- Present implementation summary (files changed, key changes)
-- Use asking the user to ask: "Proceed to testing?" / "Request implementation changes" / "Abort"
-- **Auto mode:** Skip this gate
-
-## Step 4: Testing (skip if no-test mode)
-
-**All modes (except no-test):**
-- Write tests: happy path, edge cases, errors
-- **MUST** spawn `tester` subagent: `Task(subagent_type="tester", prompt="Run test suite", description="Run tests")`
-- If failures: **MUST** spawn `debugger` subagent → fix → repeat
-- **Forbidden:** fake mocks, commented tests, changed assertions, skipping subagent delegation
-
-**Output:** `✓ Step 4: Tests [X/X passed] - tester subagent invoked`
-
-### [Review Gate 4] Post-Testing (skip if auto mode)
-- Present test results summary
-- Use asking the user to ask: "Proceed to code review?" / "Request test fixes" / "Abort"
-- **Auto mode:** Skip this gate
-
-## Step 5: Code Review
-
-**All modes - MANDATORY subagent:**
-- **MUST** spawn `code-reviewer` subagent: `Task(subagent_type="code-reviewer", prompt="Review changes. Return score, critical issues, warnings.", description="Code review")`
-- **DO NOT** review code yourself - delegate to subagent
-
-**Interactive/Parallel/Code/No-test:**
-- Interactive cycle (max 3): see `review-cycle.md`
-- Requires user approval
-
-**Auto:**
-- Auto-approve if score≥9.5 AND 0 critical
-- Auto-fix critical (max 3 cycles)
-- Escalate to user after 3 failed cycles
-
-**Fast:**
-- Simplified review, no fix loop
-- User approves or aborts
-
-**Output:** `✓ Step 5: Review [score]/10 - [Approved|Auto-approved] - code-reviewer subagent invoked`
-
-## Step 6: Finalize
-
-**All modes - MANDATORY subagents (NON-NEGOTIABLE):**
-1. **MUST** spawn these subagents in parallel:
-   - `Task(subagent_type="project-manager", prompt="Run full sync-back for [plan-path]: reconcile all completed Tasks with all phase files, backfill stale completed checkboxes across every phase, then update plan.md frontmatter/table progress. Do NOT only mark current phase.", description="Update plan")`
-   - `Task(subagent_type="docs-manager", prompt="Update docs for changes.", description="Update docs")`
-2. Project-manager sync-back MUST include:
-
-### Status Sync (Finalize)
-
-Use CLI commands for deterministic status updates:
-
-```bash
-# Mark completed phases
-ck plan check <phase-id>
-
-# Mark in-progress phases
-ck plan check <phase-id> --start
-
-# Revert if needed
-ck plan uncheck <phase-id>
-```
-
-**Fallback:** If `ck` is not available, edit plan.md directly —
-only change the Status column cell, preserve table structure.
-   - Sweep all `phase-XX-*.md` files in the plan directory.
-   - Mark every completed item `[ ] → [x]` based on completed tasks (including earlier phases finished before current phase).
-   - Update `plan.md` status/progress (`pending`/`in-progress`/`completed`) from actual checkbox state.
-   - Return unresolved mappings if any completed task cannot be matched to a phase file.
-3. Use `TaskUpdate` to mark Tasks complete after sync-back confirmation.
-4. Onboarding check (API keys, env vars)
-5. **MUST** spawn git subagent: `Task(subagent_type="git-manager", prompt="Stage and commit changes", description="Commit")`
-
-**CRITICAL:** Step 6 is INCOMPLETE without spawning all 3 subagents. DO NOT skip subagent delegation.
-
-**Auto mode:** Continue to next phase automatically, start from **Step 3**.
-**Others:** Ask user before next phase
-
-**Output:** `✓ Step 6: Finalized - 3 subagents invoked - Full-plan sync-back completed - Committed`
-
-## Mode-Specific Flow Summary
-
-Legend: `[R]` = Review Gate (human approval required)
-
-```
-interactive: 0 → 1 → [R] → 2 → [R] → 3 → [R] → 4 → [R] → 5(user) → 6
-auto:        0 → 1 → 2 → 3 → 4 → 5(auto) → 6 → next phase (NO stops)
-fast:        0 → skip → 2(fast) → [R] → 3 → [R] → 4 → [R] → 5(simple) → 6
-parallel:    0 → 1? → [R] → 2(parallel) → [R] → 3(multi-agent) → [R] → 4 → [R] → 5(user) → 6
-no-test:     0 → 1 → [R] → 2 → [R] → 3 → [R] → skip → 5(user) → 6
-code:        0 → skip → skip → 3 → [R] → 4 → [R] → 5(user) → 6
-```
-
-**Key difference:** `auto` mode is the ONLY mode that skips all review gates.
-
-## Critical Rules
-
-- Never skip steps without mode justification
-- **MANDATORY SUBAGENT DELEGATION:** Steps 4, 5, 6 MUST spawn subagents via Task tool. DO NOT implement directly.
-  - Step 4: `tester` (and `debugger` if failures)
-  - Step 5: `code-reviewer`
-  - Step 6: `project-manager`, `docs-manager`, `git-manager`
-- Use `TaskCreate` to create Tasks for each unchecked item with priority order and dependencies (or `TodoWrite` if Task tools unavailable).
-- Use `TaskUpdate` to mark Tasks `in_progress` when picking up a task (skip if Task tools unavailable).
-- Use `TaskUpdate` to mark Tasks `complete` immediately after finalizing the task (skip if Task tools unavailable).
-- All step outputs follow format: `✓ Step [N]: [status] - [metrics]`
-- **VALIDATION:** If Task tool calls = 0 at end of workflow, the workflow is INCOMPLETE.

package/skills/databases/SKILL.md

@@ -1,84 +0,0 @@
----
-name: databases
-description: Design schemas, write queries for MongoDB and PostgreSQL. Use for database design, SQL/NoSQL queries, aggregation pipelines, indexes, migrations, replication, performance optimization, psql CLI.
-license: MIT
-argument-hint: "[query or schema task]"
----
-
-# Databases Skill
-
-Unified guide for working with MongoDB (document-oriented) and PostgreSQL (relational) databases. Choose the right database for your use case and master both systems.
-
-## When to Use This Skill
-
-Use when:
-- Designing database schemas and data models
-- Writing queries (SQL or MongoDB query language)
-- Building aggregation pipelines or complex joins
-- Optimizing indexes and query performance
-- Implementing database migrations
-- Setting up replication, sharding, or clustering
-- Configuring backups and disaster recovery
-- Managing database users and permissions
-- Analyzing slow queries and performance issues
-- Administering production database deployments
-
-## Reference Navigation
-
-### Database Design
-- **[db-design.md](references/db-design.md)** - Activate when user requests: Database/table design for transactional (OLTP), analytics (OLAP), create or extend schema, design fact/dimension tables, analyze/review CSV/JSON/SQL files to create tables, or need advice on data storage structure.
-
-### MongoDB References
-- **[mongodb-crud.md](references/mongodb-crud.md)** - CRUD operations, query operators, atomic updates
-- **[mongodb-aggregation.md](references/mongodb-aggregation.md)** - Aggregation pipeline, stages, operators, patterns
-- **[mongodb-indexing.md](references/mongodb-indexing.md)** - Index types, compound indexes, performance optimization
-- **[mongodb-atlas.md](references/mongodb-atlas.md)** - Atlas cloud setup, clusters, monitoring, search
-
-### PostgreSQL References
-- **[postgresql-queries.md](references/postgresql-queries.md)** - SELECT, JOINs, subqueries, CTEs, window functions
-- **[postgresql-psql-cli.md](references/postgresql-psql-cli.md)** - psql commands, meta-commands, scripting
-- **[postgresql-performance.md](references/postgresql-performance.md)** - EXPLAIN, query optimization, vacuum, indexes
-- **[postgresql-administration.md](references/postgresql-administration.md)** - User management, backups, replication, maintenance
-
-## Python Utilities
-
-Database utility scripts in `scripts/`:
-- **db_migrate.py** - Generate and apply migrations for both databases (MongoDB and PostgreSQL)
-- **db_backup.py** - Backup and restore MongoDB and PostgreSQL
-- **db_performance_check.py** - Analyze slow queries and recommend indexes
-
-```bash
-# Generate migration
-python scripts/db_migrate.py --db mongodb --generate "add_user_index"
-
-# Run backup
-python scripts/db_backup.py --db postgres --output /backups/
-
-# Check performance
-python scripts/db_performance_check.py --db mongodb --threshold 100ms
-```
-
-## Best Practices
-
-**MongoDB:**
-- Use embedded documents for 1-to-few relationships
-- Reference documents for 1-to-many or many-to-many
-- Index frequently queried fields
-- Use aggregation pipeline for complex transformations
-- Enable authentication and TLS in production
-- Use Atlas for managed hosting
-
-**PostgreSQL:**
-- Normalize schema to 3NF, denormalize for performance
-- Use foreign keys for referential integrity
-- Index foreign keys and frequently filtered columns
-- Use EXPLAIN ANALYZE to optimize queries
-- Regular VACUUM and ANALYZE maintenance
-- Connection pooling (pgBouncer) for web apps
-
-## Resources
-
-- MongoDB: https://www.mongodb.com/docs/
-- PostgreSQL: https://www.postgresql.org/docs/
-- MongoDB University: https://learn.mongodb.com/
-- PostgreSQL Tutorial: https://www.postgresqltutorial.com/

package/skills/debug/SKILL.md

@@ -1,120 +0,0 @@
----
-name: debug
-description: "Debug systematically with root cause analysis before fixes. Use for bugs, test failures, unexpected behavior, performance issues, call stack tracing, multi-layer validation, log analysis, CI/CD failures, database diagnostics, system investigation."
-languages: all
-argument-hint: "[error or issue description]"
----
-
-# Debugging & System Investigation
-
-Comprehensive framework combining systematic debugging, root cause tracing, defense-in-depth validation, verification protocols, and system-level investigation (logs, CI/CD, databases, performance).
-
-## Core Principle
-
-**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST**
-
-Random fixes waste time and create new bugs. Find root cause, fix at source, validate at every layer, verify before claiming success.
-
-## When to Use
-
-**Code-level:** Test failures, bugs, unexpected behavior, build failures, integration problems
-**System-level:** Server errors, CI/CD pipeline failures, performance degradation, database issues, log analysis
-**Always:** Before claiming work complete
-
-## Techniques
-
-### 1. Systematic Debugging (`references/systematic-debugging.md`)
-
-Four-phase framework: Root Cause Investigation → Pattern Analysis → Hypothesis Testing → Implementation. Complete each phase before proceeding. No fixes without Phase 1.
-
-**Load when:** Any bug/issue requiring investigation and fix
-
-### 2. Root Cause Tracing (`references/root-cause-tracing.md`)
-
-Trace bugs backward through call stack to find original trigger. Fix at source, not symptom. Includes `scripts/find-polluter.sh` for bisecting test pollution.
-
-**Load when:** Error deep in call stack, unclear where invalid data originated
-
-### 3. Defense-in-Depth (`references/defense-in-depth.md`)
-
-Validate at every layer: Entry validation → Business logic → Environment guards → Debug instrumentation
-
-**Load when:** After finding root cause, need comprehensive validation
-
-### 4. Verification (`references/verification.md`)
-
-**Iron law:** NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE. Run command. Read output. Then claim result.
-
-**Load when:** About to claim work complete, fixed, or passing
-
-### 5. Investigation Methodology (`references/investigation-methodology.md`)
-
-Five-step structured investigation for system-level issues: Initial Assessment → Data Collection → Analysis → Root Cause ID → Solution Development
-
-**Load when:** Server incidents, system behavior analysis, multi-component failures
-
-### 6. Log & CI/CD Analysis (`references/log-and-ci-analysis.md`)
-
-Collect and analyze logs from servers, CI/CD pipelines (GitHub Actions), application layers. Tools: `gh` CLI, structured log queries, correlation across sources.
-
-**Load when:** CI/CD pipeline failures, server errors, deployment issues
-
-### 7. Performance Diagnostics (`references/performance-diagnostics.md`)
-
-Identify bottlenecks, analyze query performance, develop optimization strategies. Covers database queries, API response times, resource utilization.
-
-**Load when:** Performance degradation, slow queries, high latency, resource exhaustion
-
-### 8. Reporting Standards (`references/reporting-standards.md`)
-
-Structured diagnostic reports: Executive Summary → Technical Analysis → Recommendations → Evidence
-
-**Load when:** Need to produce investigation report or diagnostic summary
-
-### 9. Task Management (`references/task-management-debugging.md`)
-
-Track investigation pipelines via Native Tasks (TaskCreate, TaskUpdate, TaskList). Hydration pattern for multi-step investigations with dependency chains and parallel evidence collection. **Fallback:** Task tools are CLI-only — if unavailable (VSCode extension), use `TodoWrite` for tracking. Debug workflow remains fully functional.
-
-**Load when:** Multi-component investigation (3+ steps), parallel log collection, coordinating debugger subagents
-
-### 10. Frontend Verification (`references/frontend-verification.md`)
-
-Visual verification of frontend implementations via Chrome MCP (if available) or `chrome-devtools` (if available) skill fallback. Detect if frontend-related → check Chrome MCP availability → screenshot + console error check → report. Skip if not frontend.
-
-**Load when:** Implementation touches frontend files (tsx/jsx/vue/svelte/html/css), UI bugs, visual regressions
-
-## Quick Reference
-
-```
-Code bug       → systematic-debugging.md (Phase 1-4)
-  Deep in stack  → root-cause-tracing.md (trace backward)
-  Found cause    → defense-in-depth.md (add layers)
-  Claiming done  → verification.md (verify first)
-
-System issue   → investigation-methodology.md (5 steps)
-  CI/CD failure  → log-and-ci-analysis.md
-  Slow system    → performance-diagnostics.md
-  Need report    → reporting-standards.md
-
-Frontend fix   → frontend-verification.md (Chrome/devtools)
-```
-
-## Tools Integration
-
-- **Database:** `psql` for PostgreSQL queries and diagnostics
-- **CI/CD:** `gh` CLI for GitHub Actions logs and pipeline debugging
-- **Codebase:** `docs-seeker` skill for package/plugin docs; `repomix` skill for codebase summary
-- **Scouting:** `/ck-scout` or `/ck-scout ext` for finding relevant files
-- **Frontend:** Chrome browser or `chrome-devtools` (if available) skill for visual verification (screenshots, console, network)
-- **Skills:** Activate `problem-solving` skill when stuck on complex issues
-
-## Red Flags
-
-Stop and follow process if thinking:
-- "Quick fix for now, investigate later"
-- "Just try changing X and see if it works"
-- "It's probably X, let me fix that"
-- "Should work now" / "Seems fixed"
-- "Tests pass, we're done"
-
-**All mean:** Return to systematic process.