docs-sync

Docs-sync workflow

Synchronize docs/agent/ with what ACTUALLY happened in code. Code is truth, docs are derived.

When to run

• End of any task that modified code
• After bugfix, refactor, feature work
• After creating an ADR
• During /close-tz finalization
• When called manually via /docs-sync

Procedure (in order)

1. Determine what changed

git log --oneline <last_synced_commit>..HEAD
git diff --stat <last_synced_commit>..HEAD

The last_synced_commit is in docs/agent/00_current_state.md frontmatter.

2. Read current docs/agent/ files

• 00_current_state.md — for durable facts cache
• 03_active_plan.md — for closed task removal
• 04_changelog.md — to append new entries
• 06_known_issues.md — to update resolved/new issues
• 07_handoff.md — to refresh next-step

3. Update each file with FACTS from diff (not narrative)

00_current_state.md — only DURABLE facts:

• "Auth uses NextAuth + email" — durable
• "Currently working on TZ-15" — NOT durable, remove

04_changelog.md — concise entries from diff:

## YYYY-MM-DD — TZ-NN: <title>
- Added: ... (what new code does)
- Changed: ... (what behavior changed)
- Fixed: ... (what bug is no longer)
- Commit: <hash>

03_active_plan.md — remove closed tasks, surface next ones.

07_handoff.md — diff-based, NOT narrative:

## What was done (facts from git)
- Commit abc123: feat(tz-15) summary
- Files: src/api/foo.py (+45/-12), src/db/models.py (+8/-0)
- Tests: pytest tests/test_foo.py PASS (12/12), mypy clean

## Where we stopped
- Current position: TZ-15 stage 4 of 7
- Next concrete action: <exact command or exact edit>

## NOT what we think is true
- (no hypotheses here, only facts)

4. ADR if non-trivial decision was made

• Use /adr slash command
• INDEX.md will auto-regenerate via post-tool-edit hook

5. Update version-stamps

At the top of each modified docs/agent/ file:

---
last_updated_at: 2026-MM-DD
last_updated_commit: <new HEAD hash>
last_updated_by: <session-id or "claude-code-sync">
---

6. Do NOT invent work

• If diff doesn't show it, you didn't do it
• Don't add aspirational entries ("planning to...") to changelog
• Don't add features that aren't in the code

Anti-patterns

• ✗ Update docs by copying old docs (they get more stale)
• ✗ Update CLAUDE.md to reflect new feature (CLAUDE.md is navigation, not detail)
• ✗ Skip docs-sync because "tests pass = done"
• ✗ Add narrative to HANDOFF (use diff facts only)