# Doc Sync Enforcer

> Ensures documentation matches code when committing or pushing changes. Triggers on "commit", "push", "ready to commit".

- Skill: `mbelenmontoya/doc-sync-enforcer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add mbelenmontoya/doc-sync-enforcer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/mbelenmontoya/doc-sync-enforcer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: mbelenmontoya (https://skillmd.com/u/mbelenmontoya)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/mbelenmontoya/doc-sync-enforcer

---


# Documentation Sync Enforcer

Ensures code changes have corresponding documentation updates before committing.

## When This Activates

Auto-triggers when you:
- Say "commit", "push", or "ready to commit"
- Ask to create a commit message
- Request git operations

## What It Checks

### 1. API Route Changes
**Files:** `app/api/**/*.ts`

If API routes were modified:
- Check if `FINAL_SPEC.md` needs updating (it's the single source of truth)
- Check if `README.md` API documentation section needs updating
- Warn if a locked file was modified (see CLAUDE.md "Don't Touch" list)

### 2. Component Changes
**Files:** `app/components/**/*.tsx`, `app/r/**/components/**/*.tsx`

If components were added or significantly modified:
- Check if `CLAUDE.md` "Project Structure" section needs updating
- Check if component is listed in the reuse-enforcer skill's inventory

### 3. Design Token Changes
**Files:** `app/globals.css`

If design tokens were modified:
- Update `CLAUDE.md` "Design Tokens" table
- Update `.claude/rules/tailwind-tokens.md` token list
- Verify no hardcoded values were introduced

### 4. Hook/Utility Changes
**Files:** `app/**/hooks/*.ts`, `lib/**/*.ts`

If hooks or utilities were added:
- Update `CLAUDE.md` "Project Structure" section
- Update code-reuse-enforcer skill's hook/utility inventory

### 5. Test Changes
**Files:** `__tests__/**/*`

If tests were added or modified:
- Verify test count in `CLAUDE.md` and `README.md` is still accurate

## Decision Matrix

| Change Type | Doc Action |
|------------|-----------|
| Bug fix (behavior unchanged) | No doc update needed |
| Refactor (API unchanged) | No doc update needed |
| New component or hook | Update CLAUDE.md structure + reuse-enforcer inventory |
| Changed API route | Update FINAL_SPEC.md if schema/behavior changed |
| New design token | Update CLAUDE.md tokens table + tailwind-tokens rule |
| Deleted file or export | Search docs for stale references |
| New pending task discovered | Add to docs/TODO.md |
| Task completed | Move from docs/TODO.md to docs/DONE.md |

## Hara Documentation Files

| File | Update when... |
|------|---------------|
| `CLAUDE.md` | Project structure, tokens, patterns, or locked files change |
| `FINAL_SPEC.md` | Database schema, API specs, or core data flow changes |
| `PRODUCTION_READINESS.md` | Deployment requirements or checklist items change |
| `SELF_QA_RULES.md` | QA validation rules or test commands change |
| `KNOWN_ISSUES.md` | New bugs discovered or existing bugs resolved |
| `README.md` | Setup, commands, or architecture overview changes |
| `docs/TODO.md` | New tasks found or tasks completed |
| `docs/DONE.md` | Tasks completed |

## How It Works

When you're ready to commit:

1. Check staged/modified files
2. Categorize changes (API, component, token, hook, test)
3. Compare against documentation files
4. Report what docs need updating
5. Ask if you want to update before committing

**Non-blocking** — won't stop your commit, just reminds you.