---
name: tilelang-pass-design
description: "根据 Pass 需求生成 TileLang-Ascend Pass 设计文档（pass-design.md）。涵盖 Pass 定位分析（Phase 1/2归属、Pipeline位置、依赖关系）、IR 变换设计、C++ 实现方案、测试方案、风险分析等。触发关键词：设计 Pass、Pass 设计文档、写 Pass、实现 Pass、添加 Pass、新建 Pass、Pass 设计、开发 Pass。"
---

# TileLang-Ascend Pass 设计文档生成 Skill

---

## 1. 目标

根据 Pass 需求信息，生成一份完整的 TileLang-Ascend Pass 设计文档（`pass-design.md`），涵盖以下核心决策：

- **Pass 定位**：Phase 1 / Phase 2 归属、Pipeline 具体位置
- **依赖分析**：上游 Pass 输入、下游 Pass 输出、数据流传递
- **IR 变换设计**：输入 IR 结构、输出 IR 结构、变换逻辑
- **实现方案**：C++ 类设计、核心方法、Python Wrapper、Pipeline 集成
- **测试方案**：功能测试、依赖测试、边界测试
- **风险分析**：已知约束、常见错误、与其他 Pass 的交互

---

## 2. 输入要求

### 必需信息

| 字段 | 说明 |
|------|------|
| Pass 名称 | 如 `BufferReuseOptimizer`、`L0CLayoutOptimization` |
| 功能描述 | Pass 要解决的问题和目标 |
| IR 变换类型 | 修改 IR / 收集信息 / 验证 IR |
| 平台范围 | 平台无关 / Ascend 特定 |

**提问规则（必须严格遵守）**：
1. **每次只询问一个字段**：使用 `question` 工具时，`questions` 数组中只包含一个元素
2. **按表格顺序依次询问**：Pass 名称 → 功能描述 → IR 变换类型 → 平台范围
3. **已提供的字段跳过**：如果用户在初始请求中已提供某个字段的值，跳过该字段继续下一个

### 推荐信息

| 字段 | 说明 |
|------|------|
| 参考 Pass | 可参考的现有 Pass 名称 |
| 输入数据依赖 | Pass 需要哪些 attrs（如 `buffer_shapess`、`address_map`） |
| 输出数据供给 | Pass 产生哪些 attrs 供下游使用 |
| 性能目标 | Pass 对编译时间或生成代码性能的影响 |

---

## 3. 工作流程

### Phase 1：需求澄清

1. 解析用户提供的 Pass 需求信息
2. 检查必需字段是否完整
3. **按顺序逐一提问补全缺失字段**（每次只问一个）

### Phase 2：信息收集

1. **查阅 Pass 定位参考资料**：
   - `tilelang-pass-workflow-analyzer/references/pass-pipeline-overview.md` - Pipeline 架构
   - `tilelang-pass-workflow-analyzer/references/new-pass-placement-guide.md` - 定位决策流程
   - `tilelang-pass-workflow-analyzer/references/pass-dependency-graph.md` - 依赖关系

2. **查阅 Pass 实现参考资料**：
   - `tilelang-pass-analyzer/references/pass-registry-ascend.md` - 类似 Pass 实现
   - `tilelang-pass-analyzer/references/ir-examples.md` - IR 变换示例格式

3. **查阅本 skill 的实现模式参考**：
   - `references/pass-impl-patterns.md` - C++ 类模板、注册方式

### Phase 3：Pass 定位分析

按照 `new-pass-placement-guide.md` 的决策流程：

**Step 1：分析 Pass 功能**
- Pass 的主要功能是什么？
- Pass 修改 IR 还是收集信息？
- Pass 是平台无关还是 Ascend 特定？
- Pass 属于哪类优化（Lowering / 合法化 / 内存 / 流水线 / 同步 / 其他）？

**Step 2：分析依赖关系**
- Pass 需要哪些输入数据（attrs）？
- 这些数据由哪个 Pass 产生？
- Pass 产生哪些输出数据？
- 这些数据由哪个 Pass 使用？

