common-workflows

What this skill does

# Common Workflow Packs

Seven battle-tested workflow packs that mirror the official Claude Code common-workflows guide. Each pack is a complete playbook, not generic advice.

---

## Pack 1: Understand a Codebase

**When:** First time in an unfamiliar repo, onboarding a new project, or before making large changes.

### Start Prompt
```
You are a senior engineer exploring this codebase for the first time.

Phase 1 — Structure mapping:
1. Read CLAUDE.md, README.md, and package.json/pyproject.toml
2. Map the top-level directory structure (2 levels deep)
3. Identify: entry points, main business logic, data layer, API layer, test layer
4. Identify: tech stack, framework version, package manager

Phase 2 — Architecture extraction:
5. Find the 3 most important source files (highest import count or central routing)
6. Read each one and extract: purpose, key abstractions, dependencies
7. Map data flow: where does data enter, transform, and exit?
8. Identify patterns: are there service layers, repositories, DTOs, event buses?

Phase 3 — Output:
9. Write a 1-page architecture summary to .claude/context-snapshot.md with:
   - Tech stack table
   - 3-sentence architecture description
   - Key file map (path → purpose, one line each)
   - Entry points and their routes/triggers
   - Known complexity hotspots (files > 300 lines or deeply nested logic)
```

### Verification Steps
- [ ] Tech stack correctly identified (check package.json/Cargo.toml/pyproject.toml)
- [ ] All entry points found (check for main.ts, index.ts, manage.py, main.go)
- [ ] Architecture snapshot written to `.claude/context-snapshot.md`
- [ ] No assumptions made that weren't verified in code

### Subagent Opportunities
- Delegate framework-specific analysis: spawn a subagent for `src/auth/` while you explore `src/api/`
- Use a Haiku subagent to list imports and build the dependency graph (fast, cheap)
- Use an Opus subagent only for the final architecture synthesis

### Common Failure Modes
- **Over-reading**: reading every file instead of tracing from entry points inward
- **Missing the glue**: forgetting to read middleware, config loaders, and DI containers
- **Stale docs**: trusting README over what's actually in the code

### Completion Checklist
- [ ] `.claude/context-snapshot.md` written
- [ ] Can explain the system in 3 sentences without looking at the code
- [ ] Know where to find: routing, data models, auth, config, tests

---

## Pack 2: Fix a Bug from an Error Trace

**When:** You have a stack trace, error message, or failing test and need to find and fix the root cause.

### Start Prompt
```
You are debugging the following error:

{PASTE ERROR TRACE HERE}

Evidence-based debugging protocol:

Phase 1 — Parse:
1. Extract: error type, message, file, line number, call stack
2. Identify the proximate cause (where it failed) vs. likely root cause (why)

Phase 2 — Locate:
3. Read the file at the error line + 20 lines of context
4. Trace the call stack: read each frame's function to understand data flow
5. Find where the problematic value was created or last mutated

Phase 3 — Hypothesize:
6. Form 2-3 specific hypotheses about root cause
7. For each hypothesis: identify a code path that would produce this error
8. Pick the most likely hypothesis based on evidence

Phase 4 — Fix:
9. Write the minimal fix for the chosen hypothesis
10. Explain why the fix works
11. Identify if there are other call sites with the same bug

Phase 5 — Verify:
12. Run the failing test: {test_cmd}
13. Run the full test suite to check for regressions: {test_cmd}
14. If tests pass: commit with message "fix({scope}): {one-line description}"
```

### Verification Steps
- [ ] Error is reproducible before fix (confirm test fails)
- [ ] Root cause identified (not just symptom masked)
- [ ] Fix is minimal (no unrelated changes in the same commit)
- [ ] Tests pass after fix
- [ ] Other call sites checked for same bug

### Subagent Opportunities
- Use a subagent to search for similar patterns across the codebase: `Grep "same_pattern" --all`
- Delegate test writing to a test-writer subagent after the fix is confirmed

### Common Failure Modes
- **Symptom masking**: adding null checks without finding why null appears
- **Over-engineering**: refactoring instead of fixing
- **Regression**: fixing one thing, breaking another — always run full suite
- **Wrong hypothesis**: jumping to a fix without verifying the hypothesis first

### Completion Checklist
- [ ] Failing test was confirmed before fix
- [ ] Root cause statement written in commit message
- [ ] All tests pass
- [ ] No unrelated changes in the commit

---

## Pack 3: Refactor Safely

**When:** You need to restructure code without changing behavior. Extract a function, rename a module, split a large file, introduce an abstraction.

### Start Prompt
```
You are a refactoring engineer. Goal: {DESCRIBE REFACTOR GOAL}.

Safety protocol:

Phase 1 — Baseline:
1. Identify the exact scope of change (files, functions, types affected)
2. Run the test suite and confirm it passes: {test_cmd}
3. Count the test coverage for the affected code: check coverage report
4. If coverage < 80% for the target code: write missing tests first

Phase 2 — Characterize:
5. List every call site for the code being changed: Grep for function/class name
6. List every import of the modules being changed
7. Identify any reflection, dynamic dispatch, or string-based lookups that might miss a grep

Phase 3 — Refactor (small steps):
8. Make one structural change at a time
9. After each change: compile/typecheck and run affected tests
10. Never have the codebase in a broken state between steps
11. Commit each step separately with message "refactor({scope}): {step description}"

Phase 4 — Verify:
12. Run the full test suite
13. Check that all call sites compile correctly
14. Run linter/formatter on changed files
15. Read the final version: does it actually read better than before?
```

### Verification Steps
- [ ] Full test suite passes before refactor starts
- [ ] Full test suite passes after refactor ends
- [ ] No behavior changes (same inputs → same outputs)
- [ ] All call sites updated (no missed references)
- [ ] Commits are granular (one logical step per commit)

### Subagent Opportunities
- Delegate test writing for uncovered code before refactoring starts
- Use a subagent to find all import sites across a large monorepo

### Common Failure Modes
- **Big bang refactor**: changing too many files at once → hard to debug if tests break
- **Missing call sites**: grepping for the wrong pattern, missing dynamic usages
- **No baseline**: not confirming tests pass before starting
- **Scope creep**: refactoring adjacent code that "looked messy"

### Completion Checklist
- [ ] Tests passed before and after
- [ ] Commits are atomic and descriptive
- [ ] No new TODO comments added (fix or defer explicitly)
- [ ] Code is demonstrably more readable

---

## Pack 4: TDD Implementation

**When:** Building a new feature or fixing a bug with a test-first approach.

### Start Prompt
```
You are implementing {FEATURE DESCRIPTION} using TDD.

Red-Green-Refactor protocol:

Phase 1 — RED (write failing test):
1. Write the smallest possible test that captures the desired behavior
2. Run it: {test_cmd} — confirm it FAILS
3. If it passes without implementation, the test is wrong — fix the test

Phase 2 — GREEN (minimal implementation):
4. Write the simplest code that makes the test pass
5. No gold-plating: no error handling, no edge cases, no abstractions yet
6. Run tests: confirm it PASSES
7. Commit: "test({scope}): add test for {behavior}" + "feat({scope}): minimal implementation"

Phase 3 — REFACTOR:
8. Now improve the implementation: add error handling, extract functions, add types
9. After each change: run tests
10. When satisfied: commit "refactor({scope}): clean up {thing}"

Phase 4 — Edge cases:
11. List 3-5 edge cases: empty input, null, max values, concurrent access, etc.
12. Write a test for each
13. Make each pass w