--- name: note-it description: "Capture implementation notes after code implementation and review/fix. Records design decisions, deviations, tradeoffs, and open questions to docs/issue#XXXX.html. Triggers on: /note-it, 记录笔记, implementation notes." user-invocable: true --- # 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. ## 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 ## 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 ## Notes Structure The HTML file must cover these four categories. If a category has nothing to report, write "None" with a brief explanation. ### 1. Design Decisions Choices made where the spec was ambiguous or silent: - What was the ambiguity? - What choice did you make? - What was the rationale? ### 2. Deviations 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 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 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 Template Use this exact HTML structure: ```html Implementation Notes — Issue #XXXX

Implementation Notes

Issue #{{ISSUE_NUMBER}} — {{ISSUE_TITLE}} — {{DATE}}

Design Decisions

Deviations

Tradeoffs

Open Questions

``` ## Example Item ```html

Decision Used interface-based polymorphism instead of switch

Ambiguity: The spec said "handle different types" without specifying how.

Choice: Defined a Handler interface with per-type implementations.

Rationale: Adding new types requires no changes to existing code (Open/Closed Principle). A switch would grow unboundedly.

``` ## How to Determine the Issue Number 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?" ## Edge Cases | Scenario | Handling | |----------|----------| | No Issue number found | Ask the user to specify | | `docs/` directory does not exist | Auto-create it | | Notes file already exists for this Issue | Ask: "Update existing notes or overwrite?" — default to update (append new items) | | No deviations or open questions | Write "None — implementation followed the spec as written." | | Spec/PRD file not found | Note in Open Questions: "No PRD found at tasks/prd-*.md — verify against original requirements." | ## 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