9f00797925
All checks were successful
Deploy to Staging / Build Images (push) Successful in 23s
Deploy to Staging / Deploy to Staging (push) Successful in 36s
Deploy to Staging / Verify Staging (push) Successful in 6s
Deploy to Staging / Notify Staging Ready (push) Successful in 6s
Deploy to Staging / Notify Staging Failure (push) Has been skipped
47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
# Doc Sync
|
|
|
|
The CLAUDE.md/README.md hierarchy is central to context hygiene. CLAUDE.md files
|
|
are pure indexes -- tabular navigation with "What" and "When to read" columns
|
|
that help LLMs (and humans) find relevant files without loading everything.
|
|
README.md files capture invisible knowledge: architecture decisions, design
|
|
tradeoffs, and invariants that are not apparent from reading code.
|
|
|
|
The doc-sync skill audits and synchronizes this hierarchy across a repository.
|
|
|
|
## How It Works
|
|
|
|
The skill operates in five phases:
|
|
|
|
1. **Discovery** -- Maps all directories, identifies missing or outdated
|
|
CLAUDE.md files
|
|
2. **Audit** -- Checks for drift (files added/removed but not indexed),
|
|
misplaced content (architecture docs in CLAUDE.md instead of README.md)
|
|
3. **Migration** -- Moves architectural content from CLAUDE.md to README.md
|
|
4. **Update** -- Creates/updates indexes with proper tabular format
|
|
5. **Verification** -- Confirms complete coverage and correct structure
|
|
|
|
## When to Use
|
|
|
|
Use this skill for:
|
|
|
|
- **Bootstrapping** -- Adopting this workflow on an existing repository
|
|
- **After bulk changes** -- Major refactors, directory restructuring
|
|
- **Periodic audits** -- Checking for documentation drift
|
|
- **Onboarding** -- Before starting work on an unfamiliar codebase
|
|
|
|
If you use the planning workflow consistently, the technical writer agent
|
|
maintains documentation as part of execution. As such, doc-sync is primarily for
|
|
bootstrapping or recovery -- not routine use.
|
|
|
|
## Example Usage
|
|
|
|
```
|
|
Use your doc-sync skill to synchronize documentation across this repository
|
|
```
|
|
|
|
For targeted updates:
|
|
|
|
```
|
|
Use your doc-sync skill to update documentation in src/validators/
|
|
```
|