feat(doc-syncer): stack-aware audit with deploy-doc gating
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
parent
863fc0b646
commit
b2a5b5a602
@ -1,6 +1,6 @@
|
||||
---
|
||||
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
|
||||
model: sonnet
|
||||
---
|
||||
@ -9,8 +9,10 @@ model: sonnet
|
||||
|
||||
## GOAL
|
||||
Keep documentation in sync with code. Detect drift, report it,
|
||||
and patch what can be patched automatically. Never invent content
|
||||
-- only reflect what actually changed in code.
|
||||
patch what can be patched automatically. Auto-discover what doc
|
||||
the project has and what it actually needs based on stack and
|
||||
deploy complexity. Never invent content -- only reflect what
|
||||
changed in code.
|
||||
|
||||
## REQUEST
|
||||
$ARGUMENTS
|
||||
@ -19,135 +21,265 @@ $ARGUMENTS
|
||||
|
||||
## MODE DETECTION
|
||||
|
||||
Parse `$ARGUMENTS` to determine mode:
|
||||
Parse `$ARGUMENTS`:
|
||||
|
||||
- **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)
|
||||
Run the full audit workflow below.
|
||||
Run the full audit workflow.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
# Standard doc files at root
|
||||
ls README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
|
||||
CONTRIBUTING.md CHANGELOG.md 2>/dev/null
|
||||
# Standard root doc files (only those that exist)
|
||||
for f in README.md CLAUDE.md INSTALL.md CONFIGURE.md USAGE.md \
|
||||
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
|
||||
find docs -name '*.md' 2>/dev/null | head -50
|
||||
# docs/ tree
|
||||
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`.
|
||||
If no docs found at all, report and stop.
|
||||
Store as `DOC_FILES` (existing) and `DOC_MISSING` (canonical names
|
||||
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`:
|
||||
|
||||
1. Get its last modification date:
|
||||
1. Get last modification date:
|
||||
```bash
|
||||
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
|
||||
git log --oneline --since="<date>" \
|
||||
--diff-filter=AMRD -- '*.py' '*.ts' '*.js' '*.tsx' \
|
||||
'*.jsx' '*.rs' '*.go' '*.java' '*.c' '*.cpp' '*.h' \
|
||||
'*.toml' '*.json' '*.yaml' '*.yml' '*.env.example' \
|
||||
--diff-filter=AMRD -- <stack-specific source globs> \
|
||||
'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
|
||||
git show --stat --name-only <hash>
|
||||
git diff <hash>~1..<hash> --unified=3
|
||||
```
|
||||
Look for: new/renamed/deleted functions, new config keys,
|
||||
new CLI flags, changed endpoints, breaking changes,
|
||||
dependency adds/removes/upgrades,
|
||||
**new features added**, **features removed or deprecated**.
|
||||
dep adds/removes/upgrades, new features, removed features.
|
||||
|
||||
4. Cross-reference each change against the doc's content.
|
||||
Read the doc file and check if the change is reflected.
|
||||
4. Cross-reference each change against doc content.
|
||||
|
||||
5. **Feature delta detection** — compare what the code provides
|
||||
vs what the docs describe:
|
||||
- Scan for new entry points, routes, commands, skills, or
|
||||
modules that have no corresponding doc section → ADDED.
|
||||
- Scan docs for references to functions, files, endpoints,
|
||||
or features that no longer exist in the codebase → REMOVED.
|
||||
5. **Feature delta detection:**
|
||||
- New entry points / routes / commands / skills / modules in
|
||||
code, no doc section → `[ADDED]`.
|
||||
- Doc references functions / files / endpoints / features
|
||||
absent from code → `[REMOVED]`.
|
||||
- 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**
|
||||
- Install steps: do commands still match package manifest and CLAUDE.md?
|
||||
- Feature list: does it cover current functionality?
|
||||
- **Added features:** new skills, commands, endpoints, or modules
|
||||
present in code but missing from the feature list → tag AUTO
|
||||
if name/description is obvious, HUMAN if wording needs judgment.
|
||||
- **Removed features:** entries in the feature list that reference
|
||||
code, files, or endpoints that no longer exist → tag AUTO for
|
||||
removal, HUMAN if the feature was deprecated (needs migration note).
|
||||
- Examples: do code snippets match current API/signatures?
|
||||
- Prerequisites: are versions and tools still accurate?
|
||||
- Docker section: present if Docker is used, absent if not?
|
||||
**README.md** — *must exist; see STEP 5 if absent*
|
||||
- Title + one-line description present?
|
||||
- Quick-start commands match package manifest?
|
||||
- Feature list covers current functionality?
|
||||
- **Added:** new skills/commands/endpoints/modules in code,
|
||||
missing from feature list → AUTO if name obvious, HUMAN if
|
||||
wording needs judgment.
|
||||
- **Removed:** entries referencing code/files/endpoints absent
|
||||
→ AUTO for removal, HUMAN if deprecated.
|
||||
- Examples match current API/signatures?
|
||||
- Prerequisites: versions/tools accurate?
|
||||
- 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**
|
||||
- Norms: do coding conventions match current project patterns?
|
||||
- Stack description: still accurate?
|
||||
- Commands (build/test/lint): still runnable?
|
||||
- Folder tree: matches actual structure?
|
||||
- New patterns worth documenting?
|
||||
- Norms match current project patterns?
|
||||
- Stack description matches detected `STACK`?
|
||||
- Build/test/lint commands runnable?
|
||||
- Folder tree matches actual structure?
|
||||
- Decisions in `.claude/memory/decisions.md` reflected when
|
||||
architectural (framework choice, security stance, API versioning)?
|
||||
|
||||
**INSTALL.md / CONFIGURE.md**
|
||||
- Environment variables: do all referenced vars exist in .env.example?
|
||||
- Install steps: match current dependency manager and versions?
|
||||
- Configuration steps: reference current config file format?
|
||||
**INSTALL.md**
|
||||
- Env vars referenced exist in `.env.example`?
|
||||
- Install steps match current dep manager + versions?
|
||||
- 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**
|
||||
- CLI flags and commands: match current implementation?
|
||||
- API endpoints: match current routes?
|
||||
- Code examples: match current signatures?
|
||||
- CLI flags / commands match current implementation?
|
||||
- API endpoints match current routes (versioned per
|
||||
`/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**
|
||||
- Branch workflow: still accurate?
|
||||
- Test commands: still correct?
|
||||
- Code style rules: still enforced?
|
||||
- Branch workflow accurate?
|
||||
- Test commands correct?
|
||||
- Code style rules still enforced (lint config, formatter)?
|
||||
|
||||
**CHANGELOG.md**
|
||||
- Latest code changes: do they have corresponding entries?
|
||||
- Entry format: consistent with existing style?
|
||||
- Latest code changes have entries? Always HUMAN.
|
||||
- Entry format consistent with existing style?
|
||||
|
||||
**docs/**/*.md**
|
||||
- Technical accuracy: do references to code match reality?
|
||||
- Links: do internal links point to existing files/sections?
|
||||
- Technical accuracy: code references match reality?
|
||||
- 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)**
|
||||
- Only check files that changed since last doc update.
|
||||
- `@param` / `@return` types: match actual function signatures?
|
||||
- Description: still accurate after the change?
|
||||
- Only check files changed since last doc update.
|
||||
- `@param` / `@return` types match actual function signatures?
|
||||
- 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
|
||||
===============
|
||||
|
||||
PROJECT STACK : <detected stack>
|
||||
DEPLOY : <NONE | TRIVIAL | NON_TRIVIAL — evidence>
|
||||
DOCS PRESENT : <count> — <list>
|
||||
DOCS MISSING : <list of canonical names not present>
|
||||
|
||||
## <filename>
|
||||
Last updated: <date> (<N commits since>)
|
||||
|
||||
@ -161,53 +293,64 @@ Last updated: <date> (<N commits since>)
|
||||
|
||||
---
|
||||
(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,
|
||||
var renamed, param added, version bumped, file moved,
|
||||
dead reference removed, new entry point added to a list.
|
||||
- **HUMAN** — needs business context or judgment: feature
|
||||
description wording, architecture rationale, changelog entry
|
||||
content, new section creation, deprecation notices.
|
||||
var renamed, param added, version bumped, file moved, dead
|
||||
reference removed, new entry point added to a list, new link
|
||||
added to existing doc.
|
||||
- **HUMAN** — needs business context: feature wording,
|
||||
architecture rationale, changelog entry content, new section
|
||||
creation, deprecation notes, README/DEPLOY bootstrap content,
|
||||
decisions.md ↔ code reconciliation.
|
||||
|
||||
Feature delta tags:
|
||||
- **[ADDED]** — feature exists in code but not in docs.
|
||||
AUTO if it's a list entry (add name + one-line description).
|
||||
HUMAN if it needs a new section or paragraph.
|
||||
- **[REMOVED]** — feature documented but no longer in code.
|
||||
AUTO if it's a list entry to delete.
|
||||
HUMAN if it needs a deprecation note or migration guidance.
|
||||
**Feature delta tags:**
|
||||
- `[ADDED]` — feature in code, not in docs. AUTO for list entry
|
||||
with obvious wording, HUMAN if needs new section.
|
||||
- `[REMOVED]` — feature in docs, not in code. AUTO for list entry
|
||||
to delete, HUMAN if needs deprecation note.
|
||||
|
||||
CHANGELOG entries are always tagged HUMAN — version bump and
|
||||
release notes are human decisions.
|
||||
CHANGELOG entries always HUMAN. README/DEPLOY creation always
|
||||
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.
|
||||
|
||||
### STEP 5 — VALIDATION GATE (mandatory stop)
|
||||
### STEP 8 — VALIDATION GATE (mandatory stop)
|
||||
|
||||
```
|
||||
DOC SYNC — VALIDATION GATE
|
||||
AUTO items : <count> (Claude will patch these)
|
||||
HUMAN items: <count> (listed above for your review)
|
||||
AUTO items : <count> (Claude will patch these)
|
||||
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.
|
||||
|
||||
### STEP 6 — PATCH
|
||||
### STEP 9 — PATCH
|
||||
|
||||
Apply only approved AUTO items:
|
||||
- Surgical edits only. Preserve existing structure and tone.
|
||||
- For each edit, use the Edit tool with minimal old_string/new_string.
|
||||
- Do not rewrite surrounding prose. Do not reformat.
|
||||
- If a doc section doesn't exist yet for a change, propose creating
|
||||
it but do NOT auto-write. Tag as HUMAN and surface to user.
|
||||
|
||||
After patching, re-read each modified file to verify no broken
|
||||
markdown, no orphaned references.
|
||||
Apply only approved items:
|
||||
- Surgical Edit for AUTO items. Preserve structure and tone.
|
||||
- Write for approved CREATE items (README, DEPLOY). Use real
|
||||
project data only — no `<TODO>` placeholders, no fabricated
|
||||
feature descriptions.
|
||||
- For removals, prefer Edit (delete dead lines) over Write.
|
||||
- Re-read each modified file post-edit to verify no broken
|
||||
markdown, no orphaned references.
|
||||
|
||||
### OUTPUT
|
||||
|
||||
@ -215,6 +358,8 @@ markdown, no orphaned references.
|
||||
DOC SYNC COMPLETE
|
||||
DOCS CHECKED : <count>
|
||||
AUTO PATCHED : <count> items across <count> files
|
||||
CREATED : <count> files
|
||||
REMOVED : <count> files
|
||||
HUMAN PENDING: <count> items (see report above)
|
||||
SKIPPED : <count> (user declined)
|
||||
```
|
||||
@ -228,43 +373,48 @@ Input format: `auto-mode scope: <file1> <file2> ...`
|
||||
|
||||
### STEP A1 — PARSE SCOPE
|
||||
|
||||
Extract the file list from `$ARGUMENTS`.
|
||||
These are files modified during the current session.
|
||||
Extract file list from `$ARGUMENTS`. These are files modified
|
||||
during the current session.
|
||||
|
||||
### 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/
|
||||
- Config files → INSTALL, CONFIGURE, README (setup section)
|
||||
- Package manifest → README (prerequisites, install), INSTALL
|
||||
- Dockerfile/compose → README (Docker section), INSTALL
|
||||
- CLAUDE.md changes → skip (CLAUDE.md is self-documenting)
|
||||
- Config files → INSTALL, CONFIGURE, README setup section
|
||||
- Package manifest → README (prereqs, install), INSTALL
|
||||
- Dockerfile/compose → README Docker section, INSTALL, DEPLOY
|
||||
- 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
|
||||
|
||||
For each relevant doc, read it and check only the sections that
|
||||
could be affected by the scoped changes. No full git scan —
|
||||
compare the doc content directly against the current state of
|
||||
the modified files.
|
||||
For each relevant doc, read it and check only sections affected
|
||||
by scoped changes. No full git scan — compare doc content directly
|
||||
against current state of modified files.
|
||||
|
||||
Also check for feature deltas in the scoped files:
|
||||
- New files added → is the feature/module documented?
|
||||
- Files deleted → are there doc references to remove?
|
||||
- New exports, routes, commands → listed in relevant docs?
|
||||
Feature deltas in scoped files:
|
||||
- New files added → feature/module documented?
|
||||
- Files deleted → doc references to remove?
|
||||
- New exports/routes/commands → listed in relevant docs?
|
||||
|
||||
Categorize findings:
|
||||
- **NONE** — no drift detected
|
||||
Categorize:
|
||||
- **NONE** — no drift detected.
|
||||
- **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,
|
||||
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
|
||||
|
||||
- **NONE** → exit completely silent. No output at all.
|
||||
- **MINOR** → patch silently. Print one-line confirmation:
|
||||
- **NONE** → exit completely silent. No output.
|
||||
- **MINOR** → patch silently. One-line confirmation:
|
||||
`doc-sync: patched <file> (<what changed>)`
|
||||
- **SIGNIFICANT** → surface to user before patching:
|
||||
```
|
||||
@ -278,11 +428,20 @@ Categorize findings:
|
||||
|
||||
## RULES
|
||||
- Never invent content. Only sync what changed in code.
|
||||
- Never fabricate examples, feature descriptions, or explanations.
|
||||
- If a doc section doesn't exist yet, propose creating it but
|
||||
don't auto-write (tag HUMAN).
|
||||
- Never fabricate examples, feature descriptions, explanations.
|
||||
- Doc creation (README, DEPLOY) requires HUMAN approval and uses
|
||||
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.
|
||||
- Inline comment updates: only for files in scope, only when
|
||||
signature actually changed.
|
||||
- Preserve existing doc structure, formatting, and tone.
|
||||
- Keep patches minimal — change what's wrong, nothing else.
|
||||
- `.claude/memory/journal.md` and `evals.md` are append-only
|
||||
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.
|
||||
|
||||
@ -1,15 +1,21 @@
|
||||
---
|
||||
name: doc
|
||||
description: |
|
||||
Full documentation audit and sync. Detects stale docs by cross-referencing
|
||||
git history against README, CLAUDE.md, INSTALL.md, CONFIGURE.md, USAGE.md,
|
||||
CONTRIBUTING.md, CHANGELOG.md, docs/**/*.md, and inline comments (JSDoc,
|
||||
docstrings, rustdoc, godoc). Reports drift with commit refs, proposes fixes,
|
||||
patches approved items. Detects added features missing from docs and removed
|
||||
features still documented (feature delta detection).
|
||||
Full documentation audit and sync. Auto-detects what doc files the project
|
||||
actually has — root docs (README, CLAUDE.md, INSTALL.md, CONFIGURE.md,
|
||||
USAGE.md, DEPLOY.md, CONTRIBUTING.md, CHANGELOG.md), docs/**/*.md, project-state
|
||||
files in .claude/{tasks,audits,memory}/, and inline comments (JSDoc, docstrings,
|
||||
rustdoc, godoc). Stack-aware: detects framework + deploy complexity, proposes
|
||||
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",
|
||||
"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.
|
||||
argument-hint: [leave empty for full audit, or list specific files/docs to check]
|
||||
disable-model-invocation: false
|
||||
|
||||
Loading…
Reference in New Issue
Block a user