Keep DevDocs documentation consistent with the actual implementation progress, detect deviations, and update status.
Language Rules
- Support questions in Chinese and English
- Respond uniformly in Chinese
- Generate documentation in Chinese
Trigger Conditions
- After the user completes one or more development tasks
- When the user requests a consistency check between documentation and code
- When the user needs to update documentation progress
- Regular synchronization (e.g., at the end of a Sprint)
Run Modes
/devdocs-sync → 默认模式：trace → audit 自动串行
/devdocs-sync --check → 仅检查，不更新文档
/devdocs-sync --absorb → 吸收模式（自动 + 智能补齐）
/devdocs-sync --archive → 全量归档检查（所有文档类型）
/devdocs-sync --archive requirements → 仅归档需求文档
/devdocs-sync --archive design → 仅归档设计文档
/devdocs-sync --archive tests → 仅归档测试用例
/devdocs-sync --archive tasks → 仅归档开发任务
/devdocs-sync --archive --release v1.0.0 → 创建版本快照
/devdocs-sync T-01 T-02 → 指定范围同步
Default Mode Changes
The original --trace and --audit have been merged into the default mode. When called without arguments, it automatically executes the trace → audit serial process (audit depends on trace's output, so it is no longer a standalone subcommand).--absorb automatically includes the trace step.
Mode Comparison
| Mode | Check | Auto Update | Smart Completion | User Confirmation |
|---|---|---|---|---|
| check | ✅ | ❌ | ❌ | ❌ |
| sync (default) | ✅ trace+audit | ✅ | ❌ | ✅ All |
| absorb | ✅ trace+absorb | ✅ | ✅ | ✅ High-risk only |
| archive | ✅ Archive conditions | ✅ Archive files | ❌ | ✅ All |
Core Philosophy
Relationship Between Documentation and Code
文档定义（计划） 代码实现（实际）
│ │
├── F-XXX 功能点 ←→ ├── 功能模块
├── AC-XXX 验收标准 ←→ ├── 业务逻辑
├── T-XX 开发任务 ←→ ├── 代码提交
└── UT/IT/E2E 测试 ←→ └── 测试文件
Core Principles：
- Documentation is the plan, code is the implementation
- Deviations are normal; the key is to synchronize in a timely manner
- Synchronization should be bidirectional: documentation→code (guidance), code→documentation (recording)
Synchronization Timing
| Timing | Synchronization Content |
|---|---|
| After task completion | Update task status, test results |
| Sprint end | Full check, progress report |
| After requirement changes | Update requirement documents, impact analysis |
| After code review | Record design decision changes |
Workflow
1. 读取 DevDocs 文档
│
▼
2. 扫描代码库（工作区状态）
├── 检查文件是否存在（Glob）
├── 运行测试（获取实时结果）
├── 检查未提交变更（git status）
└── 参考提交记录（git log，辅助）
│
▼
3. 对比分析
├── 任务完成状态
├── 测试覆盖情况
└── 功能实现状态
│
▼
4. 生成偏差报告
│
▼
5. 询问用户确认更新
│
▼
6. 更新文档
Important: The check is based on thecurrent workspace state, rather than relying solely on git commit history.
Mode Details
Default Mode (trace → audit automatic serial)
When called without arguments, it automatically executes a two-step process:
- trace stage: Scans the
@satisfies/@verifiesannotations in the code, cross-validates with the documentation, and updates the code location column of the traceability matrix. See trace-mode.md - audit stage: Detects the integrity of the numbering system to prevent the accumulation of documentation maintenance debt. Checks AC coverage, F task closure, INS conversion, and orphaned numbers. See audit-mode.md
audit depends on trace's scan results, so it is executed automatically in serial and is no longer a standalone subcommand.
Absorb Mode (--absorb)
Evolves from "inspector" to "recorder", supporting a code-first development path. Low-risk deviations are automatically absorbed; high-risk ones require confirmation. Automatically includes the trace step.
See absorb-mode.md
Document Archiving (--archive)
Supports archiving of all document types, controls document bloat, and retains historical records for traceability:
| Document Type | Archive Condition | Archive File |
|---|---|---|
| Requirements | Feature completed/deprecated | archive/01-requirements-archive.md |
| Design | Associated feature has been archived | archive/02-system-design-archive.md |
| Test | Associated AC has been archived | archive/03-test-cases-archive.md |
| Task | More than 15 completed | archive/04-dev-tasks-archive.md |
Cascade is supported during archiving: when archiving F-001, associated design/test/tasks can be archived at the same time.
See archive.md
Sync commands
Quick check
/devdocs-sync --check
# 输出: 偏差报告（仅显示，不写入）
Full sync (default)
/devdocs-sync
# 流程: trace 扫描 → audit 检查 → 显示报告 → 确认 → 更新文档
Absorb mode
/devdocs-sync --absorb
# 流程: trace 扫描 → 自动吸收低风险 → 确认高风险 → 生成报告
Specify scope
/devdocs-sync T-01 T-02
# 只同步特定任务
Output file
Progress report
Generate docs/devdocs/00-progress-report.md, including overall progress, deviation summary, and next-step recommendations.
Document updates
| Document | Update content |
|---|---|
04-dev-tasks.md |
Task completion status, execution checklist |
03-test-cases.md |
Traceability matrix status, test pass status |
01-requirements.md |
Feature point implementation status (if a status column exists) |
Constraints
Check constraints
- All DevDocs documents must be read before performing the check
- A deviation report must be generated
- The user must be asked for confirmation before updating documents(except for low risk in absorb mode)
- Check results must be traceable (show the check method)
Update constraints
- Do not automatically delete document content, only mark status
- Do not automatically modify code, only update documents
- Preserve the original document structure
- Record a timestamp when updating
Absorb mode constraints
- Low-risk absorption is limited to status field updates
- High-risk absorption must be confirmed by the user
- New content must specify an associated number (AC/F/US)
- Content whose association cannot be determined is marked as "to be handled manually"
- Absorb operations must generate an absorption report
Security constraints
- Do not execute unknown shell commands
- Test commands use the command configured for the project
- Confirmation is required before large-scale updates
Skill collaboration
| Scenario | Collaborating Skill | Description |
|---|---|---|
| Development completed | /devdocs-dev-workflow |
Called: triggers --trace after task completion |
| After task completion | /devdocs-dev-tasks |
Trigger sync after executing a task |
| Test traceability | /devdocs-test-cases |
Collaboration: update traceability matrix code locations |
| Requirement change | /devdocs-feature |
Sync after adding a new feature |
| Bug fix | /devdocs-bugfix |
Update documents after a bug fix |
| Insight confirmation | /devdocs-insights |
Sync after improvement suggestions are confirmed |
| Project refactoring | /devdocs-retrofit |
Full sync after refactoring |
Reference materials
- absorb-mode.md - Absorb mode details
- audit-mode.md - Traceability health check
- trace-mode.md - Code traceability scan
- archive.md - Task archiving feature
- examples.md - Usage examples and deviation types
Deviation repair routing (scheduler feature)
When a deviation is detected, the next repair Skill must be assigned in the report:
| Deviation type | Repair Skill | Description |
|---|---|---|
| Design missing/drift | /devdocs-system-design |
Code has new interfaces but they are not documented |
| AC missing tests | /devdocs-test-cases |
Acceptance criteria have no corresponding test cases |
| F missing task closure | /devdocs-dev-tasks |
Feature points have no associated development tasks |
| Code implemented but documentation lags behind | /devdocs-sync --absorb |
Status not updated, new content not registered |
| Code location missing from traceability matrix | /devdocs-sync |
Code annotations not scanned into matrix |
Scheduler principle: A deviation report must not only list problems; it must provide a clear fix routing.
Usage instructions
After the task is completed, run directly:
/devdocs-sync # trace → audit 自动串行 → 显示报告 → 确认更新
或 --absorb # trace + 自动吸收低风险 → 确认高风险
The default mode has merged trace and audit into an automatic serial process, with no need to manually invoke them in two steps.
Batch confirmation optimization
Low-risk changes within the same session (status updates, progress statistics, etc.) are merged into document-level batch confirmation rather than confirmed one by one.
Sub-Agent summary format
When this Skill runs as a sub-Agent, return the following structured summary:
skill: devdocs-sync
mode: default | check | absorb | archive
trace_results:
satisfies_found: X
verifies_found: X
coverage: "XX%"
audit_results:
orphan_ids: []
missing_tests: []
health_score: "XX%"
deviations:
total: X
auto_absorbed: X # absorb 模式
needs_confirm: X
status: synced | deviations_found
output_file: docs/devdocs/00-progress-report.md
Next step
After synchronization is complete, according to the progress report'sdeviation fix routingexecute the corresponding Skill.