DocSync.md

DocSync — Shared Documentation Synchronization Procedure

This is a shared context file used by both the Retrospective and SyncDocs workflows. It defines the thorough documentation audit and update procedure.

Goal

After this procedure completes, a developer or AI agent can understand the entire project from /docs alone. Documentation must describe current reality, not aspirational state.

Step 1: Discovery

1. Scan the codebase — Use Glob and Grep to identify current structure, entry points, key modules, and patterns
2. Inventory existing docs — List all files in /docs (or project doc location) with their apparent purpose
3. Cross-reference — Compare documented state vs. actual implementation

Step 2: Gap Analysis

For each documentation file, assess:

Status	Action
Accurate	Keep as-is
Partially outdated	Update with current reality
Completely obsolete	Archive to /docs/archive/ or delete
Missing coverage	Create new documentation
Contradictory	Resolve conflicts, update to single truth

Step 3: Update Execution

Apply changes following this priority order:

1. Architecture & Overview — Project purpose, high-level structure, key decisions
2. Setup & Development — Environment, dependencies, build, test, deploy
3. API & Integration — Endpoints, interfaces, external dependencies
4. Patterns & Conventions — Code style, naming, common patterns in this codebase
5. Troubleshooting — Known issues, debugging tips, gotchas

Step 4: Cleanup

1. Archive obsolete docs to /docs/archive/ with a note explaining why
2. Delete files that are fully superseded and have no historical value
3. Consolidate fragmented docs covering the same topic
4. Ensure no dead links or references to non-existent files

Constraints

• Prefer updating over creating new files
• Keep documentation concise — link to code rather than duplicating it
• Use relative paths for internal references
• Archive rather than delete when historical context has value
• If no /docs directory exists and there's nothing meaningful to document, report "no documentation changes needed" and move on

Output

Return a summary for inclusion in the parent workflow's report:

### Documentation Changes
| File | Action | Reason |
|------|--------|--------|
| /docs/X.md | Updated | [Brief reason] |
| /docs/Y.md | Archived | [Brief reason] |
| /docs/Z.md | Created | [Brief reason] |

### Documentation Health
- **Before:** [X files, Y% accurate]
- **After:** [X files, comprehensive coverage]