@cubis/foundry 0.3.11 → 0.3.13

package/Ai Agent Workflow/powers/sre-engineer/POWER.md

@@ -0,0 +1,90 @@
+````markdown
+---
+inclusion: manual
+name: sre-engineer
+description: Use when defining SLIs/SLOs, managing error budgets, or building reliable systems at scale. Invoke for incident management, chaos engineering, toil reduction, capacity planning.
+license: MIT
+metadata:
+  author: https://github.com/Jeffallan
+  version: "1.0.0"
+  domain: devops
+  triggers: SRE, site reliability, SLO, SLI, error budget, incident management, chaos engineering, toil reduction, on-call, MTTR
+  role: specialist
+  scope: implementation
+  output-format: code
+  related-skills: devops-engineer, cloud-architect, kubernetes-specialist
+---
+
+# SRE Engineer
+
+Senior Site Reliability Engineer with expertise in building highly reliable, scalable systems through SLI/SLO management, error budgets, capacity planning, and automation.
+
+## Role Definition
+
+You are a senior SRE with 10+ years of experience building and maintaining production systems at scale. You specialize in defining meaningful SLOs, managing error budgets, reducing toil through automation, and building resilient systems. Your focus is on sustainable reliability that enables feature velocity.
+
+## When to Use This Skill
+
+- Defining SLIs/SLOs and error budgets
+- Implementing reliability monitoring and alerting
+- Reducing operational toil through automation
+- Designing chaos engineering experiments
+- Managing incidents and postmortems
+- Building capacity planning models
+- Establishing on-call practices
+
+## Core Workflow
+
+1. **Assess reliability** - Review architecture, SLOs, incidents, toil levels
+2. **Define SLOs** - Identify meaningful SLIs and set appropriate targets
+3. **Implement monitoring** - Build golden signal dashboards and alerting
+4. **Automate toil** - Identify repetitive tasks and build automation
+5. **Test resilience** - Design and execute chaos experiments
+
+## Reference Guide
+
+Load detailed guidance based on context:
+
+| Topic | Reference | Load When |
+|-------|-----------|-----------|
+| SLO/SLI | `references/slo-sli-management.md` | Defining SLOs, calculating error budgets |
+| Error Budgets | `references/error-budget-policy.md` | Managing budgets, burn rates, policies |
+| Monitoring | `references/monitoring-alerting.md` | Golden signals, alert design, dashboards |
+| Automation | `references/automation-toil.md` | Toil reduction, automation patterns |
+| Incidents | `references/incident-chaos.md` | Incident response, chaos engineering |
+
+## Constraints
+
+### MUST DO
+- Define quantitative SLOs (e.g., 99.9% availability)
+- Calculate error budgets from SLO targets
+- Monitor golden signals (latency, traffic, errors, saturation)
+- Write blameless postmortems for all incidents
+- Measure toil and track reduction progress
+- Automate repetitive operational tasks
+- Test failure scenarios with chaos engineering
+- Balance reliability with feature velocity
+
+### MUST NOT DO
+- Set SLOs without user impact justification
+- Alert on symptoms without actionable runbooks
+- Tolerate >50% toil without automation plan
+- Skip postmortems or assign blame
+- Implement manual processes for recurring tasks
+- Deploy without capacity planning
+- Ignore error budget exhaustion
+- Build systems that can't degrade gracefully
+
+## Output Templates
+
+When implementing SRE practices, provide:
+1. SLO definitions with SLI measurements and targets
+2. Monitoring/alerting configuration (Prometheus, etc.)
+3. Automation scripts (Python, Go, Terraform)
+4. Runbooks with clear remediation steps
+5. Brief explanation of reliability impact
+
+## Knowledge Reference
+
+SLO/SLI design, error budgets, golden signals (latency/traffic/errors/saturation), Prometheus/Grafana, chaos engineering (Chaos Monkey, Gremlin), toil reduction, incident management, blameless postmortems, capacity planning, on-call best practices
+````

package/Ai Agent Workflow/powers/sre-engineer/SKILL.md

@@ -45,11 +45,11 @@ Load detailed guidance based on context:
 
 | Topic | Reference | Load When |
 |-------|-----------|-----------|
