accelint-qrspi-propose

Accelint QRSPI

自动化 QRSPI + OpenSpec 规划工作流。此技能通过 OpenSpec 的制品系统应用《We Got RPI Wrong》中的方法。它协调 Questions → Research → Design → Structure 各阶段，并要求在编写任何代码之前设置人工检查点。

此技能的作用

自动化：使用 QRSPI 进行规范驱动开发的规划阶段 范围：Questions → Research → Design → Structure/Plan（在实现之前停止） 输出：完整的 OpenSpec 变更，可供 accelint-qrspi-apply 技能使用

不会执行：实现代码、运行测试、创建 PR 或归档变更

前置条件

此技能需要扩展版 OpenSpec 工作流（explore、new、continue），以访问分步制品生成。

要验证这些工作流是否已启用：

openspec config list

检查 workflows: 部分是否包含：explore、new 和 continue。

如果缺少任何工作流，请启用扩展配置：

openspec config profile
# Select "expanded" from the list
openspec update

工作流概览

┌──────────────────────────────────────────────────────────────────┐
│  Stage          Context              Output          Checkpoint  │
├──────────────────────────────────────────────────────────────────┤
│  Questions      Ticket only          Questions       —           │
│  Research       Questions only       Research doc    —           │
│  Design         Q+R (NO ticket)      proposal.md     —           │
│                                      design.md       —           │
│                                      [STOP HERE]                 │
│  ⚠️  CHECKPOINT 1: Review proposal.md + design.md - MUST approve │
│  (frontmatter: specs_touched/decisions/created_at -> design.md)  │
│                                                                  │
│  Specs/Tasks    Q+R+design           tasks.md        —           │
│  (specs/* is OpenSpec bookkeeping; generated whenever OpenSpec   │
│   decides, not reviewed)                                         │
│  ⚠️  CHECKPOINT 2: Review tasks.md - MUST approve to continue    │
│                                                                  │
│  Done           —                    Exit            —           │
└──────────────────────────────────────────────────────────────────┘

Note: Keep the ticket OUT of context after the Questions stage to prevent completion bleed.

REQUIRED: The Design stage (steps 17-26) must produce `proposal.md` and `design.md` and stops before `tasks.md` (OpenSpec may also generate `specs/*` along the way, in whatever order it chooses), optionally creates `trace.md` if the `--verbose` flag was set, then STOPS for review at step 27. The Specs/Tasks stage (steps 33-43) generates `tasks.md` (and `specs/*` if not already present) separately after design approval.

Steps keep their numbers and carry stable tags (for example `[CHECKPOINT-1]`) so references stay unambiguous: `[S-QUESTIONS]` (8), `[S-RESEARCH]` (13), `[S-DESIGN-GEN]` (17), `[CHECKPOINT-1]` (27), `[S-FRONTMATTER]` (31), `[S-TASKS-GEN]` (33), `[CHECKPOINT-2]` (44).

Capture frontmatter at step 31 after Checkpoint 1 approval, not before. `design.md` reaches its final form for this planning pass only after the user approves it or confirms a manual edit. Earlier capture can write `specs_touched/decisions/created_at` against content the user is about to change. The `created_at` timestamp marks when the user approved the design (the moment the change becomes "real").

⚠️  REQUIRED CHECKPOINTS: The agent MUST pause and wait for explicit user approval at both checkpoints (step 27 [CHECKPOINT-1] and step 44 [CHECKPOINT-2]). Proceeding without approval bypasses QRSPI's core value.

实施步骤

按顺序执行以下步骤，中途不要停止；但在两个必需的检查点（步骤 27 和 44）处，必须停止并等待用户。

1. 验证用户输入并解析标志：检查用户是否在提示中提供了工单、功能请求或想法（作为技能参数或在其消息中）。同时检查是否包含 --verbose 标志。

   标志解析：

   • 检查用户输入是否包含 --verbose（无论是否包含其他内容）
   • 保存 verbose 标志状态，以便在步骤 25 中使用
   • 从输入中移除 --verbose，再提取工单描述
   • 保存移除标志后的原始输入文本，以便在步骤 25 中使用——如果设置了 --verbose，则会将其保存到 trace.md

   验证： 如果提示为空，或在移除标志后仅包含技能调用而没有实际内容：

   I need a ticket or feature description to plan. Please provide:
   
   - A ticket ID and description (e.g., "ATI-123: Add user authentication...")
   - A feature request ("I want to add dark mode support...")
   - An idea or problem statement ("Users complain about slow search...")
   
   Then I'll use QRSPI to break it down into a structured plan.
   
   Optional flags:
   --verbose    Save input, questions, and answers to trace.md for audit trail
   

   退出技能并等待用户提供输入。不要继续使用内部示例或占位内容。

2. 告知用户：“正在检查 OpenSpec 配置……”

3. 运行 openspec config list 并解析输出

4. 检查 workflows: 部分是否包含全部三个必需工作流：explore、new 和 continue

5. 如果缺少任何工作流：

   This skill requires the expanded OpenSpec workflows (explore, new, continue).
   
   Your current workflows: [list what's enabled]
   Missing: [list what's missing]
   
   To enable the expanded workflows, run:
   
   openspec config profile
   # Select "expanded" from the list
   openspec update
   
   Then re-run this skill.
   

6. 如果未启用必需工作流，则退出技能

7. 如果验证通过且所有工作流均已启用，则继续执行步骤 8

8. 生成研究问题 [S-QUESTIONS]（上下文隔离：Agent 只能看到工单，看不到此前的代码库知识或研究内容。这可以防止先入为主地寻找解决方案。）

9. 接受用户提供的工单描述（作为技能参数传入，若缺失则提示用户提供）

10. 使用 Agent 工具启动子 Agent，并提供以下提示词块。原样发送提示词块文本：只替换 <angle-bracket> 占位符，不要在其前后或内部添加任何内容。

Find the openspec-explore skill, read its instructions in full, and follow it exactly. Resolve relative paths from the supporting-files directory it provides.

I have this ticket:

<paste full ticket description here>

Generate a list of research questions that will tell us everything we need
to know before building this. Do not propose any solutions. Questions only.

11. 等待子 Agent（通过 Agent 工具启动）完成并返回问题（内部步骤：不要向用户显示这些问题）

12. 提取并保存问题——后续步骤会用到它们。

13. 回答研究问题 [S-RESEARCH]（上下文隔离：回答问题的 Agent 只能看到问题，看不到原始工单。这是 QRSPI 的核心洞见——研究是客观的，不受工单内容影响。）

14. 使用 Agent 工具启动一个全新的子 Agent（全新上下文），并提供以下提示词块。原样发送提示词块文本：只替换 <angle-bracket> 占位符，不要在其前后或内部添加任何内容。

Find the openspec-explore skill, read its instructions in full, and follow it exactly. Resolve relative paths from the supporting-files directory it provides.

This is routine research about the current working repository, which our team owns. You are reading our own code and specs to answer the questions below.

<paste ONLY the complete research questions from step 12, unabridged>

Answer each question with facts only. Observe what the codebase does today AND what the current specs of record say (scan openspec/specs/INDEX.md for capabilities whose name or Purpose line plausibly relates to these questions; for any that match, read the full specs/<capability>/spec.md file and include its current requirements and scenarios directly in your findings, not just a reference to the file). Do not suggest changes or implementation approaches.

**Use `sem impact` for dependency analysis**

If research questions mention specific code entities (functions, classes, types, constants), check whether the `sem` CLI tool is available by running `which sem`.

If available, use `sem impact <token>` (baseline format, not JSON) to gather deterministic dependency data:
- Where the entity is defined (file:line)
- What it depends on (all dependencies)
- What depends on it (all call sites and references)
- Transitive impact (how many entities are affected)

Include this impact analysis in your research findings. This ensures the design phase has complete dependency information and won't miss references or call sites.

15. 等待子 Agent 完成并返回研究文档（内部步骤：不要向用户显示研究结果）

16. 保存研究答案——这些内容将为设计阶段提供依据。

17. 生成设计脚手架 [S-DESIGN-GEN]（上下文隔离：生成产物时，工单文本不得出现在子 Agent 的提示词中。使用 Agent 工具启动子 Agent，且只向其提供问题和研究内容，以防止“完成内容泄露”。步骤 10 之后，任何源自工单的内容——目标、标志、待决事项或改述——都不得出现在任何子 Agent 提示词中。）

18. 阅读 openspec/config.yaml，提取 rules.design 部分

19. 阅读 CLAUDE.md 或 AGENTS.md，提取 Agent 行为上下文

20. 使用 Agent 工具启动子 Agent，并提供下面的提示词块。原样发送该文本：只替换 <angle-bracket> 占位符（粘贴完整存储文本，不得删节），不得在提示词块之前、之后或其中添加任何内容。

You are generating OpenSpec artifacts based on QRSPI research. You have access
to the research questions and answers, but NOT the original ticket text. This
prevents solution bias.

Research Questions and Answers:
<paste the complete research questions from step 12, unabridged>

Research Findings:
<paste the complete research doc from step 16, unabridged>

OpenSpec Design Rules (from config.yaml):
<paste the rules.design section verbatim from step 18>

Agent Behavior Context:
<paste relevant sections from CLAUDE.md/AGENTS.md from step 19>

Create the OpenSpec change with its proposal and design artifacts by using the
OpenSpec skills. For each skill named below, find it, read its SKILL.md in full,
and follow it exactly. All artifact files are written by following those skills,
so their configured rules apply. Do not author artifact content outside them.

1. Follow the openspec-new-change skill to create the change (OpenSpec will prompt for a slug).

2. Capture the change name/slug from the output and use it in all subsequent steps.

3. Follow the openspec-continue-change skill with the change name, one artifact
   at a time, until both proposal.md and design.md exist. Do NOT generate tasks.md.
   If OpenSpec also generates specs/* along the way, that is fine.
   Do not add YAML frontmatter to proposal.md or design.md, even if earlier
   changes in the repo have it. The parent agent adds it after design approval.

4. Stop. Report completion, the path to design.md, and the change name explicitly as:
   "Change name: <slug>"

Your job ends here. The parent agent handles the design review checkpoint and
all later steps.

21. 等待子 Agent 完成

22. 从子 Agent 的输出中提取变更名称/slug（查找 “Change name:” 或从文件路径解析）

23. 保存变更名称——后续步骤会用到它

24. 验证所报告路径下的变更文件夹中是否存在 proposal.md 和 design.md

25. 如果在步骤 1 中设置了 --verbose 标志：在进入检查点之前，在变更文件夹中创建 trace.md 审计跟踪文件。

目的：通过记录初始输入、原始问题和为设计产物提供依据的研究答案，确保内容可追溯。这将“输入了什么 → 问了什么 → 得到了什么答案”的流程闭合起来。

文件位置：openspec/changes/<change-name>/trace.md

要求：

• 必须使用 Write 工具创建此文件
• 文件必须写入 openspec/changes/<change-name>/trace.md（其中 <change-name> 是步骤 23 中的 slug）
• 内容必须包含文档生成时间的 ISO 8601 时间戳
• 内容必须包含用户提供的原始工单/功能/想法文本（取自步骤 1，已移除标志）
• 内容必须包含步骤 12 中的完整研究问题
• 内容必须包含步骤 16 中的完整研究结果
• 不得在此步骤中修改 proposal.md 或 design.md——这是单独的审计文档
• 应在确认 design.md 存在后（步骤 24），且进入检查点（步骤 27）前，立即写入此文件

内容结构：

# QRSPI Trace Audit Trail

Generated: [paste current ISO 8601 timestamp with Z suffix, generated using: python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z'))"]

This document captures the complete QRSPI flow: the initial input, the questions generated, and the research answers that informed the design artifacts. It provides an audit trail for understanding the context and decision-making process.

---

## Initial Input

[paste the original ticket/feature/idea text from step 1, after removing the --verbose flag]

---

## Research Questions

[paste questions from step 12]

---

## Research Answers

[paste research findings from step 16]

26. 必须：暂时不要继续。下一步必须进入设计审查检查点。

27. ⚠️ 必需检查点：设计审查 [CHECKPOINT-1]（这是 QRSPI 演讲中所谓的“脑部手术”时刻。在此处进行更正只需几分钟；到实现后才更正，则会多出一个代码审查周期。必须在此处暂停并等待用户输入。未经用户明确批准，不得继续。）

28. 阅读生成的 proposal.md 和 design.md 文件

29. 按以下说明向用户展示这些文件：

Proposal and design artifacts generated (proposal.md, design.md). Please review for:

- Wrong pattern references (did I find the legacy way instead of the current way?)
- Unresolved assumptions presented as decisions
- Missing affected systems (any service boundaries not mentioned?)
- Scope creep (does the design cover more than the ticket?)

Options:
(a) Approve — continue to task breakdown
(b) Request edits — tell me what to change, I'll modify in place
(c) Manual edit — edit the file yourself, then tell me when ready

30. 等待用户输入：

• (a) 批准：继续执行下面的步骤 31
• (b) 请求修改：
  • 用户描述需要进行的更改
  • 直接修改相应文件（proposal.md 或 design.md）
  • 显示更改差异
  • 重新提交审查（重复此流程，直到获得批准）
• (c) 手动编辑：
  • 等待用户确认编辑已完成
  • 重新读取 proposal.md 和 design.md
  • 继续执行下面的步骤 31

31. 捕获 specs_touched/decisions frontmatter。 [S-FRONTMATTER] 用户批准 (a) 或确认手动编辑已完成 (c) 后，design.md 即为本轮规划的最终版本——此时再将其 specs_touched 和 decisions 捕获为结构化 YAML frontmatter，不要提前捕获，以免在同一检查点内进行的编辑导致 frontmatter 与之后更改的内容不一致。

分步流程：

a. 读取当前的 design.md 文件，查看其中已有内容： bash Read openspec/changes/<change-name-from-step-23>/design.md b. 提取撰写所需的数据： - specs_touched：design.md 和 proposal.md 已声明受此变更影响或由此变更引入的能力名称。这是变更自身声明的范围，应从刚刚获批的内容中读取，而不是通过其他方式计算得出。此时，openspec/changes/<slug>/specs/ 下的增量规范文件可能存在，也可能不存在（OpenSpec 会决定何时生成这些文件），因此应根据获批的 proposal.md 和 design.md 推导，而不是从 specs/ 中推导。 - decisions：design.md 中的决策内容——设计阶段已经讨论过的选择、理由和备选方案——重组为 {id, choice, rationale, alternatives} 条目列表。这只是对已有内容进行结构化，而不是编写新的设计内容。 - created_at：带 Z 后缀的 ISO 8601 时间戳，标记此变更的创建时间（即现在，也就是用户批准设计的时刻）。使用以下命令确定性地生成： bash python3 -c "from datetime import datetime, timezone; print(datetime.now(timezone.utc).isoformat(timespec='seconds').replace('+00:00', 'Z'))" 这是用于衡量 QRSPI 流程耗时的三个时间戳中的第一个（created_at → started_at → completed_at）。

c. 使用 Edit 工具编写 frontmatter：

  - 如果 `design.md` 尚无 frontmatter，则在文件顶部添加完整的 frontmatter 块：
    ```yaml
    ---
    change: <change-name-from-step-23>
    created_at: "2026-08-17T15:23:45.123Z"
    specs_touched: [<capability-a>, <capability-b>]
    decisions:
      - id: D1
        choice: <short decision summary>
        rationale: <why this over the alternatives>
        alternatives: [<option>, <option>]
    ---
    ```

  - 如果 `design.md` 已有 frontmatter（例如 OpenSpec 自带的元数据），请使用 Edit 工具将新字段合并到现有块中。不要创建第二个 frontmatter 块。

d. 重要的格式要求： - specs_touched 使用行内数组语法：写成 specs_touched: [cap-a, cap-b]，不要使用带连字符的多行 YAML。这样可确保 frontmatter 格式一致。 - 保留现有 frontmatter 字段：如果已有其他字段，请保持不变。 - decisions 使用块语法：decisions 列表使用多行 YAML，每个条目前加连字符（参见上面的示例）。

e. 验证写入成功： - 使用 Edit 工具后，确认操作已完成且没有错误。 - 如果 Edit 工具报告错误，请重新读取文件并再次尝试写入。 - 如果多次写入均失败，请告知用户，并请其手动添加 frontmatter。

f. 妥善处理缺失数据： - 如果无法从获批的 design.md/proposal.md 中有把握地读取 specs_touched 或明确的决策列表，不要猜测其中任何一项——请告知用户缺少哪些内容，并要求其直接将内容添加到 design.md。缺少明确决策记录的设计文档本身就值得特别指出；accelint-qrspi-archive 后续也需要这些 frontmatter 来进行跨能力关联。

此步骤的重要性： 此 frontmatter 是供 accelint-qrspi-archive 使用的跨技能记录元数据，不属于 openspec-continue-change 技能生成的设计内容；在此处写入它不违反“绝不自行生成产物”的规则（参见“绝不要做的事”）。此步骤不会创建或更改 proposal.md 或 design.md 的任何实际内容；只会更改 frontmatter 块。

32. 必须：如果用户没有明确批准（例如说“看起来不错”“批准”“继续”等），不要继续。此检查点不可跳过。跳过它会绕过 QRSPI 方法的核心价值。

33. 生成任务（及任何剩余的规范） [S-TASKS-GEN]（上下文隔离：继续确保工单不进入上下文。使用问题 + 研究 + 已批准的 design.md 启动子 Agent）

34. 读取步骤 31 中的 design.md 文件（该文件可能已由用户编辑）

35. 读取 openspec/config.yaml，提取 rules.spec 和 rules.tasks 部分

36. 读取 CLAUDE.md 或 AGENTS.md，了解 Agent 行为上下文

37. 使用 Agent 工具启动子 Agent，并附上以下提示块。原样发送该文本块：仅替换 <angle-bracket> 占位符（粘贴完整存储文本，不得删节），且不得在文本块前、后或其中添加任何内容。

You are generating the remaining OpenSpec artifacts based on QRSPI research and an
approved design. You have access to research and design, but NOT the original
ticket text.

CHANGE NAME: <change-name-from-step-23>

Research Questions and Answers:
<paste the complete research questions from step 12, unabridged>

Research Findings:
<paste the complete research doc from step 16, unabridged>

Approved Design:
<paste design.md content>

OpenSpec Spec Rules (from config.yaml):
<paste the rules.spec section verbatim>

OpenSpec Tasks Rules (from config.yaml):
<paste the rules.tasks section verbatim>

Agent Behavior Context:
<paste relevant sections from CLAUDE.md/AGENTS.md>

Find the openspec-continue-change skill, read its instructions in full, and follow it exactly.
Resolve relative paths from the supporting-files directory it provides.
All artifact files are written by following that skill, so
OpenSpec's configured rules apply. Do not author artifact content outside it.

Follow openspec-continue-change with the change name, one artifact at a time,
until tasks.md exists. specs/* may already exist; if OpenSpec has not generated
them yet, it will do so before tasks.md. Then stop.

After tasks.md is generated, the parent agent will validate vertical slicing
and add a "## Parallelization Strategy" section if needed.

After tasks.md is generated, report completion and the path to the tasks file.

38. 等待子 Agent 完成（内部步骤：不要向用户展示生成产物的详细信息）

39. 确认 tasks.md 存在于报告的路径下（并确认 specs/* 存在，除非 OpenSpec 对此变更跳过了规范）

40. 读取生成的 tasks.md 文件

41. 验证纵向切片结构：

纵向切片（accelint-qrspi-apply 必须遵循）：

每个切片都必须交付可端到端测试的功能路径，而不是横向分层。 组织工作时应确保完成切片 1 后，就有可演示、可测试的成果。

✓ 正确 — 纵向（端到端功能切片）：

Slice 1: Mock API + working frontend (user can see and click, no real data)
Slice 2: Wire real service layer (now pulls actual data)
Slice 3: Add database integration (data persists)

✗ 错误 — 横向（架构层）：

Slice 1: All database migrations
Slice 2: All service layer changes
Slice 3: All API endpoints
Slice 4: All frontend components

纵向切片的特征（正确）：

• 每个切片都有一个“交付成果：”，描述一项可运行、可测试的功能
• 切片跨越架构边界（例如，一个切片同时涉及 CLI 和实现）
• 每个切片结束时都有可向用户或利益相关者演示的成果
• 切片之间的依赖关系很少，可以并行推进

横向切片的特征（错误）：

• 按层组织切片：“数据库变更”“服务层”“API 路由”“前端”
• 交付成果是架构组件，而非面向用户的功能
• 早期切片无法在后续切片完成前进行端到端测试
• 切片之间存在顺序依赖（必须先完成第 1 层，再开始第 2 层）

每个切片的要求：

• 交付成果：可运行、可测试的增量成果（例如，“从公共 API 中移除安全功能的 CLI”）
• 测试：明确的验证步骤，展示该切片可端到端运行
• 并行化：切片应足够独立，可并发实现，且阻塞最少
• 检查点：每个子任务都要有一行“测试：”，描述验证方式
• 规模：优先采用 3–5 个主要切片；超过 5 个通常意味着范围过大
• 时长：每个子任务最多 2 小时；更大的工作应拆分为更小的子任务

关键要求：贯穿全程进行测试（而非只在最后测试）：

每个纵向切片都必须包含测试步骤。如果测试只出现在最后一个切片中，那么这种结构实际上是伪装成纵向切片的横向切片。

✓ 正确 — 每个切片都包含测试：

Slice 1: Mock API + working frontend
- [ ] Build mock API endpoint
- [ ] Create frontend component
- [ ] Test: Verify UI renders and responds to mock data

Slice 2: Wire real service layer
- [ ] Add service layer implementation
- [ ] Connect frontend to service
- [ ] Test: Verify real data flows from service to UI

Slice 3: Add database integration
- [ ] Add database queries
- [ ] Update service to use database
- [ ] Test: Verify data persists and loads correctly

✗ 错误 — 将所有测试都推迟到最后：

Slice 1: Mock API + working frontend
- [ ] Build mock API endpoint
- [ ] Create frontend component

Slice 2: Wire real service layer
- [ ] Add service layer implementation
- [ ] Connect frontend to service

Slice 3: Add database integration
- [ ] Add database queries
- [ ] Update service to use database
- [ ] Test everything end-to-end  ← RED FLAG: Only testing appears here

验证 tasks.md 时，检查以下事项：

• 每个切片都包含明确的测试步骤
• 测试步骤验证该切片的具体交付成果（而非仅仅“运行测试”）
• 没有任何切片只构建而不测试
• 最后一个切片不能只是“测试全部内容”——这表明工作是横向划分的

42. 如果发现横向或混合切片，自动转换为纵向切片：

必须遵循：qrspi-apply 技能要求采用纵向切片。如果 openspec-continue-change 技能生成了横向切片，必须先重新组织，再呈现给用户。

转换流程：

a) 识别端到端功能路径：寻找最小的完整面向用户功能，它涵盖所有相关架构层。例如： - 不要采用：“切片 1：所有 API 变更” + “切片 2：所有 CLI 变更” - 改为：“切片 1：CLI help 命令（CLI + API）” + “切片 2：CLI list 命令（CLI + API）” b) 重构每个切片，并包含以下必需元素： - 交付成果： - 一个可运行、可演示的功能（而不只是“API 端点已存在”） - 测试： - 明确的验证步骤，证明端到端流程可正常运行 - 子任务采用 Markdown 复选清单格式：每个子任务都必须使用 - [ ] instruction 格式 - 跨层子任务（例如，“- [ ] 更新 API 处理程序” + “- [ ] 接入 CLI 命令” + “- [ ] 添加帮助文本”）

  **关键：** 所有子任务都必须保留 Markdown 复选清单格式（`- [ ] ...`）。
  不要使用编号列表（1. 2. 3.）或普通项目符号（不带 [ ] 的 -）。
  accelint-qrspi-apply 技能依赖此格式来跟踪任务完成情况。

c) 确保每个切片都包含测试步骤：检查每个切片中是否都有明确的测试子任务，而不只是最后一个切片包含测试。如果测试只出现在最后一个切片中，请为之前的每个切片添加测试步骤： - 每个切片都应包含一个或多个 - [ ] Test: <what to verify> 子任务 - 测试步骤应验证该切片的特定交付成果 - 不要创建最终的“测试所有内容”切片——测试应贯穿各个切片

d) 保留并行化机会：将切片设计为彼此独立 - 好的示例：“切片 1：身份验证流程”和“切片 2：数据导出流程”相互独立 - 不好的示例：“切片 1：数据库架构”必须先于“切片 2：服务层”完成

e) 更新并行化策略（如果存在）：如果 tasks.md 已有“## Parallelization Strategy”章节，请修改它，使其反映新的切片结构（哪些切片可以并行，哪些存在依赖关系）。 注意：如果该章节不存在，它将在步骤 43 中添加。

f) 将更改写入 tasks.md：使用 Edit 工具直接编辑文件

g) 向用户展示差异：展示更改内容并说明原因（例如，“已将按层划分的切片改为按功能划分，并为每个切片添加了测试步骤”）

43. 必需：检查并添加并行化策略章节：

在验证或修正纵向切片后，检查 tasks.md 是否包含 ## Parallelization Strategy 章节。

如果缺少该章节或内容不完整，请立即使用 Edit 工具将其追加到 tasks.md 末尾（所有切片之后）：

## Parallelization Strategy

### Dependencies (Must Complete First)

- **Slice X** must wait until Slices Y-Z complete (reason)

**Independent tasks (can run in parallel):**
- Slice A and Slice B are independent → can implement simultaneously
- Slice A and Slice C are independent → can implement simultaneously

**Sequential dependencies:**
- Slice D must complete before Slice E because (reason)

**Critical path:**
Slice X → Slice Y (reason for dependency)

**Recommended implementation order:**
1. Implement Slices A, B, C in parallel (description)
2. Implement Slice D (description)
3. Implement Slice E (description)

内容应简洁明了，重点说明：

• 哪些切片可以并行执行，以及它们相互独立的原因
• 哪些切片必须按顺序执行，以及依赖原因
• 建议的实现顺序

不要加入过多细节或边缘情况，以免内容过于复杂。

如果该章节已存在，但属于水平切片到纵向切片的转换内容 （步骤 42d），请确认它准确反映新的纵向切片结构，并在需要时更新。

44. ⚠️ 必需检查点：任务审查 [CHECKPOINT-2] - 向用户展示 tasks.md，以供最终批准：

Tasks generated.

[If auto-converted:]
✓ Converted task structure to vertical slices for better parallelization
and incremental delivery. Each phase now delivers an end-to-end testable feature.

[If already vertical:]
✓ Task structure follows vertical slicing

Options:
(a) Approve — planning complete, ready for implementation
(b) Request changes — tell me what to adjust
(c) Manual edit — edit tasks.md yourself, then confirm

45. 处理用户输入（与步骤 30 的流程相同：批准、要求修改或手动编辑）

46. 必需：等待用户明确批准 tasks.md 的结构。如果用户未回复或对话结束，请在此处停止。不要自动继续完成流程。

47. 完成 - tasks.md 获得批准后，宣布完成：

✅ QRSPI planning phase complete.

Change name: <change-name-from-step-23>

Generated artifacts:
- openspec/changes/<change-slug>/proposal.md
- openspec/changes/<change-slug>/design.md
- openspec/changes/<change-slug>/specs/*
- openspec/changes/<change-slug>/tasks.md
[If --verbose was used:]
- openspec/changes/<change-slug>/trace.md (audit trail)

Next steps:
1. Review the artifacts one more time if needed
2. Run `/clear` to start fresh context for implementation
3. Invoke the accelint-qrspi-apply skill with <change-name> to begin implementation.

This allows you to create multiple specs before implementation and
maintains proper context management.

48. 退出技能——不要自动调用 accelint-qrspi-apply 技能

核心原则

上下文隔离（QRSPI 核心）

双上下文窗口模式至关重要：

• 生成问题：工单处于上下文中 → 生成问题
• 研究答案：工单不在上下文中，仅问题处于上下文中 → 获取客观事实

这可以避免“先入为主地思考解决方案”，即 Agent 在研究期间跳到实现方案。

人工检查点

两个强制审核关卡：

1. 在 proposal.md 和 design.md 完成后：发现错误模式、遗漏的系统和范围问题
2. 在 tasks.md 完成后：验证纵向切片和阶段顺序

这是纠正问题最有效的时机——此时还没有编写任何代码。

强制执行纵向切片

该技能 MUST 主动检查并纠正按层逐步切片的横向切片方式。每个切片 MUST 提供一条可测试的端到端功能路径。

不自动实施

该技能在规划后停止。用户准备好后，必须明确调用 accelint-qrspi-apply 技能。这样可以：

• 在开始任何实施之前创建多个规格
• 在规划和实施之间清除上下文
• 由用户控制何时开始实施

错误处理

如果 OpenSpec 命令失败：

• 向用户显示错误
• 询问他们要重试还是中止
• 失败时，DO NOT 继续下一步

如果子 Agent 失败：

• 显示子 Agent 返回的错误
• 询问用户是要重试该步骤还是提供手动输入
• 允许手动回退（由用户直接提供问题或研究内容）

如果子 Agent 报告偏离了这些指示：在转告用户之前，请将其行为与其遵循的内部 OpenSpec 技能文本进行比较。不要报告内部技能本身所要求的行为。

如果无法从已批准的 design.md 或 proposal.md 中可靠地读出 specs_touched 或 decisions（步骤 31）：

• DO NOT 猜测。向用户说明缺少的内容（例如，“未找到能力声明”或“没有说明理由的决策”）
• 请用户直接将其添加到 design.md，然后重新运行步骤 31
• DO NOT 因此阻塞后续步骤。变更可以在没有此 frontmatter 的情况下继续生成规格/任务，但 accelint-qrspi-archive 之后需要从 proposal.md 和届时已存在的增量规格中推导这些内容，而不是从 frontmatter 中读取

如果生成后缺少 proposal.md、design.md 或 tasks.md：

• 检查文件是否存在于预期路径
• 如果缺失，请用户核实 OpenSpec 配置
• 提供预期路径以供手动检查

配置要求

此技能假定项目已具备：

1. 已安装并初始化 OpenSpec（存在 openspec/ 目录）
2. 已配置 openspec/config.yaml（最好通过 accelint-onboard-openspec 技能完成）
3. 已启用扩展版 OpenSpec 配置文件
4. 已定义 Agent 行为的 AGENTS.md 或 CLAUDE.md（最好通过 accelint-onboard-agents 技能完成）

如果缺少其中任何一项，请在运行此技能前指导用户完成设置。

绝对不要这样做

绝对不要自行生成产物——始终通过让子 Agent 查找 OpenSpec 技能（openspec-new-change、openspec-continue-change）、阅读其 SKILL.md 并遵循其中指示来创建 proposal.md、design.md、specs/* 和 tasks.md。这些技能会按照 OpenSpec 配置的规则写入文件；这意味着任何产物内容都不能来自你在这些规则之外的自行判断。直接编写产物会绕过项目的设计、规格和任务规则，并产生不一致的输出。唯一狭义的例外是步骤 31 的 specs_touched/decisions frontmatter 块。该块是供 accelint-qrspi-archive 使用的跨技能记录元数据，来源于 openspec-continue-change 已生成且已获用户批准的内容——不是新的设计内容。即便如此，也只能写入 YAML frontmatter 块；此步骤绝不会改动 design.md 正文。 绝 NEVER 从头生成 tasks.md——始终遵循 openspec-continue-change 技能来创建初始的 tasks.md。但是，如果生成的内容采用横向切分而非纵向切分，则必须重新调整结构。accelint-qrspi-apply 技能要求采用纵向切分。如果 openspec-continue-change 生成了横向切分（按架构层组织），请根据步骤 42 中的验证指南，将其转换为纵向切分（端到端功能交付项）。重新调整时，保留 Markdown 复选清单格式（- [ ] task）——不要转换为编号列表或普通项目符号。

绝 NEVER 在 tasks.md 中使用编号列表或普通项目符号——所有子任务都必须使用 Markdown 复选清单格式：- [ ] instruction。qrspi-apply 技能通过勾选和取消勾选这些复选框来跟踪完成情况。如果看到编号列表（1. 2. 3.）或普通项目符号（不带 [ ] 的 -），请将其转换为 - [ ] ... 格式。

绝 NEVER 让并行化策略变得过于复杂——保持简单：列出哪些切片可以并行执行、哪些切片存在顺序依赖，以及建议的实现顺序。不要过度详述每一种可能的边缘情况或协调机制。此技能中的示例展示了恰当的细节程度。

绝 NEVER 未经设计批准就继续编写规格和任务——步骤 27 [CHECKPOINT-1] 是必需的检查点。如果跳过设计审查，立即生成任务，就会错过“脑外科手术”时刻，也就是修正成本最低的时候。代码编写后再修复设计问题，会增加审查轮次和返工。

绝 NEVER 在 design.md 定稿并获批前记录 specs_touched/decisions/created_at 前置元数据——只有在 (a) 获得批准或 (c) 确认已手动编辑后，才运行步骤 31；绝不能在 (b) 请求修改循环期间运行，也不能提前记录。根据仍在修改中的草稿记录这些内容，会产生过时元数据，而 accelint-qrspi-archive 正是依赖此技能避免这种情况。

绝 NEVER 跳过写入 created_at 时间戳——accelint-qrspi-apply（用于跟踪实现开始时间）和 accelint-qrspi-archive（用于跟踪完整生命周期）都要求此字段。如果写入前置元数据时 Edit 工具失败，请重试或请用户手动添加——不得在缺少该字段的情况下继续。缺少 created_at 会破坏下游的时间戳跟踪。

绝 NEVER 在无法从获批的 design.md 或 proposal.md 中有把握地读出 specs_touched 或 decisions 时自行猜测——请用户直接将缺失内容补充到 design.md 中。默默编造能力列表比明显留空更糟，因为 accelint-qrspi-archive 会将这些前置元数据视为作者对范围的明确陈述。

绝 NEVER 让工单内容泄漏到研究或设计上下文中——问题是在结合工单上下文的情况下生成的，但研究和设计阶段只能看到问题及研究答案；步骤 10 之后，任何子 Agent 提示词中都不得出现源自工单的目标、标记、待决事项或转述。如果工单内容在研究期间仍处于上下文中，Agent 就会提出解决方案，而不是收集关于当前代码库的客观事实。

绝 NEVER 跳过必需的检查点——步骤 27（在 proposal.md 和 design.md 之后）和步骤 44（在 tasks.md 之后）都要求在继续前获得用户明确批准。如果不等待用户确认（“看起来不错”“批准”“继续”），就会绕过 QRSPI 的核心价值：在设计阶段以低成本进行修正。“脑外科手术”时刻是指在生成任务之前审查设计。跳过检查点会使整个方法论失去意义。

示例用法

User: I want to plan this ticket using QRSPI:

## ATI-12: smart-ls CLI tool
Create a CLI tool that returns structured directory listings as JSON...