intent-sync

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Intent Sync

Intent 同步

Synchronize implementation details back to Intent after development is complete. This makes Intent the true single source of truth.

在开发完成后，将实现细节同步回Intent。这让Intent成为真正的单一事实来源。

When to Use

使用场景

Use

/intent-sync

when:

Implementation is complete
All tests pass
User has confirmed the implementation works
You want to capture the finalized design in Intent

在以下情况使用

/intent-sync

：

实现已完成
所有测试通过
用户已确认实现可正常工作
你希望在Intent中记录最终设计

What Gets Synced Back

同步内容

During implementation, many details get finalized that weren't specified in the original Intent:

Category	Examples
Interfaces	API endpoints, function signatures, protocol definitions
Data Structures	Schema definitions, type definitions, model structures
Naming	Final class names, function names, variable conventions
Architecture	Module boundaries, dependency directions, layer structure
Configuration	Environment variables, config file formats, defaults
Error Handling	Error codes, error message formats, recovery strategies

在实现过程中，很多原本未在初始Intent中明确的细节会最终确定：

类别	示例
接口	API 端点、函数签名、协议定义
数据结构	模式定义、类型定义、模型结构
命名	最终类名、函数名、变量约定
架构	模块边界、依赖方向、层级结构
配置	环境变量、配置文件格式、默认值
错误处理	错误码、错误消息格式、恢复策略

Workflow

工作流

User confirms implementation is done
    ↓
Read original Intent file
    ↓
Scan implemented code for:
    - Public interfaces
    - Data structures
    - Key naming conventions
    - Architecture patterns
    ↓
Compare with Intent
    ↓
Identify gaps/differences
    ↓
Present changes for approval
    ↓
Update Intent with confirmed details
    ↓
Mark synced sections with timestamp

用户确认实现完成
    ↓
读取原始Intent文件
    ↓
扫描已实现的代码，查找以下内容：
    - 公共接口
    - 数据结构
    - 关键命名约定
    - 架构模式
    ↓
与Intent进行对比
    ↓
识别差异与遗漏
    ↓
提交变更以供批准
    ↓
使用已确认的细节更新Intent
    ↓
为已同步的部分标记时间戳

Sync Process

同步流程

Step 1: Gather Implementation Facts

步骤1：收集实现细节

Scan the codebase for finalized details:

Code Analysis:
├── Public APIs
│   ├── Endpoints (REST/GraphQL/RPC)
│   ├── Function signatures
│   └── Event definitions
├── Data Models
│   ├── Database schemas
│   ├── Type definitions
│   └── Config structures
├── Architecture
│   ├── Module structure
│   ├── Dependency graph
│   └── Layer boundaries
└── Conventions
    ├── Naming patterns
    ├── Error formats
    └── Logging standards

扫描代码库，获取最终确定的细节：

代码分析:
├── 公共API
│   ├── 端点（REST/GraphQL/RPC）
│   ├── 函数签名
│   └── 事件定义
├── 数据模型
│   ├── 数据库模式
│   ├── 类型定义
│   └── 配置结构
├── 架构
│   ├── 模块结构
│   ├── 依赖图
│   └── 层级边界
└── 约定
    ├── 命名模式
    ├── 错误格式
    └── 日志标准

Step 2: Compare with Intent

步骤2：与Intent对比

Identify what's new or different:

Status	Meaning	Action
New	Not in original Intent	Add to Intent
Changed	Different from Intent	Update Intent
Confirmed	Matches Intent	Mark as implemented
Removed	In Intent but not implemented	Remove or mark deferred

识别新增或变更的内容：

状态	含义	操作
新增	初始Intent中未包含	添加到Intent
变更	与Intent内容不同	更新Intent
已确认	与Intent匹配	标记为已实现
已移除	存在于Intent但未实现	移除或标记为延期

Step 3: Present for Approval

步骤3：提交批准

Use

AskUserQuestion

to confirm changes:

"The following details were finalized during implementation.
Should I sync them back to Intent?"

Interfaces:
- [x] POST /api/users - Create user (new)
- [x] UserSchema: added 'createdAt' field (changed)

Data Structures:
- [x] Config now uses YAML instead of JSON (changed)

Naming:
- [x] Service class renamed to UserService (changed)

使用

AskUserQuestion

确认变更：

"以下是实现过程中最终确定的细节。
是否需要将它们同步回Intent？"

接口:
- [x] POST /api/users - 创建用户（新增）
- [x] UserSchema: 添加了'createdAt'字段（变更）

数据结构:
- [x] 配置现在使用YAML而非JSON（变更）

