| name | doc-sync |
| description | Synchronize documentation with the current codebase. Fix drift between docs/prd.md, docs/system-design.md, and actual source code. |
| compatibility | ["claude-code","opencode","github-copilot"] |
| metadata | {"version":"1.0","author":"team"} |
Doc Sync
Synchronize docs/prd.md and docs/system-design.md with the current codebase. Fix drift, add missing items, remove stale references.
When to Run
- After implementing features or refactoring code
- Before starting a new feature cycle
- Periodically to prevent documentation drift
Instructions
Phase 1: Explore Current Codebase
Use the Explore agent to build a complete picture of what is implemented:
- Read all Go source files under
internal/ and root -- note every type, interface, function, field
- Read configuration files (
cmd/config.example.yaml, internal/config/)
- Read all test files to understand tested behavior
- Read all ADR files under
docs/adr/
Capture: type names (exact casing), struct/interface fields (exact types), exported vs unexported visibility, package dependencies, pipeline step ordering, CLI arguments, configuration properties.
Phase 2: Diff Against Documentation
Read docs/prd.md, docs/system-design.md, and docs/documentation.md.
Compare the codebase snapshot against both documents. Identify:
In PRD:
- Features implemented but not documented (missing requirement IDs)
- Features documented but not implemented (stale requirements)
- Configuration properties that changed, were added, or were removed
- CLI arguments that changed
- Behavioral details that drifted (thresholds, defaults, fallback logic)
In System Design:
- Type names that changed (case matters)
- Struct fields that were added, removed, or retyped
- Package structure changes (new packages, moved files, visibility changes)
- Pipeline step ordering drift
- Error handling changes
- Missing or stale type/interface definitions
Phase 3: Update Documents
Apply all fixes. Follow these rules strictly:
Document boundaries (from docs/documentation.md):
- PRD = what the system does. No Go code, function names, type names, channels, goroutines, or implementation constructs.
- System design = how it is built. Type definitions, package structure, pipeline, error handling. No verbatim function implementations.
Writing standards (from CLAUDE.md):
- No prohibited words: "significant", "arguably", "might", "would help", "should result in"
- No "some", "many", "most" without percentages
- No vague adjectives without data
- 70% of sentences under 20 words, max 30 words
- Acronyms defined on first use
- One idea per sentence
Preservation rules:
- Keep existing requirement IDs stable
- Add new IDs at the end of their section
- Never renumber existing IDs (downstream references depend on them)
Phase 4: Validate
Invoke the doc-reviewer agent with this preamble:
You are a read-only reviewer. Inspect files with Read, Glob, and Grep. Only permitted Bash commands: make ci. Do not write code, scripts, or temporary files. Never use system /tmp; use .scratch/tmp/ for any temporary output.
The reviewer validates against docs/documentation.md checklist:
- Structural checks (cross-references, tables, code blocks)
- Cross-document coherence (requirement IDs, config properties, type fields, constants)
- Writing standards (prohibited words, sentence length, acronyms)
- Document boundaries (PRD has no Go code; system-design has no copied source)
Phase 5: Fix Review Issues
Apply fixes for any [AUTOFIX] or [BLOCKED] issues the reviewer found. Re-run the reviewer if changes were substantial. Stop when the reviewer returns APPROVED.
Output
Report a summary of changes made:
- Lines added/removed/changed per document
- New requirement IDs added
- Stale items removed
- Review result (APPROVED or remaining issues)
