implement-plan-preflight

实施计划预检

执行 /itp:go 工作流的预检阶段。创建 ADR 和设计规格文档，并正确建立交叉链接和验证。

自我进化技能：此技能会在使用过程中不断改进。如果说明有误、参数发生偏移，或需要采用变通方案，请立即修复此文件，不要拖延。仅针对真实、可复现的问题进行更新。

何时使用此技能

• 在预检阶段由 /itp:go 命令调用
• 用户要求为某项功能创建 ADR
• 用户提到“设计规格”或“MADR 格式”
• 需要手动进行预检验证

预检工作流概览

P.1: Create Feature Branch (if -b flag)
         │
         ▼
P.2: Create ADR File (MADR 4.0)
         │
         ▼
P.3: Create Design Spec (from global plan)
         │
         ▼
P.4: Verify Checkpoint (MANDATORY)

重要：在所有预检步骤完成并通过验证之前，切勿进入第 1 阶段实施。

---

快速参考

ADR ID 格式

YYYY-MM-DD-slug

示例：2025-12-01-clickhouse-aws-ohlcv-ingestion

文件位置

工件	路径
ADR	/docs/adr/$ADR_ID.md
设计规格	/docs/design/$ADR_ID/spec.md
全局计划	~/.claude/plans/<adj-verb-noun>.md

交叉链接（必须）

在 ADR 标题中：

**Design Spec**: [Implementation Spec](/docs/design/YYYY-MM-DD-slug/spec.md)

在 spec.md 标题中：

**ADR**: [Feature Name ADR](/docs/adr/YYYY-MM-DD-slug.md)

---

执行步骤

步骤 P.1：创建功能分支（可选）

仅在指定 -b 标志时执行。详情请参阅工作流步骤。

步骤 P.2：创建 ADR 文件

1. 创建 /docs/adr/$ADR_ID.md
2. 使用 ADR 模板
3. 根据会话上下文填写 frontmatter
4. 从视角分类体系中选择视角

步骤 P.3：创建设计规格

1. 创建文件夹：mkdir -p docs/design/$ADR_ID
2. 复制全局计划：cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md
3. 在规格文档标题中添加指向 ADR 的反向链接

步骤 P.4：验证检查点

运行验证器或手动检查清单：

uv run scripts/preflight_validator.py $ADR_ID

检查清单（必须全部满足）：

• ADR 文件存在于 /docs/adr/$ADR_ID.md
• ADR 包含 YAML frontmatter，且具备全部 7 个必填字段
• ADR 标题中包含 **Design Spec**: 链接
• 图表检查 1：ADR 包含前后对比图（上下文部分）
• 图表检查 2：ADR 包含架构图（架构部分）
• 设计规格存在于 /docs/design/$ADR_ID/spec.md
• 设计规格标题中包含 **ADR**: 反向链接

如果缺少任何项目：立即补齐。切勿进入第 1 阶段。

---

YAML Frontmatter 快速参考

---
status: proposed
date: YYYY-MM-DD
decision-maker: [User Name]
consulted: [Agent-1, Agent-2]
research-method: single-agent
clarification-iterations: N
perspectives: [Perspective1, Perspective2]
---

完整字段说明请参阅 ADR 模板。

---

图表要求（必须包含 2 张图表）

⛔ 必须：每份 ADR 必须恰好包含 2 张图表：

图表	位置	用途
前后对比图	上下文部分	展示系统状态变化
架构图	架构部分	展示组件关系

阻断关卡：在 ADR 中嵌入这两张图表之前，切勿继续编写设计规格。

---

参考文档

• ADR 模板 - 完整的 MADR 4.0 模板
• 视角分类体系 - 11 种视角类型
• 工作流步骤 - 详细的逐步指南

---

验证脚本

# Verify preflight artifacts
uv run scripts/preflight_validator.py <adr-id>

# Example
uv run scripts/preflight_validator.py 2025-12-01-my-feature

---

故障排查

问题	原因	解决方案
验证器失败	缺少 ADR 或 spec	运行验证器前创建这两个文件
Frontmatter 无效	缺少必填字段	检查全部 7 个 ADR 字段和 5 个 spec 字段
Spec 阶段不匹配	阶段值错误	使用：preflight、phase-1、phase-2 或 phase-3
ADR 状态错误	手动编辑状态	让工作流管理状态转换
设计文件夹缺失	路径结构错误	使用 docs/design/YYYY-MM-DD-slug/spec.md

执行后复盘

此技能完成后，在结束前进行检查：

1. 命令是否成功？ — 如果没有，修复导致失败的指令或错误表。
2. 参数或输出是否发生变化？ — 如果底层工具的接口发生变化，更新用法示例和参数表以保持一致。
3. 是否需要变通处理？ — 如果你不得不临时变通（使用不同的标志、执行额外步骤），请更新此 SKILL.md，避免下次调用时需要采用相同的变通方法。

只有当问题真实存在且可复现时才进行更新，不要更新推测性问题。