# Docs Sync

> Use this skill ALWAYS at the end of ANY code-changing task to synchronize project memory with reality. Trigger this skill after closing any TZ, after fixing any bug, after completing any refactor, after adding any feature, after creating any ADR — even if the user did not explicitly request docs update. This skill is MANDATORY before declaring a task complete.

- Skill: `engsimsoft/docs-sync` (Agent Skill)
- Install (CLI): `npx skillmds@latest add engsimsoft/docs-sync`
- Raw SKILL.md: https://api.skillmd.com/api/skills/engsimsoft/docs-sync/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: engsimsoft (https://skillmd.com/u/engsimsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/engsimsoft/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
```bash
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:
```yaml
---
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)