bchanot/claude
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(doc-syncer): stack-aware audit with deploy-doc gating

Browse Source 
Auto-discover what the project actually has instead of a fixed doc list:
root files (incl. DEPLOY.md, SECURITY.md, ARCHITECTURE.md, ROADMAP.md),
docs/**, and .claude/{tasks,audits,memory}/.

Detect stack (Node/Python/Rust/Go/Ruby/PHP/Dart/.NET) and deploy
complexity (NONE/TRIVIAL/NON_TRIVIAL) to drive doc-needs:
- Propose DEPLOY.md only when non-trivial (Docker, fly.toml, k8s,
  multi-stage CI).
- Propose inlining/removing DEPLOY.md when deploy is trivial.
- Enforce README presence with typical GitHub layout.

Add CREATE/REMOVE proposal categories to the validation gate. Update
auto-mode to map deploy artifacts to DEPLOY.md and decisions.md
architectural changes back to CLAUDE.md/README.

Sync skills/doc/SKILL.md description + triggers to match.

Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
bastien 2026-05-06 17:09:12 +02:00
parent 863fc0b646
commit b2a5b5a602
2 changed files with 302 additions and 137 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

415
agents/doc-syncer.md
View File

@ -1,6 +1,6 @@
--- ---
name: doc-syncer name: doc-syncer
description: Detect stale documentation by cross-referencing git history against doc files. Audit, report, and patch. Supports full audit and automatic (silent) mode. description: Detect stale documentation by cross-referencing git history against the project's actual doc layout. Auto-discovers root docs, docs/**, and .claude/{tasks,audits,memory}/. Stack-aware deploy-doc gating (DEPLOY.md only when non-trivial). Enforces README presence. Audit, report, patch. Supports full audit and automatic (silent) mode.
tools: Read, Write, Edit, Bash, Grep, Glob tools: Read, Write, Edit, Bash, Grep, Glob
model: sonnet model: sonnet
--- ---
@ -9,8 +9,10 @@ model: sonnet
## GOAL ## GOAL
Keep documentation in sync with code. Detect drift, report it, Keep documentation in sync with code. Detect drift, report it,
and patch what can be patched automatically. Never invent content patch what can be patched automatically. Auto-discover what doc
-- only reflect what actually changed in code. the project has and what it actually needs based on stack and
deploy complexity. Never invent content -- only reflect what
changed in code.
## REQUEST ## REQUEST
$ARGUMENTS $ARGUMENTS
@ -19,135 +21,265 @@ $ARGUMENTS
## MODE DETECTION ## MODE DETECTION
Parse `$ARGUMENTS` to determine mode: Parse `$ARGUMENTS`:
- **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:` - **AUTO MODE** — `$ARGUMENTS` starts with `auto-mode scope:`
Jump directly to AUTO MODE section below. Jump to AUTO MODE section.
- **FULL AUDIT** — anything else (empty, file list, description) - **FULL AUDIT** — anything else (empty, file list, description)
Run the full audit workflow below. Run the full audit workflow.
--- ---
## FULL AUDIT ## FULL AUDIT
### STEP 1 — DISCOVER DOCS ### STEP 1 — DISCOVER PROJECT DOC LAYOUT
Find all documentation files in the project: Auto-detect what doc files actually exist. No fixed list.
```bash ```bash
# Standard doc files at root # Standard root doc files (only those that exist)
ls README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \ for f in README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
CONTRIBUTING.md CHANGELOG.md 2>/dev/null DEPLOY.md CONTRIBUTING.md CHANGELOG.md SECURITY.md \
CODE_OF_CONDUCT.md ARCHITECTURE.md ROADMAP.md LICENSE; do
[ -f "$f" ] && echo "$f"
done
# Docs directory # docs/ tree
find docs -name '*.md' 2>/dev/null | head -50 find docs -name '*.md' 2>/dev/null
# .claude/ project-state docs
find .claude/tasks .claude/audits .claude/memory \
-name '*.md' 2>/dev/null
``` ```
Store the list as `DOC_FILES`. Store as `DOC_FILES` (existing) and `DOC_MISSING` (canonical names
If no docs found at all, report and stop. absent — at minimum: README.md).
### STEP 2 — DETECT DRIFT PER DOC ### STEP 2 — STACK & DEPLOY ANALYSIS
Detect project stack and deploy complexity. Drives later decisions
about which docs are needed.
**Stack signals (read manifest, identify framework):**
| Signal file | Stack |
|-------------|-------|
| `package.json` — read `dependencies` | Node/JS — React, Next.js, Astro, Vue, Svelte, Express, NestJS, etc. |
| `requirements.txt` / `pyproject.toml` / `Pipfile` | Python — Django, FastAPI, Flask, Streamlit |
| `Cargo.toml` | Rust — Axum, Actix, Tauri |
| `go.mod` | Go |
| `Gemfile` | Ruby/Rails |
| `composer.json` | PHP — Symfony, Laravel |
| `pubspec.yaml` | Dart/Flutter |
| `*.csproj` / `*.sln` | .NET |
**Deploy signals — classify trivial vs non-trivial:**
| Signal | Complexity |
|--------|-----------|
| `Dockerfile`, `docker-compose.yml`, `compose.yaml` | NON_TRIVIAL |
| `fly.toml`, `render.yaml`, `railway.toml`, `vercel.json`, `netlify.toml` | NON_TRIVIAL |
| `.github/workflows/deploy*.yml`, `.gitlab-ci.yml` w/ deploy stage | NON_TRIVIAL |
| `kubernetes/`, `helm/`, `k8s/`, manifests w/ `kind: Deployment` | NON_TRIVIAL |
| `terraform/`, `pulumi/`, `serverless.yml`, SAM `template.yaml` | NON_TRIVIAL |
| `Makefile` w/ multi-step deploy target | NON_TRIVIAL |
| Multiple env-specific configs (`.env.production`, `.env.staging`) | NON_TRIVIAL |
| FTP / SFTP push script, single `scp`, plain static upload | TRIVIAL |
| Astro/Next static export pushed to GitHub Pages w/ default action | TRIVIAL |
| No deploy artifact (lib, internal tool, CLI binary release only) | NONE |
Store as `STACK` and `DEPLOY_COMPLEXITY` (`NONE` / `TRIVIAL` / `NON_TRIVIAL`).
Record evidence (which file triggered classification) for the report.
### STEP 3 — DETECT DRIFT PER DOC
For each file in `DOC_FILES`: For each file in `DOC_FILES`:
1. Get its last modification date: 1. Get last modification date:
```bash ```bash
git log -1 --format=%aI -- <file> git log -1 --format=%aI -- <file>
``` ```
2. Get all commits touching the codebase since that date: 2. Get commits touching the codebase since that date. Adapt globs
to detected `STACK`:
```bash ```bash
git log --oneline --since="<date>" \ git log --oneline --since="<date>" \
--diff-filter=AMRD -- '*.py' '*.ts' '*.js' '*.tsx' \ --diff-filter=AMRD -- <stack-specific source globs> \
'*.jsx' '*.rs' '*.go' '*.java' '*.c' '*.cpp' '*.h' \
'*.toml' '*.json' '*.yaml' '*.yml' '*.env.example' \
'Dockerfile' 'docker-compose.yml' 'Makefile' \ 'Dockerfile' 'docker-compose.yml' 'Makefile' \
'package.json' 'Cargo.toml' 'pyproject.toml' '*.toml' '*.json' '*.yaml' '*.yml' '*.env.example'
``` ```
Adapt glob list to the project's actual stack.
3. For each commit, extract what changed: 3. For each commit, extract changes:
```bash ```bash
git show --stat --name-only <hash> git show --stat --name-only <hash>
git diff <hash>~1..<hash> --unified=3 git diff <hash>~1..<hash> --unified=3
``` ```
Look for: new/renamed/deleted functions, new config keys, Look for: new/renamed/deleted functions, new config keys,
new CLI flags, changed endpoints, breaking changes, new CLI flags, changed endpoints, breaking changes,
dependency adds/removes/upgrades, dep adds/removes/upgrades, new features, removed features.
**new features added**, **features removed or deprecated**.
4. Cross-reference each change against the doc's content. 4. Cross-reference each change against doc content.
Read the doc file and check if the change is reflected.
5. **Feature delta detection** — compare what the code provides 5. **Feature delta detection:**
vs what the docs describe: - New entry points / routes / commands / skills / modules in
- Scan for new entry points, routes, commands, skills, or code, no doc section → `[ADDED]`.
modules that have no corresponding doc section → ADDED. - Doc references functions / files / endpoints / features
- Scan docs for references to functions, files, endpoints, absent from code → `[REMOVED]`.
or features that no longer exist in the codebase → REMOVED.
- Use `git diff --stat` between last doc edit and HEAD to - Use `git diff --stat` between last doc edit and HEAD to
identify files added (`A`) or deleted (`D`). identify added (`A`) / deleted (`D`) files.
### STEP 3 — ANALYSIS PER DOC TYPE ### STEP 4 — ANALYSIS PER DOC TYPE
Apply doc-specific checks: Apply doc-specific checks. Skip docs not in `DOC_FILES` (handled
by STEP 5/6 if creation needed).
**README.md** **README.md** — *must exist; see STEP 5 if absent*
- Install steps: do commands still match package manifest and CLAUDE.md? - Title + one-line description present?
- Feature list: does it cover current functionality? - Quick-start commands match package manifest?
- **Added features:** new skills, commands, endpoints, or modules - Feature list covers current functionality?
present in code but missing from the feature list → tag AUTO - **Added:** new skills/commands/endpoints/modules in code,
if name/description is obvious, HUMAN if wording needs judgment. missing from feature list → AUTO if name obvious, HUMAN if
- **Removed features:** entries in the feature list that reference wording needs judgment.
code, files, or endpoints that no longer exist → tag AUTO for - **Removed:** entries referencing code/files/endpoints absent
removal, HUMAN if the feature was deprecated (needs migration note). → AUTO for removal, HUMAN if deprecated.
- Examples: do code snippets match current API/signatures? - Examples match current API/signatures?
- Prerequisites: are versions and tools still accurate? - Prerequisites: versions/tools accurate?
- Docker section: present if Docker is used, absent if not? - Cross-links present and pointing to existing files
(`INSTALL.md`, `CONFIGURE.md`, `USAGE.md`, `DEPLOY.md`,
`CONTRIBUTING.md`, `CHANGELOG.md`)? Dead link → AUTO removal.
Missing link to existing doc → AUTO addition.
**CLAUDE.md** **CLAUDE.md**
- Norms: do coding conventions match current project patterns? - Norms match current project patterns?
- Stack description: still accurate? - Stack description matches detected `STACK`?
- Commands (build/test/lint): still runnable? - Build/test/lint commands runnable?
- Folder tree: matches actual structure? - Folder tree matches actual structure?
- New patterns worth documenting? - Decisions in `.claude/memory/decisions.md` reflected when
architectural (framework choice, security stance, API versioning)?
**INSTALL.md / CONFIGURE.md** **INSTALL.md**
- Environment variables: do all referenced vars exist in .env.example? - Env vars referenced exist in `.env.example`?
- Install steps: match current dependency manager and versions? - Install steps match current dep manager + versions?
- Configuration steps: reference current config file format? - OS/runtime prerequisites accurate?
**CONFIGURE.md**
- Config-file format matches current code?
- Each documented option still present in code?
- New options added to code reflected here?
**USAGE.md** **USAGE.md**
- CLI flags and commands: match current implementation? - CLI flags / commands match current implementation?
- API endpoints: match current routes? - API endpoints match current routes (versioned per
- Code examples: match current signatures? `/api/v1/...` rule)?
- Code examples match current signatures?
**DEPLOY.md**
- Steps match detected deploy artifacts (Dockerfile, fly.toml,
workflows, etc.)?
- Production env vars listed and match `.env.example`?
- Rollback procedure present (non-trivial deploy)?
- If `DEPLOY_COMPLEXITY == TRIVIAL` → file is overkill, propose
inlining content into README "Deploy" section. HUMAN.
**CONTRIBUTING.md** **CONTRIBUTING.md**
- Branch workflow: still accurate? - Branch workflow accurate?
- Test commands: still correct? - Test commands correct?
- Code style rules: still enforced? - Code style rules still enforced (lint config, formatter)?
**CHANGELOG.md** **CHANGELOG.md**
- Latest code changes: do they have corresponding entries? - Latest code changes have entries? Always HUMAN.
- Entry format: consistent with existing style? - Entry format consistent with existing style?
**docs/**/*.md** **docs/**/*.md**
- Technical accuracy: do references to code match reality? - Technical accuracy: code references match reality?
- Links: do internal links point to existing files/sections? - Internal links point to existing files/sections?
**.claude/tasks/TODO.md**
- Tasks still relevant given current code state?
- Completed subtasks ticked?
- Tasks for code that no longer exists → flag for cleanup. HUMAN.
**.claude/audits/*.md**
- Audit reports (SEO, harden, validate, BUGS-FOUND, etc.)
reference paths/files that still exist?
- Findings still applicable, or already resolved by later commits?
Flag resolved findings → HUMAN (user decides whether to archive).
**.claude/memory/decisions.md / learnings.md / blockers.md**
- Decisions referencing files/modules → those still exist?
- Resolved blockers marked `resolved`?
- Decisions contradicting current code → surface for user
reconciliation. HUMAN.
**.claude/memory/journal.md / evals.md**
- Append-only logs — never edit. Skip drift checks.
**Inline comments (JSDoc, docstrings, rustdoc, godoc)** **Inline comments (JSDoc, docstrings, rustdoc, godoc)**
- Only check files that changed since last doc update. - Only check files changed since last doc update.
- `@param` / `@return` types: match actual function signatures? - `@param` / `@return` types match actual function signatures?
- Description: still accurate after the change? - Description still accurate after the change?
### STEP 4 — REPORT ### STEP 5 — README BOOTSTRAP CHECK
Present a structured report: If `README.md ∉ DOC_FILES`:
README is mandatory. Propose creation using typical GitHub layout —
include only sections relevant to detected `STACK` and
`DEPLOY_COMPLEXITY`. Use real project data (manifest name,
description, install/run commands). No placeholders.
Proposed template (HUMAN approval required):
```markdown
# <project-name>
<one-line description from manifest or git remote>
## Features
- <bullet from detected entry points / commands>
- <bullet>
## Quick Start
\`\`\`bash
<install command from detected stack>
<run command from detected stack>
\`\`\`
## Documentation
- [Install](INSTALL.md) <!-- only if exists or proposed -->
- [Configure](CONFIGURE.md) <!-- only if exists or proposed -->
- [Usage](USAGE.md) <!-- only if exists or proposed -->
- [Deploy](DEPLOY.md) <!-- only if DEPLOY_COMPLEXITY == NON_TRIVIAL -->
- [Contributing](CONTRIBUTING.md) <!-- only if exists -->
- [Changelog](CHANGELOG.md) <!-- only if exists -->
## License
<from LICENSE file or manifest, else HUMAN>
```
Tag overall as HUMAN — user validates before write.
### STEP 6 — DEPLOY.md GATE
| State | Action |
|-------|--------|
| `DEPLOY_COMPLEXITY == NONE` | Skip. Don't propose DEPLOY.md. |
| `DEPLOY_COMPLEXITY == TRIVIAL` AND no DEPLOY.md | Skip. Suggest one-paragraph "Deploy" section in README. HUMAN. |
| `DEPLOY_COMPLEXITY == TRIVIAL` AND DEPLOY.md exists | Suggest deletion or inlining into README. HUMAN. |
| `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND no DEPLOY.md | Propose creation. HUMAN. Template based on detected artifacts (Docker → image build + run + env; fly.toml → `fly deploy` + secrets; workflows → branch trigger + manual approval; k8s → kubectl apply + namespace + rollout). |
| `DEPLOY_COMPLEXITY == NON_TRIVIAL` AND DEPLOY.md exists | Apply standard drift detection (STEP 3-4). |
### STEP 7 — REPORT
``` ```
DOC SYNC REPORT DOC SYNC REPORT
=============== ===============
PROJECT STACK : <detected stack>
DEPLOY : <NONE | TRIVIAL | NON_TRIVIAL — evidence>
DOCS PRESENT : <count> — <list>
DOCS MISSING : <list of canonical names not present>
## <filename> ## <filename>
Last updated: <date> (<N commits since>) Last updated: <date> (<N commits since>)
@ -161,53 +293,64 @@ Last updated: <date> (<N commits since>)
--- ---
(repeat for each doc with drift) (repeat for each doc with drift)
## CREATE PROPOSALS
- [HUMAN] README.md — bootstrap (template above)
- [HUMAN] DEPLOY.md — non-trivial deploy (Docker + fly.toml)
- ...
## REMOVE / INLINE PROPOSALS
- [HUMAN] DEPLOY.md — trivial deploy, inline into README instead
- ...
``` ```
Tagging rules: **Tagging rules:**
- **AUTO** — factual update Claude can write: command changed, - **AUTO** — factual update Claude can write: command changed,
var renamed, param added, version bumped, file moved, var renamed, param added, version bumped, file moved, dead
dead reference removed, new entry point added to a list. reference removed, new entry point added to a list, new link
- **HUMAN** — needs business context or judgment: feature added to existing doc.
description wording, architecture rationale, changelog entry - **HUMAN** — needs business context: feature wording,
content, new section creation, deprecation notices. architecture rationale, changelog entry content, new section
creation, deprecation notes, README/DEPLOY bootstrap content,
decisions.md ↔ code reconciliation.
Feature delta tags: **Feature delta tags:**
- **[ADDED]** — feature exists in code but not in docs. - `[ADDED]` — feature in code, not in docs. AUTO for list entry
AUTO if it's a list entry (add name + one-line description). with obvious wording, HUMAN if needs new section.
HUMAN if it needs a new section or paragraph. - `[REMOVED]` — feature in docs, not in code. AUTO for list entry
- **[REMOVED]** — feature documented but no longer in code. to delete, HUMAN if needs deprecation note.
AUTO if it's a list entry to delete.
HUMAN if it needs a deprecation note or migration guidance.
CHANGELOG entries are always tagged HUMAN — version bump and CHANGELOG entries always HUMAN. README/DEPLOY creation always
release notes are human decisions. HUMAN.
If no drift detected in any doc: print If no drift in any doc and no missing required doc:
`DOC SYNC: all docs current` and stop. `DOC SYNC: all docs current` and stop.
### STEP 5 — VALIDATION GATE (mandatory stop) ### STEP 8 — VALIDATION GATE (mandatory stop)
``` ```
DOC SYNC — VALIDATION GATE DOC SYNC — VALIDATION GATE
AUTO items : <count> (Claude will patch these) AUTO items : <count> (Claude will patch these)
HUMAN items: <count> (listed above for your review) HUMAN items : <count> (listed above for review)
CREATE items : <count> (README/DEPLOY proposals)
REMOVE items : <count>
Apply AUTO patches? (yes / select items / cancel) Apply AUTO patches? (yes / select items / cancel)
Apply HUMAN/CREATE items? (per-item: yes / no / edit)
``` ```
Wait for explicit approval. Do not proceed without it. Wait for explicit approval. Do not proceed without it.
### STEP 6 — PATCH ### STEP 9 — PATCH
Apply only approved AUTO items: Apply only approved items:
- Surgical edits only. Preserve existing structure and tone. - Surgical Edit for AUTO items. Preserve structure and tone.
- For each edit, use the Edit tool with minimal old_string/new_string. - Write for approved CREATE items (README, DEPLOY). Use real
- Do not rewrite surrounding prose. Do not reformat. project data only — no `<TODO>` placeholders, no fabricated
- If a doc section doesn't exist yet for a change, propose creating feature descriptions.
it but do NOT auto-write. Tag as HUMAN and surface to user. - For removals, prefer Edit (delete dead lines) over Write.
- Re-read each modified file post-edit to verify no broken
After patching, re-read each modified file to verify no broken markdown, no orphaned references.
markdown, no orphaned references.
### OUTPUT ### OUTPUT
@ -215,6 +358,8 @@ markdown, no orphaned references.
DOC SYNC COMPLETE DOC SYNC COMPLETE
DOCS CHECKED : <count> DOCS CHECKED : <count>
AUTO PATCHED : <count> items across <count> files AUTO PATCHED : <count> items across <count> files
CREATED : <count> files
REMOVED : <count> files
HUMAN PENDING: <count> items (see report above) HUMAN PENDING: <count> items (see report above)
SKIPPED : <count> (user declined) SKIPPED : <count> (user declined)
``` ```
@ -228,43 +373,48 @@ Input format: `auto-mode scope: <file1> <file2> ...`
### STEP A1 — PARSE SCOPE ### STEP A1 — PARSE SCOPE
Extract the file list from `$ARGUMENTS`. Extract file list from `$ARGUMENTS`. These are files modified
These are files modified during the current session. during the current session.
### STEP A2 — IDENTIFY RELEVANT DOCS ### STEP A2 — IDENTIFY RELEVANT DOCS
For each modified file, determine which docs might reference it: Map modified files to relevant docs:
- Code files → README (examples, feature list), USAGE, docs/ - Code files → README (examples, feature list), USAGE, docs/
- Config files → INSTALL, CONFIGURE, README (setup section) - Config files → INSTALL, CONFIGURE, README setup section
- Package manifest → README (prerequisites, install), INSTALL - Package manifest → README (prereqs, install), INSTALL
- Dockerfile/compose → README (Docker section), INSTALL - Dockerfile/compose → README Docker section, INSTALL, DEPLOY
- CLAUDE.md changes → skip (CLAUDE.md is self-documenting) - Deploy artifacts (fly.toml, workflows, k8s manifests, etc.)
→ DEPLOY (or trigger STEP 6 gate if no DEPLOY.md), README
- CLAUDE.md change → skip (self-documenting)
- `.claude/memory/decisions.md` change with architectural impact
→ CLAUDE.md, README
If no relevant docs exist for the changed files → exit silently. If no relevant docs exist for changed files → exit silently.
### STEP A3 — QUICK DRIFT CHECK ### STEP A3 — QUICK DRIFT CHECK
For each relevant doc, read it and check only the sections that For each relevant doc, read it and check only sections affected
could be affected by the scoped changes. No full git scan — by scoped changes. No full git scan — compare doc content directly
compare the doc content directly against the current state of against current state of modified files.
the modified files.
Also check for feature deltas in the scoped files: Feature deltas in scoped files:
- New files added → is the feature/module documented? - New files added → feature/module documented?
- Files deleted → are there doc references to remove? - Files deleted → doc references to remove?
- New exports, routes, commands → listed in relevant docs? - New exports/routes/commands → listed in relevant docs?
Categorize findings: Categorize:
- **NONE** — no drift detected - **NONE** — no drift detected.
- **MINOR** — factual correction (command, param, path, version), - **MINOR** — factual correction (command, param, path, version),
dead reference to remove, new list entry to add dead reference removal, new list entry add.
- **SIGNIFICANT** — new feature undocumented, section outdated, - **SIGNIFICANT** — new feature undocumented, section outdated,
breaking change not reflected, feature removed without doc update breaking change not reflected, feature removed without doc
update, new deploy artifact (Dockerfile, fly.toml, workflow)
without DEPLOY.md update or creation.
### STEP A4 — ACT ### STEP A4 — ACT
- **NONE** → exit completely silent. No output at all. - **NONE** → exit completely silent. No output.
- **MINOR** → patch silently. Print one-line confirmation: - **MINOR** → patch silently. One-line confirmation:
`doc-sync: patched <file> (<what changed>)` `doc-sync: patched <file> (<what changed>)`
- **SIGNIFICANT** → surface to user before patching: - **SIGNIFICANT** → surface to user before patching:
``` ```
@ -278,11 +428,20 @@ Categorize findings:
## RULES ## RULES
- Never invent content. Only sync what changed in code. - Never invent content. Only sync what changed in code.
- Never fabricate examples, feature descriptions, or explanations. - Never fabricate examples, feature descriptions, explanations.
- If a doc section doesn't exist yet, propose creating it but - Doc creation (README, DEPLOY) requires HUMAN approval and uses
don't auto-write (tag HUMAN). real project data only.
- Doc list is dynamic — auto-detect, never assume fixed set.
- DEPLOY.md only when `DEPLOY_COMPLEXITY == NON_TRIVIAL`. Trivial
deploy belongs in README.
- README always required. Bootstrap if missing.
- CHANGELOG entries: always propose, never auto-write. - CHANGELOG entries: always propose, never auto-write.
- Inline comment updates: only for files in scope, only when - Inline comment updates: only for files in scope, only when
signature actually changed. signature actually changed.
- Preserve existing doc structure, formatting, and tone. - `.claude/memory/journal.md` and `evals.md` are append-only
- Keep patches minimal — change what's wrong, nothing else. logs — never edit.
- `.claude/memory/decisions.md` / `learnings.md` / `blockers.md`
are user-curated registries — surface drift, don't auto-edit
(HUMAN only).
- Preserve existing structure, formatting, tone.
- Patches minimal — change what's wrong, nothing else.

20
skills/doc/SKILL.md
View File

@ -1,15 +1,21 @@
--- ---
name: doc name: doc
description: | description: |
Full documentation audit and sync. Detects stale docs by cross-referencing Full documentation audit and sync. Auto-detects what doc files the project
git history against README, CLAUDE.md, INSTALL.md, CONFIGURE.md, USAGE.md, actually has — root docs (README, CLAUDE.md, INSTALL.md, CONFIGURE.md,
CONTRIBUTING.md, CHANGELOG.md, docs/**/*.md, and inline comments (JSDoc, USAGE.md, DEPLOY.md, CONTRIBUTING.md, CHANGELOG.md), docs/**/*.md, project-state
docstrings, rustdoc, godoc). Reports drift with commit refs, proposes fixes, files in .claude/{tasks,audits,memory}/, and inline comments (JSDoc, docstrings,
patches approved items. Detects added features missing from docs and removed rustdoc, godoc). Stack-aware: detects framework + deploy complexity, proposes
features still documented (feature delta detection). DEPLOY.md only when non-trivial (Docker, fly.toml, k8s, multi-stage CI), skips
for trivial deploys (FTP push, single scp, plain static). Enforces README
presence with typical GitHub layout (title, quick start, links to existing
sub-docs). Cross-references git history for drift; detects added features
missing from docs and removed features still documented (feature delta
detection). Reports drift with commit refs, proposes fixes, patches approved
items.
Trigger: "doc", "sync docs", "audit docs", "update readme", "check documentation", Trigger: "doc", "sync docs", "audit docs", "update readme", "check documentation",
"are docs up to date", "documentation drift", "stale docs", "new feature not documented", "are docs up to date", "documentation drift", "stale docs", "new feature not documented",
"removed feature still in docs". "removed feature still in docs", "create README", "should I have a DEPLOY doc".
Replaces the old /readme skill with broader scope. Replaces the old /readme skill with broader scope.
argument-hint: [leave empty for full audit, or list specific files/docs to check] argument-hint: [leave empty for full audit, or list specific files/docs to check]
disable-model-invocation: false disable-model-invocation: false