update-claude-docs

What this skill does

# CLAUDE.md Updater

Synchronize CLAUDE.md files based on staged git changes, capturing conventions and gotchas
that Claude cannot infer by reading code.

## When to Activate

- After significant code changes that reveal non-obvious patterns or constraints
- User requests a documentation sync or CLAUDE.md update
- Staged changes include new commands, env vars, or architectural decisions
- A new gotcha or non-obvious behavior has been introduced

## Content Model

CLAUDE.md files should contain **conventions, gotchas, and team preferences** — not
structural inventory. The guiding question for each potential entry is: **"Would removing
this cause Claude to make a mistake?"** If not, omit it.

**Include:**

- Non-obvious bash commands (env vars required, non-standard behavior, ordering constraints)
- Code style rules that differ from language defaults
- Testing instructions and non-standard runner configuration
- Repository etiquette (branch naming, PR conventions)
- Architectural decisions specific to this project
- Developer environment quirks (required env vars, local service dependencies)
- Common gotchas — behaviors that regularly surprise contributors

**Exclude:**

- File-by-file directory listings (Claude can use `git ls-files`)
- Dependency version tables (Claude can read package.json)
- Standard language or framework conventions Claude already knows
- `[TODO]` placeholder entries
- Structural overviews Claude can derive from code

## Quick Process

1. **Check Git**: Verify in git repository; determine interactive vs. automated mode
2. **Get Staged Files**: `git diff --cached --name-status`
3. **Group by CLAUDE.md**: Find nearest CLAUDE.md ancestor for each staged file
4. **Analyze Changes**: Ask "what does this change reveal that is non-obvious?"
5. **Deduplication Check**: Verify proposed content is not already in ancestor CLAUDE.md files
6. **Propose `.claude/rules/` Factoring**: Suggest a rules file if topic warrants it
7. **Show Summary**: Preview proposed additions (interactive mode only)
8. **Apply Updates**: Write changes after confirmation (or conservatively in automated mode)

## Update Triggers

An update is warranted when:

- A new non-obvious convention or pattern is introduced
- A new command, env var, or setup step is added that is not self-evident
- An existing documented behavior changes in a surprising way
- A new package with cross-cutting concerns is added
- Significant architectural changes (>50 lines) that introduce non-obvious constraints

Skip updates for: formatting changes, typos, renames with no behavior change, or anything
that is standard language/framework convention.

## Output Targets

- **CLAUDE.md files**: Primary output — update nearest ancestor CLAUDE.md for each change
- **`.claude/rules/<topic>.md` files**: Secondary output — when a topic-specific rule is
  identified that would push CLAUDE.md over 200 lines or only applies to a file subset,
  propose factoring it into a rules file with optional `paths` frontmatter

## Length Constraint

Target: **under 200 lines per CLAUDE.md**. If an update would push a file over 200 lines,
propose factoring detailed content into a `.claude/rules/<topic>.md` file instead.

## Automated Mode (Non-Interactive)

When running without a human present (e.g., via a pre-commit hook):

- Only append content that is clearly missing and high-value
- Prefer a no-op over a low-quality update
- Do not ask questions or prompt for confirmation
- Log what was added (or that no update was made)

## Safety

- Git provides rollback (`git restore CLAUDE.md`)
- Single confirmation prompt in interactive mode
- Review with `git diff **/*CLAUDE.md` before committing
- Outdated entries may be pruned when a significant update is made

## Best Practices

1. Stage changes first (`git add`)
2. Review updates (`git diff **/*CLAUDE.md`)
3. Commit CLAUDE.md changes together with related code
4. Treat CLAUDE.md as a living document — prune outdated entries over time