Skip to content

Commit 96bd18b

Browse files
fmw666fmw666
committed
feat(skills): introduce doc-source-sync skill for documentation drift detection
- Add new skill to detect and synchronize documentation drift when source code changes - Define activation triggers based on user input and code changes - Outline workflow phases for preparation, change detection, reporting, and syncing - Include detailed explanations of drift types and source_files frontmatter usage Made-with: Cursor
1 parent 54ad120 commit 96bd18b

File tree

1 file changed

+203
-0
lines changed

1 file changed

+203
-0
lines changed

‎.cursor/skills/doc-source-sync/SKILL.md‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
name: doc-source-sync
3+
description: >
4+
Detect documentation drift when source code changes, and synchronize Wiki
5+
docs accordingly. Activate when user says "同步文档", "检查文档", "文档过期了吗",
6+
"doc drift", "sync docs", "update docs from code" — or when the user mentions
7+
that frontend code has changed and documentation might be stale. Also activate
8+
proactively when reviewing a PR or commit that touches files referenced in any
9+
doc's source_files frontmatter.
10+
version: 1.0.0
11+
---
12+
13+
# Doc-Source Sync
14+
15+
Detect and resolve documentation drift by comparing EvoMap Wiki docs against
16+
their referenced source code files. Every doc in the Wiki has a `source_files`
17+
list in its YAML frontmatter — this skill uses that metadata to find stale docs
18+
and update them.
19+
20+
Documentation drifts silently. A renamed prop, a new API field, or a removed
21+
component can make an entire doc section wrong without anyone noticing. This
22+
skill closes the loop by making source-to-doc traceability a first-class concern.
23+
24+
## When to activate
25+
26+
- User says "同步文档", "检查文档", "文档过期了吗", "对比代码和文档"
27+
- User says "doc drift", "sync docs", "update docs from code"
28+
- User mentions code changes and asks if documentation needs updating
29+
- After a `git pull` of `evomap-website` that shows changed files
30+
- When reviewing a PR that touches files listed in any doc's `source_files`
31+
32+
---
33+
34+
## Key concepts
35+
36+
### source_files frontmatter
37+
38+
Every Wiki doc (`guide/*.md`, `concepts/*.md`, `reference/*.md`) contains a
39+
`source_files` array in its YAML frontmatter:
40+
41+
```yaml
42+
---
43+
title: 市场
44+
source_files:
45+
- src/app/(main)/market/page.js
46+
- src/components/market/AssetsTab.jsx
47+
- src/components/market/RecipesTab.jsx
48+
---
49+
```
50+
51+
These paths are relative to the frontend repo root (`E:/temp/evomap-website`).
52+
VitePress ignores unknown frontmatter keys, so users never see this metadata.
53+
54+
### Drift types
55+
56+
| Type | Description | Severity |
57+
|------|-------------|----------|
58+
| **Field drift** | A data field was added, renamed, or removed in the source | High — doc shows wrong info |
59+
| **Component drift** | A component was renamed, split, or deleted | High — doc references non-existent code |
60+
| **API drift** | An API endpoint path or response shape changed | High — doc shows wrong endpoint |
61+
| **Metric drift** | A KPI formula, label, or data source changed | Medium — numbers don't match |
62+
| **Layout drift** | Page tabs, sections, or navigation changed | Medium — doc structure is wrong |
63+
| **Cosmetic drift** | Copy changes, icon swaps, minor styling | Low — doc is functionally correct |
64+
65+
---
66+
67+
## Workflow
68+
69+
### Phase 1 — Prepare
70+
71+
1. Ensure the frontend repo is available locally. If not, clone it:
72+
73+
```
74+
Does E:/temp/evomap-website/.git exist?
75+
├─ Yes → git -C E:/temp/evomap-website pull
76+
└─ No → git clone --depth 1 https://github.com/EvoMap/evomap-website.git E:/temp/evomap-website
77+
```
78+
79+
2. Collect all Wiki docs that have `source_files` in their frontmatter:
80+
81+
```
82+
Scan: guide/*.md, concepts/*.md, reference/*.md
83+
Extract: frontmatter.source_files from each
84+
Build: Map<doc_path, source_file_paths[]>
85+
```
86+
87+
### Phase 2 — Detect changes
88+
89+
Two detection modes depending on user context:
90+
91+
**Mode A: Full scan** (user says "检查文档" or "sync docs")
92+
93+
For each doc, read every file in its `source_files` list. Compare the source
94+
code against what the doc claims:
95+
96+
- Check that components, props, and data fields mentioned in the doc still
97+
exist in the source
98+
- Check that API endpoints match the paths in the source
99+
- Check that KPI labels and formulas match the source
100+
- Check for new components, fields, or tabs not covered by the doc
101+
102+
**Mode B: Targeted scan** (user mentions specific code changes or a git diff)
103+
104+
1. Parse the changed files from git diff or user input
105+
2. Find which docs reference those files (reverse lookup from source_files)
106+
3. Read only the affected source files and their corresponding docs
107+
4. Identify what specifically changed and whether the doc needs updating
108+
109+
### Phase 3 — Report
110+
111+
Present findings as a drift report table:
112+
113+
```markdown
114+
## Doc Drift Report — {date}
115+
116+
| Doc | Source file | Drift type | Detail | Action needed |
117+
|-----|-------------|-----------|--------|---------------|
118+
| guide/market.md | AssetsTab.jsx | Field drift | New `trustTier` field added | Add to asset card fields table |
119+
| guide/agents.md | useAgentsData.js | API drift | New `getNodeSymbiosis` endpoint | Document new symbiosis view |
120+
| — | pricing/page.js | No drift | Unchanged since last sync | None |
121+
```
122+
123+
### Phase 4 — Sync
124+
125+
For each drift item with action needed:
126+
127+
1. Read the full doc file
128+
2. Read the changed source file(s)
129+
3. Update the doc to reflect the current code state
130+
4. Update `last_updated` in frontmatter to today's date
131+
5. If source files changed (renamed/added/removed), update `source_files` list
132+
133+
After all updates, run `npx vitepress build` in the docs repo to verify no
134+
broken links or build errors.
135+
136+
---
137+
138+
## Reverse lookup
139+
140+
To quickly find which docs are affected by a code change, use this mapping
141+
approach:
142+
143+
```
144+
Input: changed file path (e.g., "src/components/market/AssetsTab.jsx")
145+
Action: grep -r "AssetsTab.jsx" guide/*.md concepts/*.md reference/*.md
146+
Output: list of docs that reference this file in their source_files
147+
```
148+
149+
Alternatively, scan all frontmatter programmatically:
150+
151+
```
152+
For each .md file in guide/, concepts/, reference/:
153+
Parse YAML frontmatter
154+
If source_files contains the changed path:
155+
Mark doc as potentially stale
156+
```
157+
158+
---
159+
160+
## Updating source_files
161+
162+
When the source code is refactored (files renamed, split, or merged), update
163+
the `source_files` list in affected docs:
164+
165+
| Code change | Doc action |
166+
|-------------|-----------|
167+
| File renamed | Update path in source_files |
168+
| File split into two | Add new path, keep old if still relevant |
169+
| File deleted | Remove path, find replacement if any |
170+
| New page/component added | Consider whether existing doc covers it or a new doc is needed |
171+
172+
---
173+
174+
## Rules
175+
176+
1. **Always pull latest code before scanning.** Stale local clones produce
177+
false positives. Run `git pull` at the start of every sync session.
178+
179+
2. **Never remove source_files entries without checking.** A file might be
180+
renamed, not deleted. Search for the content in nearby files before removing
181+
a reference.
182+
183+
3. **Update last_updated when syncing.** Every doc edit must bump the
184+
`last_updated` field in frontmatter so readers know the doc is fresh.
185+
186+
4. **Preserve doc style.** The existing docs use a consistent style: tables for
187+
data, `<details>` for FAQ, front matter with audience and version. Match this
188+
style when adding or editing content.
189+
190+
5. **Report before editing.** Always show the drift report first and get user
191+
confirmation before making bulk changes. A false positive in detection is
192+
cheap; a false positive in editing corrupts the doc.
193+
194+
6. **Prioritize high-severity drift.** Field and API drift can mislead users.
195+
Fix those first, cosmetic drift can wait.
196+
197+
7. **Keep source_files minimal but complete.** List only files that directly
198+
inform the doc's content. Don't include transitive dependencies (e.g., a
199+
utility used by the page but not mentioned in the doc).
200+
201+
---
202+
203+
*Doc-Source Sync v1.0.0*

0 commit comments

Comments
 (0)