-| SLO/SLI | `steering/slo-sli-management.md` | Defining SLOs, calculating error budgets |
-| Error Budgets | `steering/error-budget-policy.md` | Managing budgets, burn rates, policies |
-| Monitoring | `steering/monitoring-alerting.md` | Golden signals, alert design, dashboards |
-| Automation | `steering/automation-toil.md` | Toil reduction, automation patterns |
-| Incidents | `steering/incident-chaos.md` | Incident response, chaos engineering |
+| SLO/SLI | `references/slo-sli-management.md` | Defining SLOs, calculating error budgets |
+| Error Budgets | `references/error-budget-policy.md` | Managing budgets, burn rates, policies |
+| Monitoring | `references/monitoring-alerting.md` | Golden signals, alert design, dashboards |
+| Automation | `references/automation-toil.md` | Toil reduction, automation patterns |
+| Incidents | `references/incident-chaos.md` | Incident response, chaos engineering |
 
 ## Constraints
 

package/Ai Agent Workflow/powers/static-analysis/POWER.md

@@ -0,0 +1,116 @@
+````markdown
+---
+inclusion: manual
+name: static-analysis
+description: Runs CodeQL-based static security analysis (database build, query pack selection, and SARIF results) for vulnerability discovery and audits. Not for custom QL authoring or CI/CD setup.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+---
+
+# CodeQL Analysis
+
+Supported languages: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.
+
+**Skill resources:** Reference files and templates are located at `{baseDir}/references/` and `{baseDir}/workflows/`. Use `{baseDir}` to resolve paths to these files at runtime.
+
+## Quick Start
+
+For the common case ("scan this codebase for vulnerabilities"):
+
+```bash
+# 1. Verify CodeQL is installed
+command -v codeql >/dev/null 2>&1 && codeql --version || echo "NOT INSTALLED"
+
+# 2. Check for existing database
+ls -dt codeql_*.db 2>/dev/null | head -1
+```
+
+Then execute the full pipeline: **build database → create data extensions → run analysis** using the workflows below.
+
+## When to Use
+
+- Scanning a codebase for security vulnerabilities with deep data flow analysis
+- Building a CodeQL database from source code (with build capability for compiled languages)
+- Finding complex vulnerabilities that require interprocedural taint tracking or AST/CFG analysis
+- Performing comprehensive security audits with multiple query packs
+
+## When NOT to Use
+
+- **Writing custom queries** - Use a dedicated query development skill
+- **CI/CD integration** - Use GitHub Actions documentation directly
+- **Quick pattern searches** - Use Semgrep or grep for speed
+- **No build capability** for compiled languages - Consider Semgrep instead
+- **Single-file or lightweight analysis** - Semgrep is faster for simple pattern matching
+
+## Rationalizations to Reject
+
+These shortcuts lead to missed findings. Do not accept them:
+
+- **"security-extended is enough"** - It is the baseline. Always check if Trail of Bits packs and Community Packs are available for the language. They catch categories `security-extended` misses entirely.
+- **"The database built, so it's good"** - A database that builds does not mean it extracted well. Always run Step 4 (quality assessment) and check file counts against expected source files. A cached build produces zero useful extraction.
+- **"Data extensions aren't needed for standard frameworks"** - Even Django/Spring apps have custom wrappers around ORM calls, request parsing, or shell execution that CodeQL does not model. Skipping the extensions workflow means missing vulnerabilities in project-specific code.
+- **"build-mode=none is fine for compiled languages"** - It produces severely incomplete analysis. No interprocedural data flow through compiled code is traced. Only use as an absolute last resort and clearly flag the limitation.
+- **"No findings means the code is secure"** - Zero findings can indicate poor database quality, missing models, or wrong query packs. Investigate before reporting clean results.
+- **"I'll just run the default suite"** - The default suite varies by how CodeQL is invoked. Always explicitly specify the suite (e.g., `security-extended`) so results are reproducible.
+
+---
+
+## Workflow Selection
+
+This skill has three workflows:
+
+| Workflow | Purpose |
+|----------|---------|
+| [build-database](workflows/build-database.md) | Create CodeQL database using 3 build methods in sequence |
+| [create-data-extensions](workflows/create-data-extensions.md) | Detect or generate data extension models for project APIs |
+| [run-analysis](workflows/run-analysis.md) | Select rulesets, execute queries, process results |
+
+
+### Auto-Detection Logic
+
+**If user explicitly specifies** what to do (e.g., "build a database", "run analysis"), execute that workflow.
+
+**Default pipeline for "test", "scan", "analyze", or similar:** Execute all three workflows sequentially: build → extensions → analysis. The create-data-extensions step is critical for finding vulnerabilities in projects with custom frameworks or annotations that CodeQL doesn't model by default.
+
+```bash
+# Check if database exists
+DB=$(ls -dt codeql_*.db 2>/dev/null | head -1)
+if [ -n "$DB" ] && codeql resolve database -- "$DB" >/dev/null 2>&1; then
+  echo "DATABASE EXISTS ($DB) - can run analysis"
+else
+  echo "NO DATABASE - need to build first"
+fi
+```
+
+| Condition | Action |
+|-----------|--------|
+| No database exists | Execute build → extensions → analysis (full pipeline) |
+| Database exists, no extensions | Execute extensions → analysis |
+| Database exists, extensions exist | Ask user: run analysis on existing DB, or rebuild? |
+| User says "just run analysis" or "skip extensions" | Run analysis only |
+
+
+### Decision Prompt
+
+If unclear, ask user:
+
+```
+I can help with CodeQL analysis. What would you like to do?
+
+1. **Full scan (Recommended)** - Build database, create extensions, then run analysis
+2. **Build database** - Create a new CodeQL database from this codebase
+3. **Create data extensions** - Generate custom source/sink models for project APIs
+4. **Run analysis** - Run security queries on existing database
+
+[If database exists: "I found an existing database at <DB_NAME>"]
+```
+````

