update-rules

• [Installation](#installation)
• [Quick Start](#quick-start)
• [The Philosophy](#the-philosophy)
• [Commands](#commands)

- [/worktrees](#worktrees---parallel-work-sessions)

- [/plan-review](#plan-review---staff-engineer-review)

- [/update-rules](#update-rules---claudemd-maintenance)

- [/techdebt](#techdebt---find-and-kill-technical-debt)

- [/fix](#fix---auto-bug-fixing)

- [/grill](#grill---pre-pr-challenge)

- [/elegant](#elegant---scrap-and-do-it-right)

- [/explain](#explain---visual-learning)

- [/subagents](#subagents---parallel-compute)

• [Power Prompts](#power-prompts)
• [Workflows](#workflows)
• [File Structure](#file-structure)
• [Credits](#credits)

---

Personal Installation (All Your Projects)

```bash

cp -r runbook ~/.claude/skills/

```

Project Installation (Single Project)

```bash

mkdir -p .claude/skills

cp -r runbook .claude/skills/

```

Verify Installation

```bash

claude

> /runbook

```

You should see the skill overview with all available commands.

---

```bash

# See all commands

/runbook

# Set up 3 parallel worktrees

/worktrees setup 3

# After Claude makes a mistake and you correct it

/update-rules

# End of session cleanup

/techdebt

# Before submitting a PR

/grill

# Paste a bug report, then:

/fix

```

---

The Claude Code team works differently than most users. Their core principles:

1. Parallelize Everything

Don't wait for one Claude to finish. Run 3-5 Claude sessions simultaneously in separate git worktrees. This is their #1 productivity tip.

2. Plan First, Code Once

Pour energy into the plan. A good plan lets Claude one-shot the implementation. When things go sideways, don't push through—go back to planning.

3. Compound Learning

Every mistake is an opportunity. Update CLAUDE.md after every correction. Over time, Claude gets better at your codebase, your patterns, your preferences.

4. Delegate Fully

Don't micromanage Claude. Say "fix" not "first look at file X, then check Y, then..." Trust Claude to figure out the how.

5. Challenge Before Shipping

Get grilled on your changes before they reach real reviewers. Prove your code works. Catch issues early.

6. Clean Up Daily

Run /techdebt at the end of every session. Prevent debt from accumulating. Keep the codebase healthy.

---

`/worktrees` - Parallel Work Sessions

What it does: Creates multiple copies of your codebase (git worktrees) so you can run separate Claude sessions simultaneously.

Why it matters: This is the single biggest productivity unlock according to the Claude Code team. While Claude works on Task A in one terminal, you start Task B in another. No waiting.

Usage:

```bash

/worktrees setup 3 # Create 3 worktrees

/worktrees list # Show existing worktrees

/worktrees remove # Clean up worktrees

/worktrees aliases # Generate shell aliases

```

How it works:

```

Terminal 1 (za): Claude writing tests

Terminal 2 (zb): Claude refactoring auth

Terminal 3 (zc): You investigating a bug with Claude

```

The skill creates worktrees at .claude/worktrees/wt-a, wt-b, wt-c and suggests shell aliases (za, zb, zc) for one-keystroke navigation.

Pro tips:

• Name worktrees by task: wt-auth, wt-api, wt-frontend
• Keep a dedicated "analysis" worktree for logs and investigation
• Color-code your terminal tabs for visual distinction
• Use system notifications to know when a Claude needs input

---

`/plan-review` - Staff Engineer Review

What it does: Reviews your implementation plan as a senior staff engineer would—critically examining it for flaws, edge cases, and better alternatives.

Why it matters: Catching problems in the plan is 10x cheaper than catching them in code. The Claude Code team has one Claude write the plan, then a second Claude review it.

Usage:

```bash

/plan-review # Review plan from recent context

/plan-review plan.md # Review specific plan file

```

The review process:

1. Claude reads your plan
2. Evaluates: correctness, architecture, risks, implementation quality
3. Asks probing questions: "What happens if X?" "Why not Y?"
4. Gives verdict: APPROVE, NEEDS REVISION, or MAJOR CONCERNS

Example output:

```markdown

Overall Assessment: NEEDS REVISION

Strengths

• Clean separation of concerns
• Good test coverage plan

Concerns

1. Race condition possible in token refresh - add mutex
2. No rollback strategy if migration fails

Questions to Resolve

• What happens with concurrent requests during deployment?

Recommendation

Address the race condition before implementing.

```

The pattern:

1. Write plan (or have Claude write it)
2. /plan-review to critique it
3. Revise based on feedback
4. Implement with confidence

---

`/update-rules` - CLAUDE.md Maintenance

What it does: After Claude makes a mistake and you correct it, this adds a rule to CLAUDE.md so the mistake never happens again.

Why it matters: Claude is "eerily good at writing rules for itself." Your CLAUDE.md becomes a knowledge base that compounds over time. The team says to do this after every correction.

Usage:

```bash

/update-rules # Analyze recent corrections

/update-rules "we use tabs not spaces" # Add specific lesson

```

Example flow:

```

You: "No, we use tokens not sessions here"

Claude: [fixes code]

You: /update-rules

Claude adds to CLAUDE.md:

• Use JWT tokens, not session-based auth
• Access tokens in Authorization header
• Refresh tokens in httpOnly cookies

```

What makes a good rule:

• Specific: Not "be careful with X" but "always do Y when X"
• Contextual: Includes when the rule applies
• Actionable: Clear what to do, not just what to avoid

Advanced pattern: Maintain a notes directory for each project:

```

.claude/

├── CLAUDE.md # Points to notes

└── notes/

├── auth-refactor.md

├── api-v2.md

└── performance-fixes.md

```

---

`/techdebt` - Find and Kill Technical Debt

What it does: Scans your codebase for duplicated code, dead code, code smells, and other technical debt. Run at the end of every session.

Why it matters: Debt accumulates silently. The Claude Code team built this as a daily habit—find and kill debt before it compounds.

Usage:

```bash

/techdebt # Scan recent changes

/techdebt src/ # Scan specific directory

```

What it finds:

| Category | Examples |

|----------|----------|

| Duplication | Copy-pasted functions, repeated logic blocks, similar components |

| Dead code | Unused exports, commented-out code, functions never called |

| Code smells | Functions >50 lines, files >500 lines, deep nesting, magic numbers |

| Stale TODOs | TODO/FIXME comments older than 30 days |

Example output:

```markdown

Duplication Found

| Pattern | Occurrences | Suggested Fix |

|---------|-------------|---------------|

| Error formatting | 4 files | Extract to formatError() |

| User validation | 3 files | Create shared validateUser() |

Dead Code

• src/utils/legacy.ts - entire file unused

Quick Wins

1. Remove legacy.ts (0 impact)
2. Extract error formatting (removes 60 lines of duplication)

Want me to tackle the quick wins?

```

---

`/fix` - Auto Bug Fixing

What it does: Paste a bug report, error log, or Slack thread, then say "fix." Claude figures out the rest—finds the code, identifies the root cause, implements the fix, adds tests.

**Why