sync

Documentation Sync

Keep keel documentation consistent with actual implementation progress, detect deviations, and update status.

Quick Start

One-liner: Sync documentation with implementation progress and detect doc-code drift.

Most Common Usage: /sync(default trace+audit+check),/sync --archive(archive historical docs),/sync --back-propagate-prd(reverse-sync PRD mapping)

Not suitable? Verify alignment→/verify, extract lessons→/compound

Language Rules

• Support questions in Chinese and English
• Reply uniformly in Chinese
• Generate documentation in Chinese

Trigger Conditions

• After the user completes one or more development tasks
• When the user requests a check of documentation-code consistency
• When the user needs to update documentation progress
• Regular sync (e.g., at the end of a Sprint)

Run Modes

/sync                    → 默认：trace + audit + check，可带任务范围如 T-01 T-02
/sync --archive [requirements|design|tests|tasks] [--release v1.0.0]  → 归档历史 docs
/sync --back-propagate-prd  → 反向同步 prd 映射状态

Default Mode Changes

The original --trace、--audit、--check、--absorb has been merged into the default mode. When invoked without arguments, it automatically runs the trace → audit → check serial flow (audit/check depend on trace's output, so they are no longer independent user commands). The low-risk deviation absorption capability is incorporated into the default flow per the original absorb rules.

Internal Orchestration Interface (Not a User Entry Point)

• check: Built-in check in the default flow, no longer exposed as /sync --check
• absorb: Built-in low-risk absorption in the default flow, no longer exposed as /sync --absorb
• schema-drift: Migrated to /verify --schema-drift, sync only merges the drift results produced by verify in the health report

Mode Comparison

User Entry Point	Check	Auto Update	User Confirmation
/sync	✅ trace+audit+check	✅ Low-risk absorption/status update	✅ High-risk/before write
/sync --archive	✅ Archive conditions	✅ Archive files	✅ All
/sync --back-propagate-prd	✅ PRD mapping comparison	✅ Mapping status	✅ Before write

Core Philosophy

Relationship Between Documentation and Code

文档定义（计划）          代码实现（实际）
     │                        │
     ├── F-XXX 功能点    ←→   ├── 功能模块
     ├── AC-XXX 验收标准 ←→   ├── 业务逻辑
     ├── T-XX 开发任务   ←→   ├── 代码提交
     └── UT/IT/E2E 测试  ←→   └── 测试文件

Traceability Scope of Baseline Projects: When the project has docs/devdocs/00-baseline.md , the traceability matrix and coverage must be annotated with coverage_scope: post-baseline and state adoption_commit——traceability starts after the takeover point; existing code before the baseline is not within the F→US→AC→test chain. Failing to annotate this will misreport partial coverage as full-system coverage.

Core Principles：

• Documentation is the plan, code is the implementation
• Deviations are normal; the key is to sync promptly
• Sync should be bidirectional: documentation→code (guidance), code→documentation (record)

Sync Timing

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

Workflow

1. 读取 keel 文档
   │
   ▼
2. 扫描代码库（工作区状态）
   ├── 检查文件是否存在（Glob）
   ├── 运行测试（获取实时结果）
   ├── 检查未提交变更（git status）
   └── 参考提交记录（git log，辅助）
   │
   ▼
3. 对比分析
   ├── 任务完成状态
   ├── 测试覆盖情况
   └── 功能实现状态
   │
   ▼
4. 生成偏差报告
   │
   ▼
5. 询问用户确认更新
   │
   ▼
6. 更新文档

Important: The check is based onthe current workspace state, rather than relying solely on git commit history.

Mode Details

Default Mode (trace → audit → check automatic serial execution)

When called without parameters, the three-stage process is executed automatically:

1. trace stage: Validate the "Change Source" column of the traceability matrix (⛔ Does not scan code—there is no keel number in the code). See trace-mode.md
2. audit stage: Detect the completeness of the numbering system to prevent the accumulation of documentation maintenance debt. Check AC coverage, F task closure, INS conversion, orphan numbers,CON closure, and the age of unreported unclosed needs review items. See audit-mode.md
3. check stage: Output deviation report and health report; schema drift diagnosis is uniformly delegated to /verify --schema-drift, and this Skill only merges its results.

audit/check depends on the scan results of trace, so they are executed automatically in serial and are no longer independent subcommands.

Default Absorption Rules

Evolve from "inspector" to "recorder", supporting a code-first development path. Low-risk deviations are absorbed automatically; high-risk ones require confirmation. The trace step is included automatically.

See absorb-mode.md

Document Archiving (--archive)

Supports archiving of all document types, controls document bloat, and preserves historical records for traceability:

Document Type	Archive Condition	Archived File
Requirements	Feature completed/deprecated	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	More than 15 completed	archive/04-dev-tasks-archive.md

Cascading is supported during archiving: when archiving F-001, associated designs/tests/tasks can be archived at the same time.

See archive.md

Sync Commands

Full Sync (Default)

/sync
# 流程: trace 扫描 → audit/check → 自动吸收低风险 → 确认高风险/写入 → 更新文档

Output Files

Progress Report

Generate docs/devdocs/00-progress-report.md, including overall progress, deviation summary, and next-step recommendations.

Note: The default process will first return check results and wait for write confirmation; if the user does not confirm, no progress report is generated and no documents are updated.

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 there is a status column)

