Playbook

---
name: commit-messages
description: |
  Commit message standards enforcer. ALWAYS invoke when creating
  git commits. Ensures Conventional Commits format with scope.
---

# Commit Message Standards
 
## Format
<type>(<scope>): <subject>
 
## Rules
- type: feat|fix|docs|style|refactor|perf|test|build|ci|chore
- scope: component or module name
- subject: imperative mood, no period, max 72 chars
- body: wrap at 72 chars, explain WHY not WHAT
 
## Examples
feat(auth): add OAuth2 PKCE flow for mobile clients
fix(api): prevent race condition in batch processor

---
name: debugging
description: |
  Systematic debugging workflow. ALWAYS invoke this skill when
  encountering any bug, test failure, or unexpected behavior.
  Do not propose fixes without using this skill first.
---

# Systematic Debugging
 
## Step 1: Reproduce
- Run the failing test/command. Capture exact error output.
- If you cannot reproduce, STOP and ask for more information.
 
## Step 2: Isolate
- Identify the smallest input that triggers the bug.
- Check git blame: when was the relevant code last changed?
- Read the test that's failing. Understand what it expects.
 
## Step 3: Hypothesize
- List 3 possible root causes ranked by likelihood.
- For each, identify what evidence would confirm or refute it.
 
## Step 4: Verify
- Test ONE hypothesis at a time.
- Add a failing test that captures the bug BEFORE fixing.
 
## Step 5: Fix
- Make the minimal change that fixes the bug.
- Run the full test suite, not just the failing test.
- If the fix touches shared code, check for other callers.

---
name: code-review
description: |
  Structured code review process. Invoke when reviewing PRs,
  completing features, or before merging. Creates a checklist
  and works through it systematically.
---

# Code Review Checklist
 
When invoked, IMMEDIATELY create a TodoWrite checklist with these items,
then work through each one:
 
## Checklist Items
1. Read all changed files (git diff)
2. Check for security issues (secrets, injection, auth)
3. Verify error handling (edge cases, null checks)
4. Assess test coverage (are new paths tested?)
5. Review naming and readability
6. Check performance implications
7. Verify accessibility (if UI changes)
8. Confirm documentation is updated
 
## For each item:
- Mark as PASS, FAIL, or N/A
- If FAIL: explain the issue and suggest a fix
- If uncertain: mark as REVIEW NEEDED
 
## Output
Provide a summary table:
| Check | Status | Notes |
|-------|--------|-------|

---
name: exploring-codebase
description: |
  Deep codebase exploration. Use when asked to understand
  how a system works, find all usages, or map dependencies.
context: fork
allowed-tools: Read,Grep,Glob,Bash(find:*)
---

# Codebase Exploration
 
You are running in an isolated context. Your job is to explore
thoroughly and return a concise summary.
 
## Process
1. Start from $ARGUMENTS (a file, function, or concept)
2. Map all references, callers, and dependencies
3. Identify the data flow and control flow
4. Note any surprising patterns or potential issues
 
## Output Format
Return a structured summary:
- **Entry points:** Where the code is called from
- **Dependencies:** What it depends on
- **Data flow:** How data moves through the system
- **Key files:** The 3-5 most important files to understand
- **Concerns:** Any issues spotted during exploration

<Domain> expert. ALWAYS invoke this skill when the user asks about
<trigger topics>. Do not <alternative action> directly -- use this
skill first.

---
name: fix-issue
description: |
  Fix a GitHub issue by number. ALWAYS invoke when the user
  says "fix issue" or references a GitHub issue number.
---

# Fix GitHub Issue
 
## Target
Fix GitHub issue $ARGUMENTS following our coding standards.
 
## Process
1. Read the issue: `gh issue view $0`
2. Understand the requirements and acceptance criteria
3. Create a branch: `git checkout -b fix/issue-$0`
4. Implement the fix
5. Write tests
6. Create a PR referencing the issue

~/.claude/skills/
├── debugging/
│   └── SKILL.md              # Systematic debugging (personal, all repos)
├── reviewing-code/
│   └── SKILL.md              # General code review checklist
└── writing-commits/
    └── SKILL.md              # Commit message formatting
 
.claude/skills/                # (project repo)
├── deploying-to-staging/
│   ├── SKILL.md              # Team deployment workflow
│   ├── scripts/
│   │   └── deploy.sh
│   └── references/
│       └── runbook.md
├── api-conventions/
│   ├── SKILL.md              # Endpoint patterns for this project
│   └── assets/
│       └── route.template.ts
└── running-e2e-tests/
    └── SKILL.md              # E2E test runner with environment setup