note-it

实现说明

完成某个 Issue 的实现和审查／修复后，创建并持续更新实现说明文件，记录实现与规范的差异或对规范的解读。

触发条件

在以下情况下使用：

• /goal 实现和 /review-it 均已完成
• 用户说“记录笔记”、“implementation notes”、“note-it”或“/note-it”
• /ship-it 之前（作为最后的检查点）
• 用户希望记录设计理由时

工作内容

1. 根据上下文确定 Issue 编号（分支名称、/goal 目标或用户输入）
2. 对照 Issue 规范／PRD 审查实现
3. 在 docs/issue#XXXX.html 创建 HTML 格式的说明文件
4. 向用户概述内容

说明结构

HTML 文件必须涵盖以下四个类别。如果某个类别没有内容，请写“无”，并简要说明。

1. 设计决策

规范含糊或未作说明时所作的选择：

• 含糊之处是什么？
• 你做了什么选择？
• 理由是什么？

2. 偏离之处

有意偏离规范的地方：

• 规范要求什么？
• 实际实现了什么？
• 为什么这种偏离是必要的，或更合适？

3. 权衡取舍

考虑过哪些方案，以及为何选择当前方案：

• 有哪些可行的替代方案？
• 各方案的优缺点是什么？
• 为何选择当前方案？

4. 待确认问题

希望获得确认或修订的事项：

• 哪些假设尚不确定？
• 用户应核实什么？
• 哪些事项可能需要后续跟进？

输出

• 格式： HTML
• 位置： docs/
• 文件名： issue#XXXX.html（其中 XXXX 为补零后的 Issue 编号，例如 issue#0042.html）

HTML 模板

使用以下确切的 HTML 结构：

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Implementation Notes — Issue #XXXX</title>
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }
    body {
      font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
      background: #FAF9F6;
      color: #1a1a1a;
      padding: 2.5rem 2rem;
      line-height: 1.7;
    }
    .container { max-width: 800px; margin: 0 auto; }
    h1 { font-size: 1.375rem; font-weight: 700; margin-bottom: 0.25rem; }
    .meta { color: #8B8680; font-size: 0.8125rem; margin-bottom: 2rem; }
    h2 {
      font-size: 1rem;
      font-weight: 600;
      margin-top: 2rem;
      margin-bottom: 0.75rem;
      padding-bottom: 0.375rem;
      border-bottom: 1px solid #E8E4DE;
      display: flex; align-items: center; gap: 0.5rem;
    }
    .dot {
      width: 8px; height: 8px; border-radius: 50%; display: inline-block;
    }
    .dot.design { background: #5B8A72; }
    .dot.deviation { background: #D97757; }
    .dot.tradeoff { background: #4A6FA5; }
    .dot.question { background: #D4A843; }
    .item {
      background: #FFFFFF;
      border: 1px solid #E8E4DE;
      border-radius: 8px;
      padding: 1rem 1.25rem;
      margin-bottom: 0.75rem;
      box-shadow: 0 1px 3px rgba(0,0,0,0.03);
    }
    .item h3 { font-size: 0.875rem; font-weight: 600; margin-bottom: 0.375rem; }
    .item p { font-size: 0.8125rem; color: #4A4540; margin-bottom: 0.375rem; }
    .label {
      display: inline-block;
      font-size: 0.6875rem;
      font-weight: 500;
      padding: 0.125rem 0.5rem;
      border-radius: 4px;
      margin-right: 0.375rem;
    }
    .label-design { background: #F5F8F6; color: #5B8A72; border: 1px solid #5B8A72; }
    .label-deviation { background: #FFF5F0; color: #D97757; border: 1px solid #D97757; }
    .label-tradeoff { background: #F0F4F8; color: #4A6FA5; border: 1px solid #4A6FA5; }
    .label-question { background: #FDF8F0; color: #D4A843; border: 1px solid #D4A843; }
    .none { color: #B0AAA4; font-style: italic; font-size: 0.8125rem; }
    .footer {
      text-align: center; margin-top: 2.5rem; color: #B0AAA4;
      font-size: 0.6875rem;
    }
  </style>
</head>
<body>
  <div class="container">
    <h1>Implementation Notes</h1>
    <p class="meta">Issue <a href="{{ISSUE_URL}}">#{{ISSUE_NUMBER}}</a> &mdash; {{ISSUE_TITLE}} &mdash; {{DATE}}</p>

    <h2><span class="dot design"></span> Design Decisions</h2>
    

    <h2><span class="dot deviation"></span> Deviations</h2>
    

    <h2><span class="dot tradeoff"></span> Tradeoffs</h2>
    

    <h2><span class="dot question"></span> Open Questions</h2>
    

    <p class="footer">Generated by goal-workflow /note-it</p>
  </div>
</body>
</html>

示例条目

<div class="item">
  <h3><span class="label label-design">Decision</span> Used interface-based polymorphism instead of switch</h3>
  <p><strong>Ambiguity:</strong> The spec said "handle different types" without specifying how.</p>
  <p><strong>Choice:</strong> Defined a <code>Handler</code> interface with per-type implementations.</p>
  <p><strong>Rationale:</strong> Adding new types requires no changes to existing code (Open/Closed Principle). A switch would grow unboundedly.</p>
</div>

如何确定 Issue 编号

1. 如果用户直接提供编号（例如 /note-it #42），则使用该编号
2. 如果当前分支名为 feat/issue-42-* 或 fix/issue-42-*，则提取 42
3. 如果最近一次 /goal 的目标是 #42，则使用 42
4. 否则，询问用户：“说明文件应使用哪个 Issue 编号？”

边缘情况

场景	处理方式
未找到 Issue 编号	请用户指定
docs/ 目录不存在	自动创建
此 Issue 的说明文件已存在	询问：“更新现有说明还是覆盖？”——默认更新（追加新条目）
没有偏离之处或待确认问题	写“无——实现遵循规范。”
未找到规范／PRD 文件	在待确认问题中注明：“在 tasks/prd-*.md 中未找到 PRD——请对照原始需求核实。”

检查清单

保存前：

• 已确定 Issue 编号
• 已审查全部四个类别（即使某些类别为“无”）
• 设计决策说明了理由，而不只是描述所做的工作
• 清楚说明偏离之处，并对比规范与实现
• 权衡取舍提及考虑过的具体替代方案
• 待确认问题可执行（用户可以回答是／否或给出方向）
• HTML 格式良好且能正确渲染