**Step 3：确定阶段归属**
- DSL Lowering / IR 合法化 → Phase 1
- 硬件优化 / 内存优化 / 同步优化 → Phase 2
- 输入数据来自 Phase 1 → 可在 Phase 1 或 Phase 2
- 输入数据来自 Phase 2 → 必须在 Phase 2

**Step 4：确定具体位置**
- 依赖优先：Pass 必须在产生其输入数据的 Pass 后执行
- 供给优先：Pass 必须在使用其输出数据的 Pass 前执行
- 功能相邻：将 Pass 放在功能相似的 Pass 附近

### Phase 4：生成 pass-design.md

基于 `templates/pass-design-template.md` 模板，填充所有章节：

1. 概述
2. Pass 定位
3. IR 变换设计
4. 实现方案
5. 测试方案
6. 风险点与注意事项
7. 交付清单

### Phase 5：质量自检

按照 §5 中的自检清单逐项检查，确保文档质量。

### Phase 6：针对性修订

仅修正未通过自检的项目。信息确实不足的标注为「待确认」并说明原因。

### Phase 7：输出与关联引导

1. 将 `pass-design.md` 输出到当前目录或用户指定路径
2. 若文件已存在，询问是否覆盖
3. **关联引导**：提示用户可使用相关 skill 查看详细信息

---

## 4. 定位决策速查表

### 阶段归属速查

| Pass 功能特征 | 阶段归属 | 理由 |
|-------------|---------|------|
| DSL Lowering | Phase 1 | 将高级 DSL 转换为底层 IR |
| IR 合法化 | Phase 1 | 确保 lowered IR 符合规范 |
| 信息收集 | Phase 1 或 Phase 2 | 根据收集时机决定 |
| 硬件优化 | Phase 2 | 针对 Ascend 硬件特性优化 |
| 内存优化 | Phase 2 | 利用硬件内存层级优化 |
| 流水线优化 | Phase 2 | 多核流水线规划 |
| 同步优化 | Phase 2 | 多核同步策略 |

### 典型定位场景

| Pass 功能特征 | 推荐位置 |
|-------------|---------|
| IR 合法化检查 | Phase 1 末尾 |
| 新 Tile 操作 Lowering | Phase 1，`LowerTileOp` 后 |
| 内存优化 | Phase 2，`AscendStorageRewrite` 后，`AscendMemoryPlanning` 前 |
| 同步优化 | Phase 2，`AscendMemoryPlanning` 后，`AscendSyncInsert` 前 |
| 流水线优化 | Phase 2，`PipelinePlanning` 后 |
| 信息收集 | 根据收集内容类型决定 |

### 关键数据依赖

| 输入数据 | 产生 Pass | 阶段 |
|---------|-----------|------|
| `buffer scope` | `AscendInferBufferScope` | Phase 1 |
| `buffer_shapess` | `CollectBufferShapes` | Phase 1 |
| `address_map` | `AscendMemoryPlanning` | Phase 2 |
| `size_map` | `AscendMemoryPlanning` | Phase 2 |

---

## 5. 质量自检清单

生成 `pass-design.md` 后，逐项检查：

| # | 检查项 | 是否必须通过 |
|---|--------|-------------|
| 1 | **阶段归属有明确结论和理由**：不是「视情况而定」 | ✅ 必须 |
| 2 | **Pipeline 位置具体到步骤**：如「Phase 2 步骤 13，在 X Pass 后」 | ✅ 必须 |
| 3 | **依赖关系完整**：上游 Pass + 下游 Pass + 数据传递 | ✅ 必须 |
| 4 | **IR 变换有输入/输出示例**：伪 IR 格式，标注变化点 | ✅ 必须 |
| 5 | **C++ 类名和核心方法明确**：具体到类名和关键方法名 | ✅ 必须 |
| 6 | **Pipeline 集成代码完整**：包含集成到 `phase.py` 的代码片段 | ✅ 必须 |
| 7 | **无占位符或模糊描述**：无 `{placeholder}`、TODO、「待补充」 | ✅ 必须 |