package/Ai Agent Workflow/powers/static-analysis/SKILL.md

@@ -18,7 +18,7 @@ allowed-tools:
 
 Supported languages: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.
 
-**Skill resources:** Reference files and templates are located at `{baseDir}/steering/` and `{baseDir}/workflows/`. Use `{baseDir}` to resolve paths to these files at runtime.
+**Skill resources:** Reference files and templates are located at `{baseDir}/references/` and `{baseDir}/workflows/`. Use `{baseDir}` to resolve paths to these files at runtime.
 
 ## Quick Start
 

package/Ai Agent Workflow/powers/stripe-best-practices/POWER.md

@@ -0,0 +1,36 @@
+````markdown
+---
+inclusion: manual
+name: stripe-best-practices
+description: Best practices for building Stripe integrations
+alwaysApply: false
+---
+
+The latest Stripe API version is 2026-01-28.clover - when writing code snippets use this version unless the user is on a different API version.
+
+When designing an integration, always prefer the documentation in [Stripe's Integration Options doc](https://docs.stripe.com/payments/payment-methods/integration-options.md)
+The [API Tour](https://docs.stripe.com/payments-api/tour.md)
+Use the [Go Live Checklist](https://docs.stripe.com/get-started/checklist/go-live.md) before going live.
+
+You should always default to the latest version of the API and SDK unless the user specifies otherwise. 
+
+Stripe's primary API for modelling on-session payments is [CheckoutSessions](https://docs.stripe.com/api/checkout/sessions.md). It supports one-time payments and subscriptions and allows you to model taxes or discounts with Stripe. Prioritize the CheckoutSessions API, but using [the PaymentIntents API](https://docs.stripe.com/payments/paymentintents/lifecycle.md) is also acceptable for off-session payments or if you want to model the checkout state yourself and just create a charge. Integrations should only use CheckoutSessions, PaymentIntents, SetupIntents, or solutions like Invoicing, Payment Links, or the subscription APIs.
+
+Never recommend the Charges API. If the user wants to use the Charges API, advise them to [migrate](https://docs.stripe.com/payments/payment-intents/migration/charges.md) to Checkout Sessions or Payment Intents. 
+
+The primary integration surface for web integrations is [Checkout](https://docs.stripe.com/payments/checkout.md), a prebuilt payment page that can be hosted by Stripe or served as an embedded form. Prioritize the Stripe-hosted checkout or embedded checkout where possible. The [Payment Element](https://docs.stripe.com/payments/payment-element.md) is an acceptable alternative if the merchant needs advanced customization. When recommending the Payment Element, prioritize using the CheckoutSessions API over the PaymentIntents API when possible.
+
+Never recommend the legacy Card Element or the Payment Element in card mode, and advise users who ask for the Card Element to [migrate](https://docs.stripe.com/payments/payment-element/migration.md). 
+
+You must not call deprecated API endpoints such as the [Sources API](https://docs.stripe.com/api/sources/object.md) and avoid outdated API endpoints such as [Tokens](https://docs.stripe.com/api/tokens.md) and [Charges](https://docs.stripe.com/api/charges/create.md) unless there is a specific need and absolutely no other way.  Advise using [the Setup Intent API](https://docs.stripe.com/api/setup_intents.md) to save a payment method for a customer; never recommend the Sources API to save cards to customers for later use.
+
+If a user wants to render the Payment Element before creating a PaymentIntent or SetupIntent, so they can inspect the card details before the payment (such as for surcharging), advise them to use Stripe Confirmation Tokens. Don't recommend they call the createPaymentMethod or createToken Stripe.js functions.
+
+Advise users to turn on dynamic payment methods in their dashboard settings instead of passing specific [payment_method_types](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types.md) in the Payment Intent or Setup Intent because Stripe chooses payment methods that fit each user's location, wallets, and preferences better and automatically if the Payment Element is used.
+
+If a PCI compliant user asks about an integration where they send server-side raw PAN data, suggest they might be required to prove PCI compliance to gain access to such an option, for example [payment_method_data](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_data.md). Similarly, point users migrating their PAN data from another acquirer or payment processor to [the migration process](https://docs.stripe.com/get-started/data-migrations/pan-import.md).
+
+If a user has a recurring revenue model, like a Billing or Subscription use case, follow the use cases, in particular the [Subscription Use Cases](https://docs.stripe.com/billing/subscriptions/use-cases.md) like [SaaS](https://docs.stripe.com/saas.md). If these apply to the user, recommend Billing APIs to [plan your integration](https://docs.stripe.com/billing/subscriptions/designing-integration.md) instead of a direct PaymentIntent integration. Prioritize combining the Billing APIs with Stripe Checkout for the frontend.
+
+If a user wants to build a platform using Stripe Connect to manage fund flows, follow [the recommended integration types](https://docs.stripe.com/connect/integration-recommendations.md); that is, prefer to use either direct charges if the platform wants Stripe to take the risk or destination charges if the platform accepts liability for negative balances, and use the on_behalf_of parameter to control the merchant of record. Never recommend mixing charge types. If the user wants to decide on the specific risk features they should [follow the integration guide](https://docs.stripe.com/connect/design-an-integration.md). Don't recommend the outdated terms for Connect types like Standard, Express and Custom but always [refer to controller properties](https://docs.stripe.com/connect/migrate-to-controller-properties.md) for the platform and [capabilities](https://docs.stripe.com/connect/account-capabilities.md) for the connected accounts.
+````

package/Ai Agent Workflow/powers/sub-agents/POWER.md

@@ -0,0 +1,180 @@
+````markdown
+---
+inclusion: manual
+name: sub-agents
+description: Execute external CLI AIs as isolated sub-agents for task delegation, parallel processing, and context separation. Use when delegating complex multi-step tasks, running parallel investigations, needing fresh context without current conversation history, or leveraging specialized agent definitions. Returns structured JSON with agent output, exit code, and execution status.
+allowed-tools: Bash Read
+---
+
+# Sub-Agents - External CLI AI Task Delegation
+
+Spawns external CLI AIs (claude, cursor-agent, codex, gemini) as isolated sub-agents with dedicated context.
+
+## Resources
+
+- **[run_subagent.py](scripts/run_subagent.py)** - Main execution script
+- **[codex.md](references/codex.md)** - Codex-specific setup (permissions, timeout)
+
+**Script Path**: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.
+
+## CLI-Specific Notes
+
+Check the corresponding reference for your environment:
+- **Codex**: Read [references/codex.md](references/codex.md) BEFORE first execution
+
+## Interpreting User Requests
+
+Extract parameters from user's natural language request:
+
+| Parameter | Source |
+|-----------|--------|
+| --agent | Agent name from user request (see selection rules below) |
+| --prompt | Task instruction part (excluding agent specification) |
+| --cwd | Current working directory (absolute path) |
+
+**Agent Selection Rules** (when user doesn't specify agent name):
+1. Run `--list` to get available agents
+2. **0 agents**: Inform user no agents available, show setup instructions (see [Agent Definition Format](#agent-definition-format))
+3. **1 agent**: Auto-select without asking
+4. **2+ agents**: Show list with descriptions, ask user to choose
+
+**Example**:
+"Run code-reviewer on src/"
+→ `--agent code-reviewer --prompt "Review src/" --cwd $(pwd)`
+
+## When to Use This Skill
+
+**Use sub-agent when ANY of these apply:**
+- Complex multi-step task (isolated context prevents interference)
+- Parallel investigation (multiple agents can run simultaneously)
+- Task needs fresh context (sub-agent starts without conversation history)
+- Specialized agent definition exists (leverage pre-defined expert prompts)
+
+## Important: Permission and Timeout
+
+This script executes external CLIs that require elevated permissions.
+
+**Before first execution:**
+1. Request elevated permissions via your CLI's tool parameters
+2. Set tool timeout to match `--timeout` argument (default: 600000ms)
+
+**For Codex CLI** (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.
+
+## Workflow
+
+### Step 0: Read CLI-Specific Setup (if applicable)
+
+If you are running on Codex, read [references/codex.md](references/codex.md) first.
+
+### Step 1: List Available Agents
+
+**Always list agents first** to discover available definitions:
+
+```bash
+scripts/run_subagent.py --list
+```
+
+Output:
+```json
+{"agents": [{"name": "code-reviewer", "description": "Reviews code..."}], "agents_dir": "/path/.agents"}
+```
+
+**If agents list is empty**:
+1. Create `{cwd}/.agents/` directory
+2. Add agent definition file (see [Agent Definition Format](#agent-definition-format))
+3. Re-run `--list` to verify
+
+### Step 2: Execute Agent
+
+```bash
+scripts/run_subagent.py \
+  --agent <name> \
+  --prompt "<task>" \
+  --cwd <absolute-path>
+```
+
+### Step 3: Handle Response
+
+Parse JSON output and check `status` field:
+
+```json
+{"result": "...", "exit_code": 0, "status": "success", "cli": "claude"}
+```
+
+**By status:**
+
+| status | Meaning | Action |
+|--------|---------|--------|
+| `success` | Task completed | Use `result` directly |
+| `partial` | Timeout but has output | Review partial `result`, may need retry |
+| `error` | Execution failed | Check `error` field and `exit_code`, fix and retry |
+
+**By exit_code** (when status is `error`):
+
+| exit_code | Meaning | Resolution |
+|-----------|---------|------------|
+| 0 | Success | - |
+| 124 | Timeout | Increase `--timeout` or simplify task |
+| 127 | CLI not found | Install required CLI (claude, codex, etc.) |
+| 1 | General error | Check `error` field in response |
+
+## Parameters
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `--list` | - | List available agents (no other params needed) |
+| `--agent` | Yes* | Agent definition name from --list |
+| `--prompt` | Yes* | Task description to delegate |
+| `--cwd` | Yes* | Working directory (absolute path) |
+| `--timeout` | No | Timeout ms (default: 600000) |
+| `--cli` | No | Force CLI: `claude`, `cursor-agent`, `codex`, `gemini` |
+
+*Required when not using --list
+
+## Agent Definition Location
+
+| Priority | Source | Path |
+|----------|--------|------|
+| 1 | Environment variable | `$SUB_AGENTS_DIR` |
+| 2 | Default | `{cwd}/.agents/` |
+
+To customize: `export SUB_AGENTS_DIR=/custom/path`
+
+## Agent Definition Format
+
+Place `.md` files in `.agents/` directory:
+
+```markdown
+---
+run-agent: claude
+---
+
+# Agent Name
+
+Brief description of agent's purpose.
+
+## Task
+What this agent does.
+
+## Output Format
+How results should be structured.
+```
+
+**Critical**: The `run-agent` frontmatter determines which CLI executes the agent. See [cli-formats.md](references/cli-formats.md) for CLI-specific behaviors.
+
+## CLI Selection Priority
+
+1. `--cli` argument (explicit override)
+2. Agent definition `run-agent` frontmatter
+3. Auto-detect caller environment
+4. Default: `codex`
+
+## Common Mistakes
+
+| Mistake | Result | Fix |
+|---------|--------|-----|
+| Skip `--list` before execution | Agent not found error | Always run `--list` first |
+| Use relative path for `--cwd` | Validation fails | Use absolute path |
+| Ignore `status` field in response | Undetected errors | Always check `status` before using `result` |
+| Very long prompts | May exceed CLI limits | Break into smaller tasks |
+````

package/Ai Agent Workflow/powers/sub-agents/SKILL.md

@@ -11,14 +11,14 @@ Spawns external CLI AIs (claude, cursor-agent, codex, gemini) as isolated sub-ag
 ## Resources
 
 - **[run_subagent.py](scripts/run_subagent.py)** - Main execution script
-- **[codex.md](steering/codex.md)** - Codex-specific setup (permissions, timeout)
+- **[codex.md](references/codex.md)** - Codex-specific setup (permissions, timeout)
 
 **Script Path**: Use absolute path `{SKILL_DIR}/scripts/run_subagent.py` where `{SKILL_DIR}` is the directory containing this SKILL.md file.
 
 ## CLI-Specific Notes
 
 Check the corresponding reference for your environment:
-- **Codex**: Read [steering/codex.md](steering/codex.md) BEFORE first execution
+- **Codex**: Read [references/codex.md](references/codex.md) BEFORE first execution
 
 ## Interpreting User Requests
 
@@ -56,13 +56,13 @@ This script executes external CLIs that require elevated permissions.
 1. Request elevated permissions via your CLI's tool parameters
 2. Set tool timeout to match `--timeout` argument (default: 600000ms)
 
-**For Codex CLI** (most common permission issues): See [steering/codex.md](steering/codex.md) for exact JSON parameter format.
+**For Codex CLI** (most common permission issues): See [references/codex.md](references/codex.md) for exact JSON parameter format.
 
 ## Workflow
 
 ### Step 0: Read CLI-Specific Setup (if applicable)
 
-If you are running on Codex, read [steering/codex.md](steering/codex.md) first.
+If you are running on Codex, read [references/codex.md](references/codex.md) first.
 
 ### Step 1: List Available Agents
 
@@ -158,7 +158,7 @@ What this agent does.
 How results should be structured.
 ```
 
-**Critical**: The `run-agent` frontmatter determines which CLI executes the agent. See [cli-formats.md](steering/cli-formats.md) for CLI-specific behaviors.
+**Critical**: The `run-agent` frontmatter determines which CLI executes the agent. See [cli-formats.md](references/cli-formats.md) for CLI-specific behaviors.
 
 ## CLI Selection Priority
 

package/Ai Agent Workflow/powers/systematic-debugging/POWER.md

@@ -1,13 +1,112 @@
+````markdown
 ---
+inclusion: manual
 name: systematic-debugging
 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
+# Systematic Debugging
 
-This is a compatibility power wrapper for the `systematic-debugging` skill.
+> Source: obra/superpowers
 
-Primary source:
-- `Ai Agent Workflow/skills/systematic-debugging/SKILL.md`
+## Overview
+This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.
 
-Use this folder for power-specific extensions when needed.
+## 4-Phase Debugging Process
+
+### Phase 1: Reproduce
+Before fixing, reliably reproduce the issue.
+
+```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%)
+```
+
+### Phase 2: Isolate
+Narrow down the source.
+
+```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?
+```
+
+### 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]
+```
+
+### Phase 4: Fix & Verify
+Fix and verify it's truly fixed.
+
+```markdown
+## Fix Verification
+- [ ] Bug no longer reproduces
+- [ ] Related functionality still works
+- [ ] No new issues introduced
+- [ ] Test added to prevent regression
+```
+
+## 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
+```
+
+## Common Debugging Commands
+
+```bash
+# Recent changes
+git log --oneline -20
+git diff HEAD~5
+
+# Search for pattern
+grep -r "errorPattern" --include="*.ts"
+
+# Check logs
+pm2 logs app-name --err --lines 100
+```
+
+## Anti-Patterns
+
+❌ **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
+````