Back to Details

note-it

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementation Notes

实现笔记

After completing implementation and review/fix for an Issue, capture a running implementation notes file that documents how the implementation diverges from or interprets the spec.
在完成某个Issue的实现及审核/修复工作后，生成一份动态更新的实现笔记文件，记录实现方案与需求规格说明书（spec）的差异或对其的解读。

Triggers

触发场景

Use when:
  • After 
    /goal
    implementation and 
    /review-it
    are both complete
  • User says "记录笔记", "implementation notes", "note-it", "/note-it"
  • Before 
    /ship-it
    (as a final checkpoint)
  • Any time the user wants to capture design rationale
在以下场景使用：
  • 完成
    /goal
    实现和
    /review-it
    审核后
  • 用户输入“记录笔记”、“implementation notes”、“note-it”或
    /note-it
    时
  • 执行
    /ship-it
    之前（作为最终检查点）
  • 用户需要记录设计依据的任何时刻

The Job

执行步骤

  1. Determine the Issue number from context (branch name, 
    /goal
    target, or user input)
  2. Review the implementation against the Issue spec / PRD
  3. Generate an HTML notes file at 
    docs/issue#XXXX.html
  4. Present a summary to the user
  1. 从上下文（分支名称、
    /goal
    目标或用户输入）中确定Issue编号
  2. 对照Issue的需求规格说明书（spec）或PRD审核实现方案
  3. 在
    docs/issue#XXXX.html
    路径下生成HTML格式的笔记文件
  4. 向用户展示笔记摘要

Notes Structure

笔记结构

The HTML file must cover these four categories. If a category has nothing to report, write "None" with a brief explanation.
HTML文件必须涵盖以下四个类别。如果某个类别无内容可记录，需写入“无”并附上简短说明。

1. Design Decisions

1. 设计决策

Choices made where the spec was ambiguous or silent:
  • What was the ambiguity?
  • What choice did you make?
  • What was the rationale?
针对需求规格说明书模糊或未明确说明的内容所做出的选择：
  • 模糊点是什么？
  • 做出了什么选择？
  • 选择的依据是什么？

2. Deviations

2. 偏差记录

Places where you intentionally departed from the spec:
  • What did the spec say?
  • What did you implement instead?
  • Why was the deviation necessary or better?
有意偏离需求规格说明书的地方：
  • 需求规格说明书的要求是什么？
  • 实际实现的方案是什么？
  • 偏离的必要性或优势是什么？

3. Tradeoffs

3. 权衡方案

Alternatives you considered and why you picked what you did:
  • What were the viable alternatives?
  • What were the pros/cons of each?
  • Why did the chosen approach win?
考虑过的替代方案及最终选择的原因：
  • 可行的替代方案有哪些？
  • 每个方案的优缺点是什么？
  • 为何最终选择该方案？

4. Open Questions

4. 未解决问题

Anything you'd want confirmed or revised:
  • What assumption are you unsure about?
  • What should the user verify?
  • What might need follow-up?
需要确认或修订的内容：
  • 哪些假设不确定？
  • 用户需要验证什么？
  • 哪些内容需要后续跟进？

Output

输出要求

  • Format: HTML
  • Location: 
    docs/
  • Filename: 
    issue#XXXX.html
    (where XXXX is the zero-padded Issue number, e.g., 
    issue#0042.html
    )
  • 格式： HTML
  • 存储位置： 
    docs/
    目录
  • 文件名： 
    issue#XXXX.html
    （其中XXXX为补零后的Issue编号，例如
    issue#0042.html
    ）

HTML Template

HTML模板

Use this exact HTML structure:
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>
    <!-- One .item per decision, or .none if none -->

    <h2><span class="dot deviation"></span> Deviations</h2>
    <!-- One .item per deviation, or .none if none -->

    <h2><span class="dot tradeoff"></span> Tradeoffs</h2>
    <!-- One .item per tradeoff, or .none if none -->

    <h2><span class="dot question"></span> Open Questions</h2>
    <!-- One .item per question, or .none if none -->

    <p class="footer">Generated by goal-workflow /note-it</p>
  </div>
</body>
</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>
    <!-- One .item per decision, or .none if none -->

    <h2><span class="dot deviation"></span> Deviations</h2>
    <!-- One .item per deviation, or .none if none -->

    <h2><span class="dot tradeoff"></span> Tradeoffs</h2>
    <!-- One .item per tradeoff, or .none if none -->

    <h2><span class="dot question"></span> Open Questions</h2>
    <!-- One .item per question, or .none if none -->

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

Example Item

示例条目

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

How to Determine the Issue Number

Issue编号的确定方式

  1. If the user provides it directly (e.g., 
    /note-it #42
    ), use it
  2. If on a branch named 
    feat/issue-42-*
    or 
    fix/issue-42-*
    , extract 
    42
  3. If the last 
    /goal
    target was 
    #42
    , use 
    42
  4. Otherwise, ask the user: "Which Issue number should I use for the notes file?"
  1. 如果用户直接提供（例如
    /note-it #42
    ），则使用该编号
  2. 如果当前分支名称为
    feat/issue-42-*
    或
    fix/issue-42-*
    ，则提取编号
    42
  3. 如果最近的
    /goal
    目标为
    #42
    ，则使用编号
    42
  4. 否则，询问用户：“笔记文件应使用哪个Issue编号？”

Edge Cases

边缘场景处理

ScenarioHandling
No Issue number foundAsk the user to specify
docs/
directory does not exist		Auto-create it
Notes file already exists for this IssueAsk: "Update existing notes or overwrite?" — default to update (append new items)
No deviations or open questionsWrite "None — implementation followed the spec as written."
Spec/PRD file not foundNote in Open Questions: "No PRD found at tasks/prd-*.md — verify against original requirements."
场景处理方式
未找到Issue编号请用户指定
docs/
目录不存在		自动创建该目录
该Issue对应的笔记文件已存在询问用户：“更新现有笔记还是覆盖？” — 默认选择更新（追加新条目）
无偏差记录或未解决问题写入“无 — 实现方案严格遵循需求规格说明书。”
未找到需求规格说明书/PRD文件在未解决问题中记录：“未在tasks/prd-*.md路径下找到PRD — 请对照原始需求进行验证。”

Checklist

检查清单

Before saving:
  • Issue number identified
  • All four categories reviewed (even if some are "None")
  • Design decisions explain rationale, not just what was done
  • Deviations clearly contrast spec vs implementation
  • Tradeoffs mention specific alternatives considered
  • Open questions are actionable (user can answer yes/no or give direction)
  • HTML is well-formed and renders correctly
保存前请确认：
  • 已确定Issue编号
  • 已审核所有四个类别（即使部分类别为“无”）
  • 设计决策说明了选择依据，而非仅描述操作内容
  • 偏差记录明确对比了需求规格说明书与实际实现方案
  • 权衡方案提及了具体的替代选项
  • 未解决问题具备可操作性（用户可回答是/否或给出指导方向）
  • HTML格式规范且可正常渲染