Constraints

Check Constraints

• All keel documents must be read before checking
• A deviation report must be generated
• The user must be asked for confirmation before updating documents(except for low-risk absorption mode)
• Check results must be traceable (show the check method)

Update Constraints

• Do not automatically delete document content; only mark the status
• Do not automatically modify code; only update documents
• Record timestamps when updating

Absorption Mode Constraints

• Low-risk absorption is limited to status field updates
• New content must specify an associated number (AC/F/US)
• Content whose association cannot be determined is marked as "pending manual handling"

Security Constraints

• Do not execute unknown shell commands
• The test command uses the command configured by the project

Skill Collaboration

Scenario	Collaborating Skill	Description
Development Complete	/dev-workflow	Called: triggers the trace phase after task completion
After Task Completion	/dev-tasks	Triggers synchronization after task execution
Test Traceability	/test-cases	Collaboration: updates traceability matrix code locations
Requirement Change	/feature	Synchronization after new feature addition
Bug Fix	/bugfix	Updates documentation after Bug fix
Insight Confirmation	/insights	Synchronization after improvement suggestion confirmation
Project Refactoring	/retrofit	Full synchronization after refactoring

Reference Materials

• absorb-mode.md - Absorption Mode Details
• audit-mode.md - Traceability Health Check
• trace-mode.md - Code Traceability Scan
• archive.md - Task Archiving Function
• examples.md - Usage Examples and Deviation Types

Deviation Repair Routing (Scheduler Function)

When a deviation is detected, the next repair Skill must be assigned in the report:

Deviation Type	Repair Skill	Description
Design Missing/Drift	/system-design	Code has new interfaces but documentation does not record them
AC Missing Tests	/test-cases	Acceptance criteria have no corresponding test cases
F Missing Task Closure	/dev-tasks	Feature points have no associated development tasks
Code Implemented but Documentation Lags	/sync	Status not updated, new content not registered, handled by default process as low-risk absorption
Traceability Matrix Code Location Missing	/sync	Code annotations not scanned into the matrix

Scheduler Principles: A deviation report cannot only list problems; it must provide clear repair routing.

Invocation Instructions

Run directly after task completion:

/sync            # trace → audit → check 自动串行 → 显示报告 → 确认更新

The default mode has merged trace, audit, check, and low-risk absorption into an automatic serial process, with no need for manual step-by-step invocation.

Batch Confirmation Optimization

Low-risk changes within the same session (status updates, progress statistics, etc.) are merged into document-level batch confirmations rather than confirmed one by one.

--back-propagate-prd mode

Back-propagates keel requirement changes to the prd mapping table. Executed only when explicitly invoked by the user.

/sync --back-propagate-prd
    |
    v
1. 定位 PRD requirements index（写路径）：固定为 docs/prd/requirements/index.md（单需求脚手架，扁平唯一路径）
   ├── 未找到 → 提示「无 prd 映射表，无需反向同步」
   └── 找到 → 继续
    |
    v
2. 读取 docs/devdocs/01-requirements.md 的 F-XXX 列表
    |
    v
3. 对比 index.md 映射表 vs 01-requirements.md
   ├── 新增 F-XXX（无对应 FR-XX 映射）→ 标注「keel 侧新增，无 prd 来源」
   ├── 废弃 F-XXX（已从 01-requirements.md 移除）→ 标注 mapping_status: removed（规范见 skills/prd/references/prd-mapping-status.md）
   └── 已有映射未变 → 保持
    |
    v
4. 更新 index.md 的「keel 映射」章节

Write Permission Boundary：

• Only the "keel mapping" section of index.md is allowed to be modified
• If the section does not exist, it may only be created at the end of the document; other sections must not be rearranged
• Only mapping status is written; FR content is not changed

Sub-Agent Summary Format

When this Skill runs as a sub-agent, return the following structured summary:

skill: sync
status: success | partial
summary:
  headline: "同步完成，健康度 85%，2 个偏差已修复"
  details:
    mode: default | archive | back_propagate_prd
    internal_operations: [trace, audit, check, absorb]
    trace_results:
      satisfies_found: X
      verifies_found: X
      coverage: "XX%"
      coverage_scope: "post-baseline | full"    # post-baseline 时必填 adoption_commit
      adoption_commit: ""                        # coverage_scope 为 post-baseline 时填
    audit_results:
      orphan_ids: []
      missing_tests: []
      health_score: "XX%"
    deviations:
      total: X
      auto_absorbed: X
      needs_confirm: X
blockers: []
output_files:
  - docs/devdocs/00-progress-report.md  # 仅确认写入后生成；检查-only 内部调用为空
new_ids: {}
next_recommended:
  skill: compound
  args: ""

Next Steps

After synchronization is complete, according to the progress report'sdeviation repair routing, execute the corresponding Skill.