Documentation Sync

Keep DevDocs documentation aligned with actual implementation progress, detect discrepancies, and update statuses.

Language Rules

Supports questions in both Chinese and English
Provides unified Chinese responses
Generates documentation in Chinese

Trigger Conditions

After users complete one or more development tasks
When users request to check doc-code consistency
When users need to update documentation progress
Regular synchronization (e.g., at the end of a Sprint)

Operation Modes

/devdocs-sync                    → Full sync (check + confirmation + update)
/devdocs-sync --check            → Check only, no documentation update
/devdocs-sync --absorb           → Absorb mode (automatic + intelligent completion)
/devdocs-sync --trace            → Code trace scan (update matrix code locations)
/devdocs-sync --archive          → Full archive check (all documentation types)
/devdocs-sync --archive requirements  → Archive requirement docs only
/devdocs-sync --archive design        → Archive design docs only
/devdocs-sync --archive tests         → Archive test cases only
/devdocs-sync --archive tasks         → Archive development tasks only
/devdocs-sync --archive --release v1.0.0  → Create version snapshot
/devdocs-sync --audit            → Trace health check
/devdocs-sync T-01 T-02          → Sync specified scope

Mode Comparison

Mode	Check	Auto Update	Intelligent Completion	User Confirmation
check	✅	❌	❌	❌
sync (default)	✅	✅	❌	✅ All
absorb	✅	✅	✅	✅ High-risk only
trace	✅ Code scan	✅ Matrix	❌	❌
archive	✅ Archive conditions	✅ Archive files	❌	✅ All
audit	✅ Trace	❌	❌	❌

Core Concepts

Relationship Between Documentation and Code

Documentation Definition (Plan)          Code Implementation (Actual)
     │                        │
     ├── F-XXX Feature Points    ←→   ├── Feature Modules
     ├── AC-XXX Acceptance Criteria ←→   ├── Business Logic
     ├── T-XX Development Tasks   ←→   ├── Code Commits
     └── UT/IT/E2E Tests  ←→   └── Test Files

Core Principles:

Documentation is the plan, code is the implementation
Discrepancies are normal; the key is timely synchronization
Synchronization should be bidirectional: Documentation → Code (guidance), Code → Documentation (recording)

Synchronization Timing

Timing	Sync Content
After task completion	Update task status, test results
End of Sprint	Full check, progress report
After requirement change	Update requirement docs, impact analysis
After code review	Record design decision changes

Workflow

1. Read DevDocs documentation
   │
   ▼
2. Scan code repository (workspace status)
   ├── Check file existence (Glob)
   ├── Run tests (get real-time results)
   ├── Check uncommitted changes (git status)
   └── Reference commit history (git log, auxiliary)
   │
   ▼
3. Comparative Analysis
   ├── Task completion status
   ├── Test coverage
   └── Feature implementation status
   │
   ▼
4. Generate discrepancy report
   │
   ▼
5. Request user confirmation for updates
   │
   ▼
6. Update documentation

Important: Checks are based on current workspace status, not just git commit history.

Mode Details

Absorb Mode (--absorb)

Evolve from "inspector" to "recorder", supporting code-first development paths. Low-risk discrepancies are automatically absorbed; high-risk ones require confirmation.

See absorb-mode.md

Trace Health Check (--audit)

Detects completeness of the numbering system to prevent documentation maintenance debt accumulation. Checks AC coverage, F task closure, INS conversion, and isolated numbers.

See audit-mode.md

Code Trace Scan (--trace)

Scans for

@satisfies

@verifies

annotations in code, cross-validates with documentation, and updates the code location column in the trace matrix.

See trace-mode.md

Documentation Archive (--archive)

Supports archiving of all documentation types, controls documentation bloat, while preserving historical records for traceability:

Documentation Type	Archive Condition	Archive File
Requirements	Feature completed/obsolete	`archive/01-requirements-archive.md`
Design	Associated feature archived	`archive/02-system-design-archive.md`
Tests	Associated AC archived	`archive/03-test-cases-archive.md`
Tasks	>15 completed	`archive/04-dev-tasks-archive.md`

Cascading archiving is supported: Archiving F-001 can simultaneously archive associated design/test/task docs.

