---
description: docs-sync
allowed-tools: Bash, Read, Edit, Write, Glob, Grep
---

# docs-sync

Synchronize documentation with codebase changes.

## Prompt

ROLE: Documentation Synchronizer

OBJECTIVE
Detect code changes and ensure corresponding documentation is created or updated.

INPUTS (optional)
- BRANCH=<branch name> (default: current branch)
- BASE=<base branch> (default: main/master)
- AUTO_CREATE=yes|no (default: no, ask first)

DETECTION WORKFLOW
1. Get git diff between BASE and BRANCH:
   ```bash
   git diff <BASE>...<BRANCH> --name-status
   ```

2. Categorize changes:
   - **New API endpoints**: src/api/, src/routes/, src/controllers/
   - **New UI components**: src/components/, src/pages/
   - **New utilities/services**: src/services/, src/utils/
   - **Config changes**: *.config.js, *.yml, .env.example
   - **Database changes**: migrations/, schema/

3. Map to expected docs:
   - API endpoints → docs/04-architecture/api.md or OpenAPI spec
   - UI components → docs/04-architecture/components.md or Storybook
   - Services → docs/04-architecture/services.md
   - Config → docs/02-practices/configuration.md
   - Migrations → docs/04-architecture/database.md

ANALYSIS
For each changed file:
```
File: src/api/auth/login.ts (ADDED)
Expected doc: docs/04-architecture/api.md
Section: Authentication Endpoints
Status: ❌ MISSING (section exists but endpoint not documented)

Suggestion:
## POST /api/auth/login
**Added**: <date>
**Story**: <US_ID if found in commit>

Request:
\`\`\`json
{ "email": "string", "password": "string" }
\`\`\`

Response:
\`\`\`json
{ "token": "string", "user": {...} }
\`\`\`

Authentication: None (public endpoint)
Rate limit: 5 requests/minute
```

GAP REPORT
```markdown
# Documentation Sync Report

**Branch**: <BRANCH>
**Base**: <BASE>
**Generated**: <ISO timestamp>

## Missing Documentation

### API Endpoints (3)
- ❌ POST /api/auth/login (src/api/auth/login.ts)
- ❌ GET /api/users/:id (src/api/users/get.ts)
- ❌ DELETE /api/sessions (src/api/sessions/delete.ts)

### UI Components (2)
- ❌ LoginForm (src/components/LoginForm.tsx)
- ⚠️ UserProfile (src/components/UserProfile.tsx) - stub exists, needs details

### Configuration (1)
- ❌ New env var: JWT_SECRET (.env.example)

## Outdated Documentation

### Deprecated
- 📄 docs/04-architecture/api.md mentions /api/v1/login (removed in this branch)

## Up-to-Date
- ✅ UserAvatar component documented
- ✅ Database schema up-to-date
```

ACTIONS (after user review)
1. For missing docs:
   - Generate stub documentation with placeholders
   - Preview (diff-first)
   - Ask: "Create missing documentation? (YES/NO)"

2. For outdated docs:
   - Suggest removals or updates
   - Preview changes
   - Ask: "Update outdated sections? (YES/NO)"

3. If AUTO_CREATE=yes:
   - Create all missing docs automatically
   - Mark sections with "TODO: Add details" for manual review
   - Commit: "docs: sync with codebase changes"

SMART INFERENCE
Try to infer documentation from:
- TypeScript types/interfaces
- JSDoc comments
- OpenAPI decorators
- Function signatures
- Test files (use as examples)

Example:
```typescript
// Code: src/api/auth/login.ts
/**
 * Authenticates user with email and password
 * @returns JWT token and user profile
 */
export async function login(req: Request, res: Response) {
  const { email, password } = req.body;
  // ...
}

// Generated doc:
## POST /api/auth/login
Authenticates user with email and password.
Returns JWT token and user profile.
```

INTEGRATION
- Create story if significant doc gaps found: "US-XXXX: Update documentation for <feature>"
- Append to docs/09-agents/bus/log.jsonl: {"type":"docs-sync","missing":3,"outdated":1}
- Optionally add to PR checklist: "- [ ] Documentation updated"

CI INTEGRATION
Suggest adding to PR checks:
```yaml
- name: Check docs sync
  run: npx claude-code /AgileFlow:docs-sync BRANCH=${{ github.head_ref }}
  # Fail if critical docs missing (e.g., public API endpoints)
```

RULES
- Never delete docs without explicit approval
- Preserve custom content (don't overwrite manually written sections)
- Use managed section markers: <!-- MANAGED:api-endpoints --> ... <!-- /MANAGED -->
- Link docs to source files for traceability
- Diff-first, YES/NO for all changes

OUTPUT
- Gap report (markdown)
- List of actions to take
- Optional: PR with doc updates (if approved)