## Tool Workflow Patterns

### File Editing Lifecycle
1. ALWAYS read a file before editing it. Never edit blind.
2. After editing, read the modified section to verify the change applied correctly.
3. For multi-file changes, prefer apply_patch over multiple edit_file calls.
4. If edit_file fails (no match found), re-read the file — content may have changed since you last read it.
5. When editing, include enough surrounding context in your match string to ensure uniqueness.

### Shell Command Patterns
1. Before running tests, verify the test command exists: check package.json scripts.
2. After starting a server, verify it responds: `curl -s http://localhost:PORT`.
3. Pipe long outputs through tail: `npm test 2>&1 | tail -40`.
4. Set explicit timeouts for potentially long-running commands.
5. Use `set -e` in multi-step shell scripts so failures surface immediately.
6. Capture stderr: `command 2>&1` — many tools print errors to stderr only.

### Test-Fix-Verify Loop
1. Run tests FIRST to understand current state before changing anything.
2. Read the failing test to understand expected behavior.
3. Fix the source code, not the test (unless the test itself is wrong).
4. Re-run tests to confirm the fix works.
5. If still failing, read the FULL error output carefully. Do not just re-run and hope.
6. If a fix breaks other tests, check what those tests expect before proceeding.

### Error Recovery
1. On 1st failure: Read the error message carefully. Fix the obvious issue.
2. On 2nd failure from same tool: Try a different approach — different tool or strategy.
3. On 3rd failure: Stop. Re-read the relevant files. Reconsider your approach entirely.
4. NEVER retry the exact same command with the exact same arguments. That is a doom loop.
5. If a tool consistently fails, switch tools (e.g., edit_file failing? use apply_patch).

### Exploration Before Action
1. Start with glob or list_directory to understand project structure.
2. Read package.json, CLAUDE.md, or README for project conventions.
3. Use grep_files to find related code before making changes.
4. Check git status to see what has already been modified.
5. Look at imports and call sites before changing a function signature.

### Debugging Strategy
1. Reproduce the issue first — run the failing command and capture output.
2. Read the stack trace bottom-to-top to find the originating error.
3. Add targeted logging only if needed; remove it after debugging.
4. Check recent git changes (`git diff`) if something that worked before is now broken.
5. Use lsp_diagnostics to catch type errors and undefined references.

### Multi-File Changes
1. Plan all changes before starting: list which files need modification.
2. Make changes in dependency order — update shared modules before consumers.
3. After all edits, run the full test suite (not just individual tests).
4. If one edit depends on another, verify the first edit before proceeding.
