Doc Auto Sync

Doc Auto-Sync Skill

Visibility

This is a doc-ops helper. It should normally run behind a doc-ops or finish bundle after implementation or verification. Do not present it as a default workflow entrypoint.

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
• project reference docs: workflow/README.md, docs/design/README.md, docs/glossary/README.md, docs/daily/README.md, TEST_GUIDE.md, docs/analysis/README.md

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"
    - "docs/glossary/README.md#api-terms"
  "src/components/**":
    - "ARCHITECTURE.md#components"
    - "docs/design/README.md#component-rules"
  "prisma/schema.prisma|drizzle/*":
    - "docs/generated/db-schema.md"
    - ".claude/PROJECT.md#type-domain-patterns"
    - "docs/glossary/README.md#term-table"
  "package.json":
    - "README.md#installation"
    - ".claude/PROJECT.md#stack"
    - "TEST_GUIDE.md#command-matrix"
  ".env*":
    - "README.md#configuration"
    - ".claude/PROJECT.md#environment-variables"
  "*.config.*":
    - ".claude/PROJECT.md#verification-commands"
    - "TEST_GUIDE.md#command-matrix"
  "<MOONSHOT_RELAY_HOME>/scripts/**|workflow/**":
    - "workflow/README.md#standard-entry-points"
  "src/**|apps/**|packages/**":
    - "docs/analysis/README.md"

2. PROJECT.md Auto-Sync

Detect and update the relevant PROJECT.md section:

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
    - workflow/README.md
    - docs/design/README.md
    - docs/glossary/README.md
    - docs/daily/README.md
    - TEST_GUIDE.md
    - docs/analysis/README.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"
    - "workflow/README.md vs actual workflow scripts and branch policy"
    - "docs/design/README.md vs UI/component system"
    - "docs/glossary/README.md vs active domain terms"
    - "TEST_GUIDE.md vs executable verification commands"

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

4.5 Phase Closeout Sync

When a phase runner marks a phase complete, finish-bundle doc sync must reconcile:

• master plan Phase Completion Checklist
• .moonshot-relay/docs/phase-status.yaml status and archivedPhaseDoc
• execution artifact paths for SPRINT_CONTRACT.md, QA_REPORT.md, HANDOFF.md, and SCORECARD.md
• daily log final reconciliation when earlier entries record blocked or failed attempts
• evidence links for every critical SCN-*

Do not leave only mid-run blocker notes when final evidence supersedes them. Append a final reconciliation entry instead of deleting history.

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"

6. Project Knowledge Seed/Cache Sync

When docs are updated from code analysis, refresh the deterministic project knowledge seed/cache so later verified knowledge writes can use the same code/doc understanding:

node <MOONSHOT_RELAY_HOME>/scripts/memorygraph-project-index.mjs

Rules:

• Generate only compatibility seed/cache files during doc sync; do not write semantic facts or raw graph state unless the user explicitly requested memory refresh.
• Keep .moonshot-relay/docs/ko/ out of seed sources.
• Include code-level facts from existing projects through the default --analysis-level code.
• Report promotion candidate count, but do not promote into moonshot-relay without explicit approval.
• Keep .moonshot-relay/cache/memorygraph/, legacy .claude/cache/memorygraph/, and account-root knowledge runtime state unstaged by default.

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"
  memoryGraphSeed:
    path: ".moonshot-relay/cache/memorygraph/project-graph-seed.json"
    promotionCandidatesPath: ".moonshot-relay/cache/memorygraph/promotion-candidates.json"
    nodeCount: 0
    relationshipCount: 0
    promotionCandidateCount: 0

Scale Guidance

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 .moonshot-relay/docs/tasks/ for git-tracked task docs. Configure via PROJECT.md: documentPaths.tasksRoot.

Project Knowledge Context Contract

Doc sync may consume compact projectKnowledgeContext to align terminology and may generate seed/cache material. Prompt assembly must not write semantic facts.

Allowed writes during doc sync are documentation updates and deterministic seed/cache artifacts only. Semantic fact promotion remains a separate verify/promote lifecycle, and raw MemoryGraph/KG/ontology/log/transcript payloads must not enter doc-sync prompts.