Based on the operator specification and related context, generate a structured operator design document DESIGN.md, covering complete design content such as API mapping, data specifications, tiling strategy, and loop structure, to guide subsequent code implementation.
- Extract necessary content such as the operator name and specification information from user input
- If information is insufficient, ask the user follow-up questions step by step to supplement it
- Execute design plan generation according to the workflow (input validation → information collection → draft generation → confirmation → output)
- Output DESIGN.md to the current directory or a user-specified location
1. Required Information
| Item | Description |
|---|---|
| Input | Operator specification information (such as SPEC.md), reference implementation (optional), related context |
| Output | DESIGN.md, with the path being the current directory or a user-specified location |
2. Operator Information Acquisition
Extract the operator name and specification information from the input. If information is insufficient, ask the user follow-up questions step by step to supplement it.
3. Specification Field Check
After reading the operator specification information, check field completeness:
Required fields (if missing, report an error and exit)
| Field | Purpose |
|---|---|
| Operator name | Directory name, file naming |
| Mathematical formula | API mapping, computation logic design |
| Input specification | Data specification design, Tiling strategy |
| Output specification | Data specification design |
Suggested fields (guide the user to supplement when missing)
| Field | Purpose | Handling when missing |
|---|---|---|
| Typical configuration | Verification plan, performance target | Guide the user to supplement |
| Algorithm description | Loop/Tiling design for complex operators | May be omitted for simple operators; prompt to supplement for complex operators |
| Dynamic axis range | Tiling/Loop strategy reference | Use the default range |
Handling when typical configuration is missing
Guide the user to provide it; if the user skips, recommend a default configuration based on the dynamic axis range, and after confirmation supplement it into the operator specification information.
The typical configuration uses a 7-column format:
| Configuration name | Type | Priority | Parameters | Input Shape | Output Shape | Description |
|---|
4. Workflow
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 1：输入验证与特征分析 │
├───────────────────────────────────────────────────────────────────┤
│ 1. 读取算子规格信息 │
│ 2. 验证必须字段完整性 │
│ 3. 分析算子特征： │
│ - 类型判断：含 matmul → Cube；仅逐元素/归约 → Vector │
│ - 复杂度：简单（≤5 步）/ 中等（5-15 步）/ 复杂（>15 步） │
│ - Loop 判断：按 references/quick_ref.md §2.1 判据表逐条检查 │
│ - 动态 shape：检查规格信息中是否声明动态轴 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 2：信息收集 │
├───────────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────────────────────────┐ │
│ │ 若输入已包含约束、参考实现等信息，优先复用 │ │
│ │ 否则自行搜索补充 │ │
│ └──────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌───────────────────┐ ┌────────────────────┐ │
│ │ 知识库查询 │ │ 动态查询文档 │ │
│ │ - references/ │ │ - 搜索 docs/ │ │
│ │ quick_ref.md │ │ - 查找类似算子示例 │ │
│ │ - 核心原则速查 │ │ - 验证 API 规格 │ │
│ └───────────────────┘ └────────────────────┘ │
│ │ │ │
│ └──────────┬─────────────┘ │
│ ▼ │
│ 合并生成信息 │
│ 成功标准：每个公式步骤均找到对应 PyPTO API 或标记为 unsupported │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 3：生成 DESIGN.md │
├───────────────────────────────────────────────────────────────────┤
│ 基于模板 templates/design-template.md 生成完整 DESIGN.md 草稿 │
│ 包含全部 9 个章节 │
│ 成功标准： │
│ ✓ DESIGN.md 包含全部 9 个章节标题 │
│ ✓ §2 API 映射表每步均有对应 PyPTO API（或标记 unsupported） │
│ ✓ §5 Loop 结构已按场景 A 或场景 B 填写（无空白占位） │
│ ✓ 无残留 {placeholder} 占位符 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 4：质量自检 │
├───────────────────────────────────────────────────────────────────┤
│ 按 5 项检查表逐项检查： │
│ □ API 映射是否具体 │
│ □ Tiling / Loop 是否说明理由 │
│ □ 验证方案是否覆盖典型配置 │
│ □ 风险点是否具体 │
│ □ 是否存在空话或占位符 │
│ │
│ 输出：通过 / 不通过 + 修复建议 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 5：定向回修（如需要） │
├───────────────────────────────────────────────────────────────────┤
│ 仅修复不通过项，不重写整篇文档 │
│ 保留已通过章节；信息不足时写”待确认”，不得编造结论 │
└───────────────────────────────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────────┐
│ 阶段 6：输出文件 │
├───────────────────────────────────────────────────────────────────┤
│ 自检通过后输出：DESIGN.md │
│ 如回修后仍有关键未决项，向用户确认缺口 │
│ 如果文件已存在 → 通过 AskUserQuestion 询问是否覆盖 │
└───────────────────────────────────────────────────────────────────┘
5. DESIGN.md Section Structure
DESIGN.md contains 9 sections; the template file is located at: templates/design-template.md
| Section | Content | Information source |
|---|---|---|
| 1. Overview | Operator name, function, mathematical formula, data flow diagram | Operator specification (basic information, data flow diagram) |
| 2. API Mapping Design | Formula decomposition, PyPTO API mapping table, computation steps | references/quick_ref.md + docs/ |
| 3. Data Specification Design | Input/Output dataclass, intermediate Tensor, data format, JIT configuration | Operator specification (data specification) |
| 4. Tiling Strategy | Operator type determination, TileShape configuration, basis for settings | references/quick_ref.md + docs/ |
| 5. Loop Structure Design | Whether a loop is needed, static/dynamic axis handling, tail block handling | references/quick_ref.md + docs/ |
| 6. Verification Plan | Golden function design, test cases (based on typical configurations), precision standards | Operator specification (precision requirements, typical configurations) |
| 7. Performance Metrics and Out-of-the-Box Configuration | Performance targets, TileShape, pass_options, runtime_options | references/quick_ref.md + docs/ |
| 8. Risk Points and Precautions | Known constraints, common error avoidance, special scenario handling | Knowledge base + docs/ |
| 9. Deliverables List | Directory structure, file list, naming conventions, generation order | Fixed template |
Section 5 (Loop Structure Design) Always generate: use scenario A template when no loop is needed, and scenario B template when a loop is needed.
6. Quality Self-Check and Targeted Rework
After generating the DESIGN.md draft, you must check item by item according to the following 5-item checklist:
-
Whether the API mapping is specific
- Write out the explicit PyPTO API name for each key step
- Do not use vague expressions such as "related API" or "appropriate API"
-
Whether Tiling / Loop explains the rationale
- Not only give the conclusion, but also explain why it is designed this way
- At least clearly state the applicable conditions, basis for judgment, or limitations
-
Whether the verification plan covers typical configurations
- At least cover the main typical configurations in the operator specification
- Do not only write "to be verified later" or "supplement as needed"
-
Whether the risk points are specific
- Each risk point must explain the triggering scenario or impact
- Do not only write "pay attention to performance issues" or "pay attention to boundary cases"
-
Whether there is empty talk or placeholders
- Must not remain
{placeholder}、TODO、待补充 - Do not include large passages of vague descriptions such as "usually/generally/adjust as needed/may be modified according to the situation"
- Must not remain
When outputting the check results, you must provide:
- Pass / Fail
- Reason for failure
- Fix suggestion
If there are failed items, only fix the failed sections, and do not rewrite the entire document.
Rework requirements:
- Preserve the content of sections that have passed
- Only supplement the missing APIs, rationale, verification configurations, and risk explanations
- If the information is insufficient, explicitly write "to be confirmed", and do not fabricate definitive conclusions
Self-check pass conditions:
- At least 4 of the 5 checks pass
- "Whether the API mapping is specific" must pass
- "Whether Tiling / Loop explains the rationale" must pass
- No placeholders may remain
7. Knowledge Base Usage Specification
Knowledge base files
| File | Content | When to use |
|---|---|---|
| references/quick_ref.md | Quick reference for core principles of tiling / loop / runtime | Read during Stage 1 feature analysis + Stage 2 information collection |
Detailed API mapping, Tiling rules, Loop strategy, performance parameters, and other information are dynamically obtained through searching
docs/.
Source priority
docs/（官方文档）→ 规则来源，API 规格验证
↓
输入中附带的约束限制、参考实现等信息 → 用户提供
↓
models/（生产代码）→ 实践参考
↓
examples/（教学示例）→ 教学参考
Knowledge base files are pre-organized experience summaries, and their accuracy must be verified in docs/ when used. When knowledge base content is inconsistent with docs/, docs/ takes precedence.
8. Typical configuration usage
Uses of the typical configurations in the operator specification in DESIGN.md:
| Purpose | Configuration used | Corresponding DESIGN.md section |
|---|---|---|
| Verification plan | All typical configurations (performance + functional) | §6 Verification plan |
| Performance target | Performance configurations (Performance_P0, Performance_P1) | §7 Performance metrics |
| Tiling reference | Shape of Performance_P0 | §4 Tiling strategy |
Typical configuration 7-column format：
| Configuration name | Type | Priority | Parameters | Input Shape | Output Shape | Description |
|---|
Field description：
- Type：
功能or性能. Performance-type configurations also need functional correctness verified first - Priority: P0 (core/required) > P1 (important/recommended) > P2 > P3
- Verification order: Performance_P0 → Performance_P1 → Functional_P0 → Functional_P1
9. Error handling
| Scenario | Handling method |
|---|---|
| Missing operator specification information | Exit with an error, prompting to provide requirement information first |
| Missing required field | List the missing fields and guide the user to supplement them |
| Missing typical configuration | Guide the user to provide or confirm the recommended configuration |
| Knowledge base query miss | Dynamically search docs/ and models/ to supplement information |
| docs query failure | Generate based on AI knowledge, marked "requires manual confirmation" |
| DESIGN.md already exists | Through AskUserQuestion ask whether to overwrite |
Fault tolerance strategy：
- When non-required fields are missing, continue generation using default values
- When required fields are missing, clearly inform the user what is needed
- When the knowledge base cannot match, fall back to generation based on AI knowledge, and mark the corresponding sections with "requires manual confirmation"
10. Completion report
After file generation is complete, first self-check the following items, then present the report to the user:
- DESIGN.md contains all 9 sections
- §2 API mapping has no unsupported items (if any, list them in the report)
- §5 Loop conclusion is consistent with Stage 1 feature analysis
- Whether API mapping is specific: pass / fail
- Tiling / Loop rationale: pass / fail
- Verification plan coverage: pass / fail
- Specificity of risk points: pass / fail
- Empty talk / placeholders: pass / fail
✅ 设计文档已生成:
• DESIGN.md
• API 映射：{N} 步全部映射 / {M} 步标记 unsupported
• Loop 结论：{不需要 / 需要 pypto.loop / 需要 loop_unroll}
• 质量检查：
- API 映射：{通过 / 不通过}
- Tiling / Loop 理由：{通过 / 不通过}
- 验证方案覆盖：{通过 / 不通过}
- 风险点具体性：{通过 / 不通过}
- 空话 / 占位符：{通过 / 不通过}
If the self-check pass conditions are not met, output:
⚠️ 当前文档为草稿，需人工补强：
• {问题 1}
• {问题 2}