@ngxtm/devkit 3.15.0 → 3.16.0

package/merged-commands/supabase-automation.md

@@ -0,0 +1,241 @@
+---
+name: supabase-automation
+description: "Automate Supabase database queries, table management, project administration, storage, edge functions, and SQL execution via Rube MCP (Composio). Always search tools first for current schemas."
+requires:
+  mcp: [rube]
+risk: unknown
+source: community
+---
+
+# Supabase Automation via Rube MCP
+
+Automate Supabase operations including database queries, table schema inspection, SQL execution, project and organization management, storage buckets, edge functions, and service health monitoring through Composio's Supabase toolkit.
+
+## Prerequisites
+
+- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
+- Active Supabase connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `supabase`
+- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas
+
+## Setup
+
+**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.
+
+
+1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
+2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `supabase`
+3. If connection is not ACTIVE, follow the returned auth link to complete Supabase authentication
+4. Confirm connection status shows ACTIVE before running any workflows
+
+## Core Workflows
+
+### 1. Query and Manage Database Tables
+
+**When to use**: User wants to read data from tables, inspect schemas, or perform CRUD operations
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - List projects to find the target project_ref [Prerequisite]
+2. `SUPABASE_LIST_TABLES` - List all tables and views in the database [Prerequisite]
+3. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed column types, constraints, and relationships [Prerequisite for writes]
+4. `SUPABASE_SELECT_FROM_TABLE` - Query rows with filtering, sorting, and pagination [Required for reads]
+5. `SUPABASE_BETA_RUN_SQL_QUERY` - Execute arbitrary SQL for complex queries, inserts, updates, or deletes [Required for writes]
+
+**Key parameters for SELECT_FROM_TABLE**:
+- `project_ref`: 20-character lowercase project reference
+- `table`: Table or view name to query
+- `select`: Comma-separated column list (supports nested selections and JSON paths like `profile->avatar_url`)
+- `filters`: Array of filter objects with `column`, `operator`, `value`
+- `order`: Sort expression like `created_at.desc`
+- `limit`: Max rows to return (minimum 1)
+- `offset`: Rows to skip for pagination
+
+**PostgREST filter operators**:
+- `eq`, `neq`: Equal / not equal
+- `gt`, `gte`, `lt`, `lte`: Comparison operators
+- `like`, `ilike`: Pattern matching (case-sensitive / insensitive)
+- `is`: IS check (for null, true, false)
+- `in`: In a list of values
+- `cs`, `cd`: Contains / contained by (arrays)
+- `fts`, `plfts`, `phfts`, `wfts`: Full-text search variants
+
+**Key parameters for RUN_SQL_QUERY**:
+- `ref`: Project reference (20 lowercase letters, pattern `^[a-z]{20}$`)
+- `query`: Valid PostgreSQL SQL statement
+- `read_only`: Boolean to force read-only transaction (safer for SELECTs)
+
+**Pitfalls**:
+- `project_ref` must be exactly 20 lowercase letters (a-z only, no numbers or hyphens)
+- `SELECT_FROM_TABLE` is read-only; use `RUN_SQL_QUERY` for INSERT, UPDATE, DELETE operations
+- For PostgreSQL array columns (text[], integer[]), use `ARRAY['item1', 'item2']` or `'{"item1", "item2"}'` syntax, NOT JSON array syntax `'["item1", "item2"]'`
+- SQL identifiers that are case-sensitive must be double-quoted in queries
+- Complex DDL operations may timeout (~60 second limit); break into smaller queries
+- ERROR 42P01 "relation does not exist" usually means unquoted case-sensitive identifiers
+- ERROR 42883 "function does not exist" means you are calling non-standard helpers; prefer information_schema queries
+
+### 2. Manage Projects and Organizations
+
+**When to use**: User wants to list projects, inspect configurations, or manage organizations
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_ORGANIZATIONS` - List all organizations (IDs and names) [Required]
+2. `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` - Get detailed org info by slug [Optional]
+3. `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` - List org members with roles and MFA status [Optional]
+4. `SUPABASE_LIST_ALL_PROJECTS` - List all projects with metadata [Required]
+5. `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` - Get database configuration [Optional]
+6. `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` - Get authentication configuration [Optional]
+7. `SUPABASE_GET_PROJECT_API_KEYS` - Get API keys (sensitive -- handle carefully) [Optional]
+8. `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` - Check service health [Optional]
+
+**Key parameters**:
+- `ref`: Project reference for project-specific tools
+- `slug`: Organization slug (URL-friendly identifier) for org tools
+- `services`: Array of services for health check: `auth`, `db`, `db_postgres_user`, `pg_bouncer`, `pooler`, `realtime`, `rest`, `storage`
+
+**Pitfalls**:
+- `LIST_ALL_ORGANIZATIONS` returns both `id` and `slug`; `LIST_MEMBERS_OF_AN_ORGANIZATION` expects `slug`, not `id`
+- `GET_PROJECT_API_KEYS` returns live secrets -- NEVER log, display, or persist full key values
+- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` requires a non-empty `services` array; empty array causes invalid_request error
+- Config tools may return 401/403 if token lacks required scope; handle gracefully rather than failing the whole workflow
+
+### 3. Inspect Database Schema
+
+**When to use**: User wants to understand table structure, columns, constraints, or generate types
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - Find the target project [Prerequisite]
+2. `SUPABASE_LIST_TABLES` - Enumerate all tables and views with metadata [Required]
+3. `SUPABASE_GET_TABLE_SCHEMAS` - Get detailed schema for specific tables [Required]
+4. `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` - Generate TypeScript types from schema [Optional]
+
+**Key parameters for LIST_TABLES**:
+- `project_ref`: Project reference
+- `schemas`: Array of schema names to search (e.g., `["public"]`); omit for all non-system schemas
+- `include_views`: Include views alongside tables (default true)
+- `include_metadata`: Include row count estimates and sizes (default true)
+- `include_system_schemas`: Include pg_catalog, information_schema, etc. (default false)
+
+**Key parameters for GET_TABLE_SCHEMAS**:
+- `project_ref`: Project reference
+- `table_names`: Array of table names (max 20 per request); supports schema prefix like `public.users`, `auth.users`
+- `include_relationships`: Include foreign key info (default true)
+- `include_indexes`: Include index info (default true)
+- `exclude_null_values`: Cleaner output by hiding null fields (default true)
+
+**Key parameters for GENERATE_TYPE_SCRIPT_TYPES**:
+- `ref`: Project reference
+- `included_schemas`: Comma-separated schema names (default `"public"`)
+
+**Pitfalls**:
+- Table names without schema prefix assume `public` schema
+- `row_count` and `size_bytes` from LIST_TABLES may be null for views or recently created tables; treat as unknown, not zero
+- GET_TABLE_SCHEMAS has a max of 20 tables per request; batch if needed
+- TypeScript types include all tables in specified schemas; cannot filter individual tables
+
+### 4. Manage Edge Functions
+
+**When to use**: User wants to list, inspect, or work with Supabase Edge Functions
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]
+2. `SUPABASE_LIST_ALL_FUNCTIONS` - List all edge functions with metadata [Required]
+3. `SUPABASE_RETRIEVE_A_FUNCTION` - Get detailed info for a specific function [Optional]
+
+**Key parameters**:
+- `ref`: Project reference
+- Function slug for RETRIEVE_A_FUNCTION
+
+**Pitfalls**:
+- `LIST_ALL_FUNCTIONS` returns metadata only, not function code or logs
+- `created_at` and `updated_at` may be epoch milliseconds; convert to human-readable timestamps
+- These tools cannot create or deploy edge functions; they are read-only inspection tools
+- Permission errors may occur without org/project admin rights
+
+### 5. Manage Storage Buckets
+
+**When to use**: User wants to list storage buckets or manage file storage
+
+**Tool sequence**:
+1. `SUPABASE_LIST_ALL_PROJECTS` - Find the project reference [Prerequisite]
+2. `SUPABASE_LISTS_ALL_BUCKETS` - List all storage buckets [Required]
+
+**Key parameters**:
+- `ref`: Project reference
+
+**Pitfalls**:
+- `LISTS_ALL_BUCKETS` returns bucket list only, not bucket contents or access policies
+- For file uploads, `SUPABASE_RESUMABLE_UPLOAD_SIGN_OPTIONS_WITH_ID` handles CORS preflight for TUS resumable uploads only
+- Direct file operations may require using `proxy_execute` with the Supabase storage API
+
+## Common Patterns
+
+### ID Resolution
+- **Project reference**: `SUPABASE_LIST_ALL_PROJECTS` -- extract `ref` field (20 lowercase letters)
+- **Organization slug**: `SUPABASE_LIST_ALL_ORGANIZATIONS` -- use `slug` (not `id`) for downstream org tools
+- **Table names**: `SUPABASE_LIST_TABLES` -- enumerate available tables before querying
+- **Schema discovery**: `SUPABASE_GET_TABLE_SCHEMAS` -- inspect columns and constraints before writes
+
+### Pagination
+- `SUPABASE_SELECT_FROM_TABLE`: Uses `offset` + `limit` pagination. Increment offset by limit until fewer rows than limit are returned.
+- `SUPABASE_LIST_ALL_PROJECTS`: May paginate for large accounts; follow cursors/pages until exhausted.
+- `SUPABASE_LIST_TABLES`: May paginate for large databases.
+
+### SQL Best Practices
+- Always use `SUPABASE_GET_TABLE_SCHEMAS` or `SUPABASE_LIST_TABLES` before writing SQL
+- Use `read_only: true` for SELECT queries to prevent accidental mutations
+- Quote case-sensitive identifiers: `SELECT * FROM "MyTable"` not `SELECT * FROM MyTable`
+- Use PostgreSQL array syntax for array columns: `ARRAY['a', 'b']` not `['a', 'b']`
+- Break complex DDL into smaller statements to avoid timeouts
+
+## Known Pitfalls
+
+### ID Formats
+- Project references are exactly 20 lowercase letters (a-z): pattern `^[a-z]{20}$`
+- Organization identifiers come as both `id` (UUID) and `slug` (URL-friendly string); tools vary in which they accept
+- `LIST_MEMBERS_OF_AN_ORGANIZATION` requires `slug`, not `id`
+
+### SQL Execution
+- `BETA_RUN_SQL_QUERY` has ~60 second timeout for complex operations
+- PostgreSQL array syntax required: `ARRAY['item']` or `'{"item"}'`, NOT JSON syntax `'["item"]'`
+- Case-sensitive identifiers must be double-quoted in SQL
+- ERROR 42P01: relation does not exist (check quoting and schema prefix)
+- ERROR 42883: function does not exist (use information_schema instead of custom helpers)
+
+### Sensitive Data
+- `GET_PROJECT_API_KEYS` returns service-role keys -- NEVER expose full values
+- Auth config tools exclude secrets but may still contain sensitive configuration
+- Always mask or truncate API keys in output
+
+### Schema Metadata
+- `row_count` and `size_bytes` from `LIST_TABLES` can be null; do not treat as zero
+- System schemas are excluded by default; set `include_system_schemas: true` to see them
+- Views appear alongside tables unless `include_views: false`
+
+### Rate Limits and Permissions
+- Enrichment tools (API keys, configs) may return 401/403 without proper scopes; skip gracefully
+- Large table listings may require pagination
+- `GETS_PROJECT_S_SERVICE_HEALTH_STATUS` fails with empty `services` array -- always specify at least one
+
+## Quick Reference
+
+| Task | Tool Slug | Key Params |
+|------|-----------|------------|
+| List organizations | `SUPABASE_LIST_ALL_ORGANIZATIONS` | (none) |
+| Get org info | `SUPABASE_GETS_INFORMATION_ABOUT_THE_ORGANIZATION` | `slug` |
+| List org members | `SUPABASE_LIST_MEMBERS_OF_AN_ORGANIZATION` | `slug` |
+| List projects | `SUPABASE_LIST_ALL_PROJECTS` | (none) |
+| List tables | `SUPABASE_LIST_TABLES` | `project_ref`, `schemas` |
+| Get table schemas | `SUPABASE_GET_TABLE_SCHEMAS` | `project_ref`, `table_names` |
+| Query table | `SUPABASE_SELECT_FROM_TABLE` | `project_ref`, `table`, `select`, `filters` |
+| Run SQL | `SUPABASE_BETA_RUN_SQL_QUERY` | `ref`, `query`, `read_only` |
+| Generate TS types | `SUPABASE_GENERATE_TYPE_SCRIPT_TYPES` | `ref`, `included_schemas` |
+| Postgres config | `SUPABASE_GETS_PROJECT_S_POSTGRES_CONFIG` | `ref` |
+| Auth config | `SUPABASE_GETS_PROJECT_S_AUTH_CONFIG` | `ref` |
+| Get API keys | `SUPABASE_GET_PROJECT_API_KEYS` | `ref` |
+| Service health | `SUPABASE_GETS_PROJECT_S_SERVICE_HEALTH_STATUS` | `ref`, `services` |
+| List edge functions | `SUPABASE_LIST_ALL_FUNCTIONS` | `ref` |
+| Get edge function | `SUPABASE_RETRIEVE_A_FUNCTION` | `ref`, function slug |
+| List storage buckets | `SUPABASE_LISTS_ALL_BUCKETS` | `ref` |
+| List DB branches | `SUPABASE_LIST_ALL_DATABASE_BRANCHES` | `ref` |
+
+## When to Use
+This skill is applicable to execute the workflow or actions described in the overview.

