implement-plan-preflight

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implement Plan Preflight

实施计划预检查

Execute the Preflight phase of the

/itp:go

workflow. Creates ADR and Design Spec artifacts with proper cross-linking and verification.

执行/itp:go工作流的预检查阶段。创建带有正确交叉链接和验证的ADR与设计规范工件。

When to Use This Skill

何时使用该Skill

Invoked by
```
/itp:go
```
command during Preflight phase
User asks to create an ADR for a feature
User mentions "design spec" or "MADR format"
Manual preflight verification needed

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

Preflight Workflow Overview

预检查工作流概述

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)

CRITICAL: Do NOT proceed to Phase 1 implementation until ALL preflight steps are complete and verified.

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阶段的实施。

Quick Reference

快速参考

ADR ID Format

ADR ID格式

YYYY-MM-DD-slug

Example:

2025-12-01-clickhouse-aws-ohlcv-ingestion

YYYY-MM-DD-slug

示例：

2025-12-01-clickhouse-aws-ohlcv-ingestion

File Locations

文件位置

Artifact	Path
ADR	`/docs/adr/$ADR_ID.md`
Design Spec	`/docs/design/$ADR_ID/spec.md`
Global Plan	`~/.claude/plans/<adj-verb-noun>.md`

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

Cross-Links (MANDATORY)

交叉链接（必填）

In ADR header:

markdown

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

In spec.md header:

markdown

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

在ADR头部：

markdown

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

在spec.md头部：

markdown

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

Execution Steps

执行步骤

Step P.1: Create Feature Branch (Optional)

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

Only if

-b

flag specified. See Workflow Steps for details.

仅当指定

-b

标志时执行。详情请参阅工作流步骤。

Step P.2: Create ADR File

步骤P.2：创建ADR文件

Create
```
/docs/adr/$ADR_ID.md
```
Use template from ADR Template
Populate frontmatter from session context
Select perspectives from Perspectives Taxonomy
Use Skill tool to invoke
```
adr-graph-easy-architect
```
for diagrams

创建
```
/docs/adr/$ADR_ID.md
```
使用ADR模板中的模板
从会话上下文填充前置元数据
从视角分类法中选择视角
使用Skill工具调用
```
adr-graph-easy-architect
```
生成图表

Step P.3: Create Design Spec

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

Create folder:
```
mkdir -p docs/design/$ADR_ID
```

Copy global plan:

cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md

Add ADR backlink to spec header

创建文件夹：
```
mkdir -p docs/design/$ADR_ID
```

复制全局计划：

cp ~/.claude/plans/<adj-verb-noun>.md docs/design/$ADR_ID/spec.md

在规范头部添加ADR反向链接

Step P.4: Verify Checkpoint

步骤P.4：验证检查点

Run validator or manual checklist:

bash

uv run scripts/preflight_validator.py $ADR_ID

Checklist (ALL must be true):

ADR file exists at
```
/docs/adr/$ADR_ID.md
```
ADR has YAML frontmatter with all 7 required fields
ADR has
```
**Design Spec**:
```
link in header
DIAGRAM CHECK 1: ADR has Before/After diagram (Context section)
DIAGRAM CHECK 2: ADR has Architecture diagram (Architecture section)
Design spec exists at
```
/docs/design/$ADR_ID/spec.md
```
Design spec has
```
**ADR**:
```
backlink in header

If any item is missing: Create it now. Do NOT proceed to Phase 1.

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

bash

uv run scripts/preflight_validator.py $ADR_ID

检查清单（所有项必须为真）：

ADR文件存在于
```
/docs/adr/$ADR_ID.md
```
ADR包含带有全部7个必填字段的YAML前置元数据
ADR头部包含
```
**Design Spec**:
```
链接
图表检查1：ADR（上下文部分）包含Before/After图表
图表检查2：ADR（架构部分）包含架构图表
设计规范存在于
```
/docs/design/$ADR_ID/spec.md
```
设计规范头部包含
```
**ADR**:
```
反向链接

如果有任何项缺失：立即创建。请勿进入第1阶段。

YAML Frontmatter Quick Reference

YAML前置元数据快速参考

yaml

---
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]
---

See ADR Template for full field descriptions.

yaml

---
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模板。

Diagram Requirements (2 DIAGRAMS REQUIRED)

图表要求（需包含2张图表）

⛔ MANDATORY: Every ADR must include EXACTLY 2 diagrams:

Diagram	Location	Purpose
Before/After	Context section	Shows system state change
Architecture	Architecture section	Shows component relationships

SKILL INVOCATION: Invoke

adr-graph-easy-architect

skill NOW to create BOTH diagrams.

BLOCKING GATE: Do NOT proceed to design spec until BOTH diagrams are embedded in ADR.

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

图表	位置	用途
Before/After	上下文部分	展示系统状态变化
Architecture	架构部分	展示组件关系

Skill调用：立即调用

adr-graph-easy-architect

Skill来创建这两张图表。

阻塞关卡：在两张图表都嵌入到ADR之前，请勿继续创建设计规范。

Reference Documentation

参考文档

ADR Template - Complete MADR 4.0 template
Perspectives Taxonomy - 11 perspective types
Workflow Steps - Detailed step-by-step guide

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

Validation Script

验证脚本

bash

undefined

bash

undefined

Verify preflight artifacts

验证预检查工件

uv run scripts/preflight_validator.py <adr-id>

Example

示例

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

---

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

---

Troubleshooting

故障排除

Issue	Cause	Solution
Validator fails	Missing ADR or spec	Create both files before running validator
Frontmatter invalid	Missing required fields	Check all 7 ADR fields and 5 spec fields
Diagram not rendering	graph-easy not installed	Run `brew install graph-easy`
Spec phase mismatch	Wrong phase value	Use: preflight, phase-1, phase-2, or phase-3
ADR status wrong	Manual status edit	Let workflow manage status transitions
Design folder missing	Wrong path structure	Use docs/design/YYYY-MM-DD-slug/spec.md

问题	原因	解决方案
验证器失败	缺少ADR或规范	运行验证器前先创建这两个文件
前置元数据无效	缺少必填字段	检查所有7个ADR字段和5个规范字段
图表无法渲染	graph-easy未安装	运行 `brew install graph-easy`
规范阶段不匹配	阶段值错误	使用：preflight, phase-1, phase-2, 或phase-3
ADR状态错误	手动编辑了状态	让工作流管理状态转换
设计文件夹缺失	路径结构错误	使用docs/design/YYYY-MM-DD-slug/spec.md