Doc Source Sync

Doc-Source Sync

Detect and resolve documentation drift by comparing EvoMap Wiki docs against their referenced source code files. Every doc in the Wiki has a source_files list in its YAML frontmatter — this skill uses that metadata to find stale docs and update them.

Documentation drifts silently. A renamed prop, a new API field, or a removed component can make an entire doc section wrong without anyone noticing. This skill closes the loop by making source-to-doc traceability a first-class concern.

When to activate

• User says "同步文档", "检查文档", "文档过期了吗", "对比代码和文档"
• User says "doc drift", "sync docs", "update docs from code"
• User mentions code changes and asks if documentation needs updating
• After a git pull of evomap-website that shows changed files
• When reviewing a PR that touches files listed in any doc's source_files

Key concepts

source_files frontmatter

Every Wiki doc (guide/*.md, concepts/*.md, reference/*.md) contains a source_files array in its YAML frontmatter:

---
title: 市场
source_files:
  - src/app/(main)/market/page.js
  - src/components/market/AssetsTab.jsx
  - src/components/market/RecipesTab.jsx
---

These paths are relative to the frontend repo root (E:/temp/evomap-website). VitePress ignores unknown frontmatter keys, so users never see this metadata.

Drift types

Workflow

Phase 1 — Prepare

1. Ensure the frontend repo is available locally. If not, clone it:

Does E:/temp/evomap-website/.git exist?
├─ Yes → git -C E:/temp/evomap-website pull
└─ No  → git clone --depth 1 https://github.com/EvoMap/evomap-website.git E:/temp/evomap-website

2. Collect all Wiki docs that have source_files in their frontmatter:

Scan: guide/*.md, concepts/*.md, reference/*.md
Extract: frontmatter.source_files from each
Build: Map<doc_path, source_file_paths[]>

Phase 2 — Detect changes

Two detection modes depending on user context:

Mode A: Full scan (user says "检查文档" or "sync docs")

For each doc, read every file in its source_files list. Compare the source code against what the doc claims:

• Check that components, props, and data fields mentioned in the doc still exist in the source
• Check that API endpoints match the paths in the source
• Check that KPI labels and formulas match the source
• Check for new components, fields, or tabs not covered by the doc

Mode B: Targeted scan (user mentions specific code changes or a git diff)

1. Parse the changed files from git diff or user input
2. Find which docs reference those files (reverse lookup from source_files)
3. Read only the affected source files and their corresponding docs
4. Identify what specifically changed and whether the doc needs updating

Phase 3 — Report

Present findings as a drift report table:

## Doc Drift Report — {date}

| Doc | Source file | Drift type | Detail | Action needed |
|-----|-------------|-----------|--------|---------------|
| guide/market.md | AssetsTab.jsx | Field drift | New `trustTier` field added | Add to asset card fields table |
| guide/agents.md | useAgentsData.js | API drift | New `getNodeSymbiosis` endpoint | Document new symbiosis view |
| — | pricing/page.js | No drift | Unchanged since last sync | None |

Phase 4 — Sync

For each drift item with action needed:

1. Read the full doc file
2. Read the changed source file(s)
3. Update the doc to reflect the current code state
4. Update last_updated in frontmatter to today's date
5. If source files changed (renamed/added/removed), update source_files list

After all updates, run npx vitepress build in the docs repo to verify no broken links or build errors.

Reverse lookup

To quickly find which docs are affected by a code change, use this mapping approach:

Input:  changed file path (e.g., "src/components/market/AssetsTab.jsx")
Action: grep -r "AssetsTab.jsx" guide/*.md concepts/*.md reference/*.md
Output: list of docs that reference this file in their source_files

Alternatively, scan all frontmatter programmatically:

For each .md file in guide/, concepts/, reference/:
  Parse YAML frontmatter
  If source_files contains the changed path:
    Mark doc as potentially stale

Updating source_files

When the source code is refactored (files renamed, split, or merged), update the source_files list in affected docs:

Rules

1. Always pull latest code before scanning. Stale local clones produce false positives. Run git pull at the start of every sync session.

2. Never remove source_files entries without checking. A file might be renamed, not deleted. Search for the content in nearby files before removing a reference.

3. Update last_updated when syncing. Every doc edit must bump the last_updated field in frontmatter so readers know the doc is fresh.

4. Preserve doc style. The existing docs use a consistent style: tables for data, <details> for FAQ, front matter with audience and version. Match this style when adding or editing content.

5. Report before editing. Always show the drift report first and get user confirmation before making bulk changes. A false positive in detection is cheap; a false positive in editing corrupts the doc.

6. Prioritize high-severity drift. Field and API drift can mislead users. Fix those first, cosmetic drift can wait.

7. Keep source_files minimal but complete. List only files that directly inform the doc's content. Don't include transitive dependencies (e.g., a utility used by the page but not mentioned in the doc).

Doc-Source Sync v1.0.0