package/merged-commands/swiftui-expert-skill.md

@@ -1,6 +1,6 @@
 ---
 name: swiftui-expert-skill
-description: "Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when building new SwiftUI features, refactoring existing views, reviewing code quality, or adopting modern SwiftUI patterns."
+description: "Write, review, or improve SwiftUI code following best practices for state management, view composition, performance, modern APIs, Swift concurrency, and iOS 26+ Liquid Glass adoption. Use when buil..."
 source: "https://github.com/AvdLee/SwiftUI-Agent-Skill/tree/main/swiftui-expert-skill"
 risk: safe
 ---

package/merged-commands/systematic-debugging.md

@@ -1,296 +1,109 @@
 ---
 name: systematic-debugging
-description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+description: 4-phase systematic debugging methodology with root cause analysis and evidence-based verification. Use when debugging complex issues.
+allowed-tools: Read, Glob, Grep
 ---
 
 # Systematic Debugging
 
-## Overview
+> Source: obra/superpowers
 
-Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+## Overview
+This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
 
-**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+## 4-Phase Debugging Process
 
-**Violating the letter of this process is violating the spirit of debugging.**
+### Phase 1: Reproduce
+Before fixing, reliably reproduce the issue.
 
-## The Iron Law
+```markdown
+## Reproduction Steps
+1. [Exact step to reproduce]
+2. [Next step]
+3. [Expected vs actual result]
 
+## Reproduction Rate
+- [ ] Always (100%)
+- [ ] Often (50-90%)
+- [ ] Sometimes (10-50%)
+- [ ] Rare (<10%)
 ```
