docs-sync

name	docs-sync
description	Detect and update out-of-sync documentation when closing an epic or feature
version	2.0.0
compat	claude-code, codex, cursor, openclaw
fill	file-patterns

Skill: Docs Sync (Generic Template)

Detect which documentation has become out of sync with the changes in the current epic/feature and update it without asking for confirmation.

When to use it

• Mandatory when closing each epic or major feature.
• Usually performed after final audits (security, linting) and before the final closure commit.
• Do not use for individual small PRs unless they significantly impact core documentation — the batch context of an epic is where this skill shines.

Process

1. Diff Collection

List all files touched in the epic/feature:

git diff main...HEAD --name-only

2. Mapping & Discovery (Self-Referential)

If this is the first time running in this repo or the mapping table below contains placeholders:

1. Scan the repository structure (e.g., ls -R or check .knowledge/ folder).
2. Identify the core modules and their corresponding documentation files.
3. Update this SKILL.md file to replace the generic placeholders in the table below with the actual project mappings. This ensures future runs are faster and more accurate.

Touched Files/Patterns	Potential Out-of-Sync Docs
{{FILL: pattern_1}}	{{FILL: doc_1}}
{{FILL: pattern_2}}	{{FILL: doc_2}}
CLAUDE.md	Ensure skills and workflows reflect architectural changes
Any file in the epic	AGENT_TASKS.md or ROADMAP.md — mark tasks as completed
Config/Setup changes	README.md — for onboarding and local environment setup
Architectural decisions	.knowledge/decisions/*.md

3. Read and Contrast

For each candidate document:

1. Read the entire current document.
2. Read the diff of the related files.
3. Determine if there's anything in the doc that is no longer true, or something in the code that the doc should mention but doesn't.

4. Verdict per Document

For each candidate doc, issue one of these verdicts:

• SYNC — The doc is out of sync; update it now.
• OK — The doc correctly reflects the current state of the code.

5. Immediate Action

• If the verdict is SYNC: Edit the document directly without presenting a plan or asking for permission.
• If the verdict is OK: Do nothing for that document.

Rules

• Self-Configuration: If the mapping table is empty or generic (REPLACE_ME), the agent MUST populate it by analyzing the repository structure before proceeding with the sync.
• Direct Action: Do not present plans or ask for approval — the verdict is the action.
• Surgical Edits: Do not rewrite sections that haven't changed. Edit only the out-of-sync parts.
• Creation: If a document doesn't exist but should (e.g., a new core module was added), create it.
• Contradictions: If code contradicts a critical rule in CLAUDE.md, report it explicitly before proceeding.

Final Output

## Docs Sync — [Epic/Feature Name]

### Analyzed Docs
- `.knowledge/feature-a.md` → OK
- `.knowledge/schema.md` → SYNC ✏️ (updated: "users" table — new field `is_active`)
- `.knowledge/decisions/005-caching.md` → SYNC ✏️ (updated: TTL changed from 60s to 300s)

### Missing Documentation Gaps
- `src/experimental/new-tool.md` — no doc covers this module (consider creating `.knowledge/experimental-tools.md`)

### Global Verdict
DOCS UP TO DATE / GAPS IDENTIFIED