**通过条件**：所有必须项全部通过。

---

## 6. 信息源优先级

| 优先级 | 信息源 | 用途 |
|--------|--------|------|
| 1 | `tilelang-pass-workflow-analyzer/references/` | Pass 定位、依赖分析 |
| 2 | `tilelang-pass-analyzer/references/` | Pass 实现参考、IR 变换示例 |
| 3 | `references/pass-impl-patterns.md`（本 skill） | C++ 类模板、注册方式 |
| 4 | `tilelang/engine/phase.py` | Pipeline 集成参考 |
| 5 | `src/transform/*.cc` | 典型实现模式（仅在追问时使用） |

**冲突处理**：当信息源之间矛盾时，以 `pass-pipeline-overview.md` 和 `new-pass-placement-guide.md` 为准。

---

## 7. 错误处理

| 场景 | 处理方式 |
|------|----------|
| 用户未提供 Pass 名称 | 提问补全 |
| 必需字段缺失 | 列出缺失项，逐一提问 |
| 无法确定阶段归属 | 分析依赖关系后给出推荐方案，标注为「需确认」 |
| 目标文件已存在 | 询问用户是否覆盖或另存 |
| Pass 功能过于复杂 | 建议拆分为多个子 Pass 分别设计 |

---

## 8. 完成报告与关联引导

文档生成完成后，输出以下格式的报告：

```
## Pass 设计文档生成报告

- Pass 名称: {Pass 名称}
- 阶段归属: {Phase 1 / Phase 2}
- Pipeline 位置: {具体位置描述}
- IR 变换类型: {修改 IR / 收集信息 / 验证 IR}
- 输出路径: {文件路径}

### 自检结果
1. 阶段归属明确: ✅ / ❌
2. Pipeline 位置具体: ✅ / ❌
3. 依赖关系完整: ✅ / ❌
4. IR 变换示例清晰: ✅ / ❌
5. C++ 实现方案明确: ✅ / ❌
6. Pipeline 集成代码完整: ✅ / ❌
7. 无占位符: ✅ / ❌

### 待确认项
- {列出需要用户进一步确认的内容}

### 后续步骤建议
1. 查看详细 Pass 工作流：使用 **tilelang-pass-workflow-analyzer** skill
2. 查看类似 Pass 实现：使用 **tilelang-pass-analyzer** skill
3. 开始实现 Pass：使用 **tilelang-pass-generate** skill
```

---

## 9. 参考资料

本 skill 依赖以下参考文件：

| 文件 | 路径 | 用途 |
|------|------|------|
| Pass 定位指南 | `tilelang-pass-workflow-analyzer/references/new-pass-placement-guide.md` | 定位决策流程 |
| Pipeline 架构 | `tilelang-pass-workflow-analyzer/references/pass-pipeline-overview.md` | 阶段划分、Pass 列表 |
| 依赖关系图 | `tilelang-pass-workflow-analyzer/references/pass-dependency-graph.md` | 数据流分析 |
| Pass 注册表 | `tilelang-pass-analyzer/references/pass-registry-ascend.md` | 类似 Pass 参考 |
| IR 示例 | `tilelang-pass-analyzer/references/ir-examples.md` | IR 变换格式 |
| 实现模式 | `references/pass-impl-patterns.md`（本 skill） | C++ 模板代码 |

---

## 10. 与其他 Skill 的关系

| Skill | 关系 | 使用时机 |
|------|------|----------|
| `tilelang-pass-workflow-analyzer` | 依赖 | 查阅 Pipeline 架构、Pass 定位、依赖关系 |
| `tilelang-pass-analyzer` | 依赖 | 查阅现有 Pass 实现细节、IR 变换示例 |
| `tilelang-pass-generate` | 后续 | 根据设计文档生成 Pass 代码（先输出 `pass-impl-skeleton.md` 框架，再落 C++/Python/Pipeline/测试） |