-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)
-
-## The Four Phases
-
-You MUST complete each phase before proceeding to the next.
-
-### 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
-   ```
-
-   **Example (multi-layer system):**
-   ```bash
-   # Layer 1: Workflow
-   echo "=== Secrets available in workflow: ==="
-   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
-
-   # Layer 2: Build script
-   echo "=== Env vars in build script: ==="
-   env | grep IDENTITY || echo "IDENTITY not in environment"
-
-   # Layer 3: Signing script
-   echo "=== Keychain state: ==="
-   security list-keychains
-   security find-identity -v
-
-   # Layer 4: Actual signing
-   codesign --sign "$IDENTITY" --verbose=4 "$APP"
-   ```
-
-   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
-
-5. **Trace Data Flow**
-
-   **WHEN error is deep in call stack:**
-
-   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
-
-   **Quick version:**
-   - 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
-
-### 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?
+### Phase 2: Isolate
+Narrow down the source.
 
-### 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
-
-### Phase 4: Implementation
-
-**Fix the root cause, not the symptom:**
-
-1. **Create Failing Test Case**
-   - Simplest possible reproduction
-   - Automated test if possible
-   - One-off test script if no framework
-   - MUST have before fixing
-   - Use the `superpowers:test-driven-development` 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
-
-   **STOP and question fundamentals:**
-   - Is this pattern fundamentally sound?
-   - Are we "sticking with it through sheer inertia"?
-   - Should we refactor architecture vs. continue fixing symptoms?
-
-   **Discuss with your human partner before attempting more fixes**
-
-   This is NOT a failed hypothesis - this is a wrong architecture.
-
-## 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.**
-
-**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
-
-## your human partner's Signals You're Doing It Wrong
-
-**Watch for these redirections:**
-- "Is that not happening?" - You assumed without verifying
-- "Will it show us...?" - You should have added evidence gathering
-- "Stop guessing" - You're proposing fixes without understanding
-- "Ultrathink this" - Question fundamentals, not just symptoms
-- "We're stuck?" (frustrated) - Your approach isn't working
-
-**When you see these:** STOP. Return to Phase 1.
-
-## 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. |
-| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
-| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
-| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
-
-## Quick Reference
-
-| Phase | Key Activities | Success Criteria |
-|-------|---------------|------------------|
-| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
-| **2. Pattern** | Find working examples, compare | Identify differences |
-| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
-| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+```markdown
+## Isolation Questions
+- When did this start happening?
+- What changed recently?
+- Does it happen in all environments?
+- Can we reproduce with minimal code?
+- What's the smallest change that triggers it?
+```
 
-## When Process Reveals "No Root Cause"
+### Phase 3: Understand
+Find the root cause, not just symptoms.
+
+```markdown
+## Root Cause Analysis
+### The 5 Whys
+1. Why: [First observation]
+2. Why: [Deeper reason]
+3. Why: [Still deeper]
+4. Why: [Getting closer]
+5. Why: [Root cause]
+```
 
-If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+### Phase 4: Fix & Verify
+Fix and verify it's truly fixed.
 
-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
+```markdown
+## Fix Verification
+- [ ] Bug no longer reproduces
+- [ ] Related functionality still works
+- [ ] No new issues introduced
+- [ ] Test added to prevent regression
+```
 
-**But:** 95% of "no root cause" cases are incomplete investigation.
+## Debugging Checklist
+
+```markdown
+## Before Starting
+- [ ] Can reproduce consistently
+- [ ] Have minimal reproduction case
+- [ ] Understand expected behavior
+
+## During Investigation
+- [ ] Check recent changes (git log)
+- [ ] Check logs for errors
+- [ ] Add logging if needed
+- [ ] Use debugger/breakpoints
+
+## After Fix
+- [ ] Root cause documented
+- [ ] Fix verified
+- [ ] Regression test added
+- [ ] Similar code checked
+```
 
-## Supporting Techniques
+## Common Debugging Commands
 
-These techniques are part of systematic debugging and available in this directory:
+```bash
+# Recent changes
+git log --oneline -20
+git diff HEAD~5
 
-- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
-- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
-- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+# Search for pattern
+grep -r "errorPattern" --include="*.ts"
 
-**Related skills:**
-- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
-- **superpowers:verification-before-completion** - Verify fix worked before claiming success
+# Check logs
+pm2 logs app-name --err --lines 100
+```
 
-## Real-World Impact
+## Anti-Patterns
 
-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
+❌ **Random changes** - "Maybe if I change this..."
+❌ **Ignoring evidence** - "That can't be the cause"
+❌ **Assuming** - "It must be X" without proof
+❌ **Not reproducing first** - Fixing blindly
+❌ **Stopping at symptoms** - Not finding root cause

package/merged-commands/systems-programming-rust-project.md

@@ -1,6 +1,8 @@
 ---
 name: systems-programming-rust-project
 description: "You are a Rust project architecture expert specializing in scaffolding production-ready Rust applications. Generate complete project structures with cargo tooling, proper module organization, testing"
+risk: unknown
+source: community
 ---
 
 # Rust Project Scaffolding

package/merged-commands/tailwind-design-system.md

@@ -1,6 +1,8 @@
 ---
 name: tailwind-design-system
-description: Build scalable design systems with Tailwind CSS, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.
+description: "Build scalable design systems with Tailwind CSS, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI..."
+risk: unknown
+source: community
 ---
 
 # Tailwind Design System

package/merged-commands/tailwind-patterns.md

@@ -1,13 +1,19 @@
 ---
 name: tailwind-patterns
-description: Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture.
+description: "Tailwind CSS v4 principles. CSS-first configuration, container queries, modern patterns, design token architecture."
 allowed-tools: Read, Write, Edit, Glob, Grep
+risk: unknown
+source: community
 ---
 
 # Tailwind CSS Patterns (v4 - 2025)
 
 > Modern utility-first CSS with CSS-native configuration.
 
+## When to Use
+
+Use this skill when configuring Tailwind v4, using CSS-first theme and design tokens, or implementing container queries and modern Tailwind patterns.
+
 ---
 
 ## 1. Tailwind v4 Architecture