命名:
- [x] 服务类重命名为UserService（变更）

Step 4: Update Intent

步骤4：更新Intent

Add a new section or update existing sections:

markdown

undefined

添加新章节或更新现有章节：

markdown

undefined

Finalized Implementation Details

最终实现细节

Synced on: YYYY-MM-DD From: [commit hash or version]

同步时间: YYYY-MM-DD 来源: [提交哈希或版本号]

API Interfaces

API接口

Endpoint	Method	Request	Response
/api/users	POST	`{name, email}`	`{id, name, email, createdAt}`
/api/users/:id	GET	-	`{id, name, email, createdAt}`

端点	方法	请求	响应
/api/users	POST	`{name, email}`	`{id, name, email, createdAt}`
/api/users/:id	GET	-	`{id, name, email, createdAt}`

Data Structures

数据结构

```typescript interface User { id: string; name: string; email: string; createdAt: Date; } ```

Module Structure

模块结构

``` src/ ├── api/ │ └── users.ts # User endpoints ├── services/ │ └── UserService.ts # Business logic ├── models/ │ └── User.ts # Data model └── config/ └── config.yaml # Configuration ```

``` src/ ├── api/ │ └── users.ts # 用户端点 ├── services/ │ └── UserService.ts # 业务逻辑 ├── models/ │ └── User.ts # 数据模型 └── config/ └── config.yaml # 配置文件 ```

Key Decisions Confirmed

已确认的关键决策

Decision	Final Choice	Rationale
Config format	YAML	Better readability for nested config
ID generation	UUID v4	Standard, no coordination needed

undefined

决策	最终选择	理由
配置格式	YAML	嵌套配置可读性更强
ID生成	UUID v4	标准化，无需协调

undefined

Output Format

输出格式

The sync adds or updates these Intent sections:

同步操作会添加或更新以下Intent章节：

New Section:

## Finalized Implementation Details

新增章节:

## 最终实现细节

Contains:

Sync timestamp
Source reference (commit/version)
Concrete interfaces
Concrete data structures
Final module structure
Confirmed decisions

包含：

同步时间戳
来源参考（提交/版本）
具体接口
具体数据结构
最终模块结构
已确认的决策

Updated Existing Sections

更新现有章节

Architecture diagrams updated to reflect reality
Data contracts updated with actual schemas
API specifications updated with real endpoints

架构图更新为反映实际情况
数据契约更新为实际模式
API规范更新为实际端点

Sync Markers

同步标记

Use markers to indicate sync status:

markdown

undefined

使用标记指示同步状态：

markdown

undefined

API Design

API设计

[!SYNCED] Last synced: 2024-01-15 from commit abc123

[!SYNCED] 最后同步时间: 2024-01-15 来自提交 abc123

Endpoints

端点

...


Or in tables:

| Component | Status | Last Synced |
|-----------|--------|-------------|
| User API | SYNCED | 2024-01-15 |
| Auth API | DRAFT | - |

...


或在表格中：

| 组件 | 状态 | 最后同步时间 |
|-----------|--------|-------------|
| 用户API | SYNCED | 2024-01-15 |
| 认证API | DRAFT | - |

Integration with Other Skills

与其他Skill的集成

/intent-interview     # Create Intent (initial)
    ↓
/intent-review        # Approve Intent
    ↓
/intent-plan          # Generate execution plan
    ↓
[Execute: TDD cycles]
    ↓
/intent-sync          # Write back confirmed details (THIS SKILL)
    ↓
/intent-check         # Verify consistency

/intent-interview     # 创建Intent（初始）
    ↓
/intent-review        # 批准Intent
    ↓
/intent-plan          # 生成执行计划
    ↓
[执行：TDD循环]
    ↓
/intent-sync          # 回写已确认的细节（本Skill）
    ↓
/intent-check         # 验证一致性

Best Practices

最佳实践

Sync after stability: Don't sync during active development; wait for confirmation
Preserve original intent: Keep original design rationale, add implementation details
Be specific: Include actual types, actual endpoints, actual names
Version reference: Always note which code version was synced
Incremental sync: Can sync multiple times as features stabilize

稳定后再同步：不要在活跃开发期间同步；等待确认后再操作
保留初始意图：保留原始设计理由，添加实现细节
具体明确：包含实际类型、实际端点、实际名称
版本参考：始终记录同步的代码版本
增量同步：可在功能稳定后多次同步

Example Session

示例会话

User: Implementation is done, tests pass. Please sync back to Intent.

用户: 实现已完成，测试通过。请同步回Intent。