Doc Auto-Sync Skill

Purpose: Auto-detect code changes → identify affected docs → update or bootstrap them. When: After implementation-runner, before codex-review-code.

---

Inputs

• analysisContext.repo.changedFiles — list of changed files
• analysisContext.request.taskType — feature/bugfix/refactor
• analysisContext.artifacts.tasksRoot — task document root

Workflow

1. Change Detection → Doc Mapping

Map changed files to affected docs:

docMapping:
  "src/api/**":
    - "docs/generated/api-reference.md"
    - "README.md#api"
    - ".claude/PROJECT.md#api-data-patterns"
  "src/components/**":
    - "ARCHITECTURE.md#components"
  "prisma/schema.prisma|drizzle/*":
    - "docs/generated/db-schema.md"
    - ".claude/PROJECT.md#type-domain-patterns"
  "package.json":
    - "README.md#installation"
    - ".claude/PROJECT.md#stack"
  ".env*":
    - "README.md#configuration"
    - ".claude/PROJECT.md#environment-variables"
  "*.config.*":
    - ".claude/PROJECT.md#verification-commands"

2. PROJECT.md Auto-Sync

Detect and update the relevant PROJECT.md section:

Trigger	Section
package.json / pyproject.toml / go.mod changed	## Stack
New directory created or structure change	## Directory / Structure
API route file changed	## API / Data Patterns
Type definition or schema file changed	## Type / Domain Patterns
.env* file changed	## Environment Variables
Test config file changed (jest.config, vitest.config)	## Testing Rules
package.json scripts / Makefile changed	## Verification / Commands

Rules:

• Only update sections with actual changes (diff-based)
• CRITICAL: Preserve user-written content.
  • For lists (e.g. Stack), append new items; do not remove existing ones.
  • For descriptions, only append new info if missing.
  • Do not overwrite custom notes or comments.
• Add <!-- auto-synced: YYYY-MM-DD --> comment to updated sections

3. Document Bootstrap (New Projects)

If key documents are missing, recommend creation:

bootstrapRules:
  always:
    - CHANGELOG.md
  ifMissing:
    - condition: "estimatedLOC > 5000"
      create: "ARCHITECTURE.md (skeleton)"
    - condition: "API route files exist"
      create: "docs/generated/api-reference.md"
    - condition: "ORM schema files exist"
      create: "docs/generated/db-schema.md"
  neverForce:
    - docs/design-docs/

Bootstrap runs only on first detection or explicit --init flag.

4. Freshness Check

Compare doc last-modified vs related source last-modified:

freshnessCheck:
  staleThreshold: "30 days"
  checks:
    - "ARCHITECTURE.md vs project structure"
    - "docs/generated/* vs source code"
    - ".claude/PROJECT.md vs actual project state"

Stale docs → add to output staleDocs[] for pre-flight-check to surface.

5. CHANGELOG Entry

Generate a changelog entry for commit-moonshot:

changelog:
  format: "Keep a Changelog"
  sections: [Added, Changed, Deprecated, Removed, Fixed, Security]
  source: "git diff + commit messages + analysisContext.request.taskType"

---

Output (patch)

notes:
  - "doc-auto-sync: updated=[count], bootstrapped=[count], stale=[count]"

docSync:
  updatedDocs:
    - path: ".claude/PROJECT.md"
      sections: ["stack", "apiPatterns"]
    - path: "docs/generated/api-reference.md"
      action: "regenerated"
  bootstrappedDocs:
    - path: "CHANGELOG.md"
      action: "created"
  staleDocs:
    - path: "ARCHITECTURE.md"
      lastModified: "2025-01-15"
      relatedCodeModified: "2025-02-10"
  changelogEntry:
    type: "Added"
    description: "Payment API endpoint with coupon validation"
  projectMdChanges:
    - section: "stack"
      diff: "+stripe@14.0.0"

---

Scale Guidance

Scale	Auto-generate	Manual
Small (< 5K LOC)	PROJECT.md sync, CHANGELOG.md	README.md (initial)
Medium (5K~50K)	+ docs/generated/*, README.md sections	+ ARCHITECTURE.md
Large (50K+)	+ full suite	+ docs/design-docs/*

Recommended Docs Structure

{project-root}/
├── ARCHITECTURE.md              # Module codemap, boundaries, invariants
├── CHANGELOG.md                 # Auto-generated at commit
├── README.md                    # Section-level auto-update
│
├── docs/
│   ├── design-docs/             # Complex feature designs (manual, opt-in)
│   │   └── {feature}.md
│   └── generated/               # Auto-extracted from code
│       ├── api-reference.md
│       └── db-schema.md
│
└── .claude/
    ├── PROJECT.md               # Auto-synced sections
    └── docs/tasks/              # Default tasksRoot (or docs/exec-plans/)

Note: docs/exec-plans/ is an optional alternative to .claude/docs/tasks/ for git-tracked task docs. Configure via PROJECT.md: documentPaths.tasksRoot.