Announce at start: "I am using the arkweb-design-alignment skill to perform implementation design alignment."
Execution Mode
Mode A: Subagent Mode
As an independent subagent, scheduled by arkweb-architect The main Session provides the design document path and code repository path, and the subagent performs difference comparison and requests decisions from the user one by one.
Mode B: Independent Invocation
When invoked directly by the user, the following must be provided:
- Design document path (requirement.md + design.md)
- Directory where the implementation code resides
- Requirement analysis report path (optional)
If not provided, the skill will automatically search for documents under {DOCS_REPO}/docs/features/{feature-name}/ .
Input
| Input Item | Path | Required | Description |
|---|---|---|---|
| requirement.md | {docs_dir}{feature-name}/{date}-{feature}-requirement.md |
Yes | Requirement baseline review document |
| design.md | {docs_dir}{feature-name}/{date}-{feature}-design.md |
Yes | Architecture design document |
| spec.md | {docs_dir}{feature-name}/spec.md |
No | Unified specification document (supplementary reference) |
| analysis.md | {analysis_dir}{date}-{feature}-analysis.md |
No | Code analysis report |
| Implementation code directory | {WORK_HOME}/ |
Yes | Code repository root path |
Execution Steps
Step 1: Collect information from three parties and identify differences
Read all input documents in parallel and extract all information needed for comparison:
1. Read requirement.md + design.md
→ 提取:接口定义、API 签名、数据结构、流程描述、约束条件
2. Read spec.md(如存在)
→ 提取:结构化接口规格、参数约束、行为场景
3. Read analysis.md(如存在)
→ 提取:实现步骤清单、代码探查结果
4. 在代码仓库中搜索实现代码
→ 使用 Grep + Read 查找头文件和实现文件
→ 提取实际的类定义、方法签名、数据结构
Comparison Dimension:
| Design Element | Comparison Method | Difference Type |
|---|---|---|
| Interface/API Signature | API definitions in the design document vs header files in the actual code | Signature difference |
| Data structure/enum | Field definitions in the design document vs actual struct/enum | Field difference |
| Class/inheritance relationship | Class diagram in the design document vs actual class definitions | Structural difference |
| Method list | Method list in the design document vs actual method list | Addition/removal difference |
| Parameters/return values | Parameter descriptions in the design document vs actual parameter types | Type difference |
| Process/state machine | Flowcharts in the design document vs actual control flow | Logic difference |
| Error codes/exceptions | Error definitions in the design document vs actual error handling | Exception difference |
| Feature Flag | Switch planning in the design document vs actual flag definitions | Configuration difference |
| Multi-language binding scope | Binding requirements in the design document vs actual binding coverage | Scope difference |
| Module division | Module boundaries in the design document vs actual file organization | Architecture difference |
Execution method: For each interface/class/method described in the design document, use Grep + Read to find the corresponding implementation in the actual code and compare item by item.
Collect all differences into a list, preparing to enter the user decision step.
Step 2: Show differences to the user one by one and request decisions
For each difference point, use the AskUserQuestion tool to present it to the user and request a decision.Show only one difference point at a time, and wait for the user's explicit reply before handling the next one.
Display format:
差异 {N}/{Total}: {差异标题}
设计文档描述:
{设计文档中的原始描述,包含章节引用}
实际实现:
{代码中实际的实现情况}
差异分析:
{简要说明差异的原因和影响}
请选择处理方式:
A) 接受实现 — 将设计文档修改为与实现一致(回写设计文档)
B) 要求重做 — 按设计文档的要求重新实现代码(启动 coder+reviewer)
C) 暂时搁置 — 记录为遗留事项,后续处理
Explanation of user decision options:
| Option | Meaning | Follow-up action |
|---|---|---|
| A) Accept implementation | The implementation is reasonable, and the design document needs to be updated | Directly Edit the original section of the design document |
| B) Request rework | The implementation deviates from the design intent, and the code needs to be corrected | Start the coder → reviewer loop |
| C) Temporarily shelve | Cannot decide immediately, handle later | Record in the pending items list |
Step 3: Handle by category according to user decisions
Collect user decisions for all difference points and group them by handling method:
决策 A(接受实现)的差异数量: {a_count}
决策 B(要求重做)的差异数量: {b_count}
决策 C(暂时搁置)的差异数量: {c_count}
Step 4: Execute user decisions
For differences with decision A (accept implementation): directly write back to the design document
Key principle: directly modify the original section of the design document, rather than appending an explanation at the end.
For each difference with decision A:
- Use Read to locate the corresponding original section in the design document
- Use Edit modify in placethe original description so that it is consistent with the actual implementation
- Do not append a summary section at the end, and only annotate the source of modification at the modified location
Modification principles:
- Only modify paragraphs/sections that are inconsistent with the implementation, without changing the overall document structure
- Maintain the writing style and terminology of the original document
- Use Edit for precise replacement, not overwriting the entire document
- Annotate the source and reason of each change via inline comments
For differences with decision B (request rework): start the coder+reviewer rework loop
Integrate all decision B differences into rework requirements and pass them to the arkweb-coder Agent:
请根据以下用户决策,重新实现代码以对齐设计文档。
需求设计文档路径:{requirement_path}
设计文档路径:{design_path}
用户要求重做的差异点:
差异 1: {差异标题}
设计文档要求:{设计文档的原始描述}
当前实现:{当前代码的实现}
需要修改为:{与设计文档一致}
差异 2: ...
请按以下步骤执行:
1. 读取需求设计文档中对应的章节
2. 使用 TodoWrite 创建修复任务列表
3. 逐个修改代码文件以对齐设计文档
4. 修改完成后输出变更文件清单
After rework is complete, start the arkweb-reviewer Agent to review only the files involved in the rework.
If the review still has BLOCKER/CRITICAL issues, continue the fix loop (up to 3 rounds).
For differences with decision C (temporarily shelve): record them as pending items
Do not modify the design document, and do not modify the code. Only list them in the final summary.
Step 5: Difference alignment loop check
如果有决策 B 的差异触发了重做:
→ 重新执行 Step 1(重新收集信息并比对)
→ 检查重做是否引入了新的差异
→ 如果有新差异 → 回到 Step 2(向用户展示新差异)
→ 如果无新差异 → 退出循环
如果无决策 B 的差异:
→ 直接退出循环,所有差异已处理完毕
Loop protection:
max_diff_rounds = 5
如果差异对齐循环超过 5 轮:
→ 向用户报告仍有未对齐的差异
→ 列出剩余差异
→ 建议人工介入
Step 6: Output difference handling summary
After completing the handling of all differences, output a summary to the user:
═══════════════════════════════════════════
设计差异对齐完成
═══════════════════════════════════════════
需求文档: {requirement_path}
设计文档: {design_path}
差异统计:
总差异点: {N}
用户决策分布:
接受实现(已回写设计文档): {A_count} 处
要求重做(已重新实现): {B_count} 处
暂时搁置(记录为遗留): {C_count} 处
已直接修改的设计文档章节:
- {章节1} ({差异标题}): {修改摘要}
- {章节2} ({差异标题}): {修改摘要}
已重新实现的代码文件:
- {文件1}: {修改说明}
- {文件2}: {修改说明}
遗留事项(用户选择搁置):
- [ ] {差异标题}: {设计要求 vs 实际实现}
═══════════════════════════════════════════
Process status tracking
Use TodoWrite to maintain progress:
Step 1: 收集信息并识别差异 [pending / in_progress / completed]
Step 2: 向用户展示差异并决策 [pending / in_progress / completed]
Step 3: 分类处理 [pending / in_progress / completed]
Step 4: 执行用户决策 [pending / in_progress / completed]
Step 5: 差异对齐循环检查 [pending / in_progress / completed]
Step 6: 输出总结 [pending / in_progress / completed]
└─ 差异决策轮次 (1~5) [追踪当前是第几轮差异对齐]
Exception handling
No differences
- Report to the user that "the design document is fully consistent with the implementation, no alignment needed"
- Exit directly
Maximum rounds reached but differences remain
- Stop the difference alignment loop
- Report to the user that there are still unaligned differences
- List the remaining differences and suggested handling methods
- Preserve the results of completed difference handling
Design document does not exist
- Report the path error to the user
- Indicate the correct document path
No implementation found in the code repository
- Report to the user that the corresponding implementation code was not found
- List the interfaces/classes defined in the design document but not implemented
- Suggest completing the code implementation first