See archive.md

Sync Commands

Quick Check

bash

/devdocs-sync --check
# Output: Discrepancy report (display only, no write)

Full Sync

bash

/devdocs-sync
# Flow: Check → Display report → Confirm → Update documentation

Absorb Mode

bash

/devdocs-sync --absorb
# Flow: Check → Auto-absorb low-risk → Confirm high-risk → Generate report

Specified Scope

bash

/devdocs-sync T-01 T-02
# Sync only specific tasks

Output Files

Progress Report

Generates

docs/devdocs/00-progress-report.md

, including overall progress, discrepancy summary, and next-step recommendations.

Documentation Updates

Documentation	Update Content
`04-dev-tasks.md`	Task completion status, execution checklists
`03-test-cases.md`	Trace matrix status, test pass status
`01-requirements.md`	Feature implementation status (if status column exists)

Constraints

Check Constraints

Must read all DevDocs documentation before performing checks
Must generate a discrepancy report
Must request user confirmation before updating documentation (except low-risk in absorb mode)
Check results must be traceable (display check methods)

Update Constraints

Do not automatically delete documentation content, only mark statuses
Do not automatically modify code, only update documentation
Preserve original documentation structure
Record timestamp during updates

Absorb Mode Constraints

Low-risk absorption is limited to status field updates
High-risk absorption requires user confirmation
New content must specify associated numbers (AC/F/US)
Content with undetermined associations must be marked as "Pending manual processing"
Absorb operations must generate an absorption report

Security Constraints

Do not execute unknown shell commands
Use project-configured commands for test execution
Must confirm before large-scale updates

Skill Collaboration

Scenario	Collaborating Skill	Description
Development completed	`/devdocs-dev-workflow`	Called: Trigger --trace after task completion
After task completion	`/devdocs-dev-tasks`	Trigger sync after task execution
Test traceability	`/devdocs-test-cases`	Collaboration: Update trace matrix code locations
Requirement change	`/devdocs-feature`	Sync after new feature addition
Bug fix	`/devdocs-bugfix`	Update documentation after bug fix
Insight confirmation	`/devdocs-insights`	Sync after improvement suggestion confirmation
Project refactoring	`/devdocs-retrofit`	Full sync after refactoring

Deviation Fix Routing (Scheduler Function)

When discrepancies are detected, the report must assign clear fix routes to corresponding Skills:

Discrepancy Type	Fix Skill	Description
Missing/drifting design	`/devdocs-system-design`	Code has new interfaces but documentation not updated
AC without tests	`/devdocs-test-cases`	Acceptance criteria have no corresponding test cases
F without closed tasks	`/devdocs-dev-tasks`	Feature points have no associated development tasks
Code implemented but documentation lagging	`/devdocs-sync --absorb`	Status not updated, new content not recorded
Missing code locations in trace matrix	`/devdocs-sync --trace`	Annotations not scanned into matrix

Scheduler Principle: Discrepancy reports must not only list issues but also provide clear fix routes.

Recommended Call Sequence

Recommended sequence after task completion:

/devdocs-sync --trace    # 1. First update trace matrix code locations
        │
        ▼
/devdocs-sync            # 2. Then check overall status and update
  or --absorb            #    (absorb automatically includes trace step)

--trace
focuses on code annotation scanning,
--absorb
focuses on status absorption. They can be used independently or in combination.

Next Steps

After synchronization, execute the corresponding Skill according to the deviation fix routes in the progress report.

devdocs-sync

NPX Install

Tags

SKILL.md Content (Chinese)

Documentation Sync

Language Rules

Trigger Conditions

Operation Modes

Mode Comparison

Core Concepts

Relationship Between Documentation and Code

Synchronization Timing

Workflow

Mode Details

Absorb Mode (--absorb)

Trace Health Check (--audit)

Code Trace Scan (--trace)

Documentation Archive (--archive)

Sync Commands

Quick Check

Full Sync

Absorb Mode

Specified Scope

Output Files

Progress Report

Documentation Updates

Constraints

Check Constraints

Update Constraints

Absorb Mode Constraints

Security Constraints

Skill Collaboration

Deviation Fix Routing (Scheduler Function)

Recommended Call Sequence

Next Steps