# note-it
Captures design decisions, spec deviations, and tradeoffs after code implementation, saving them into a structured HTML report in docs/.
- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 465 installs · ★ 294
- Author: smallnest
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/smallnest/goal-workflow/tree/HEAD/skills/note-it/SKILL.md
- Updated: 2026-09-13
- HTML: https://affpapa.org/en/nevibecode/skills/note-it
## What it does
The skill reviews completed code against the issue specification and writes an implementation report to `docs/issue#XXXX.html`. It pulls the issue number directly from the prompt, a Git branch name like `feat/issue-42-*`, or the previous `/goal` step. If the `docs/` folder does not exist yet, the skill creates it automatically.
The output HTML file divides notes into four specific categories: design choices made for ambiguous requirements, deliberate deviations from the spec, evaluated tradeoffs, and open questions. When a report for that issue already exists, the skill asks whether to update or overwrite, defaulting to appending new items.
Missing PRD files at `tasks/prd-*.md` will not crash execution. In that scenario, the skill marks the absence inside the open questions section so you can verify requirements manually.
## Install
### Claude Code (native platform)
1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill note-it -a claude-code
```
2. **Manually: put the files in place**
- File: `~/.claude/skills/note-it/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/note-it/
### Codex
1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill note-it -a codex
```
2. **Manually: put the files in place**
- File: `.agents/skills/note-it/SKILL.md` — For all projects use ~/.agents/skills/
### Cursor
1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill note-it -a cursor
```
2. **Manually: put the files in place**
- File: `.cursor/skills/note-it/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/
### GitHub Copilot
1. **GitHub CLI**
```bash
gh skill install smallnest/goal-workflow note-it
```
2. **Manually: put the files in place**
- File: `.github/skills/note-it/SKILL.md`
### Gemini CLI
1. **Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill note-it -a gemini-cli
```
2. **Platform CLI**
```bash
gemini skills install https://github.com/smallnest/goal-workflow --path skills/note-it
```
### Windsurf (Devin Desktop)
**Manually: put the files in place**
- File: `.devin/skills/note-it/SKILL.md` — The legacy .windsurf/skills/ path still works
### OpenCode
**Skills CLI (Vercel)**
```bash
npx skills add smallnest/goal-workflow --skill note-it -a opencode
```
### Claude.ai
**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills
Where a file is given instead of a command, copy the files from the source to that path: https://github.com/smallnest/goal-workflow/tree/HEAD/skills/note-it/SKILL.md
## When to use it
- Record deviations from issue specs right after implementation
- Document architectural choices and rejected alternatives in HTML
- Collect open questions for manual review before `/ship-it`
- Track design rationale when requirements are ambiguous or silent
## Example prompts
- /note-it #42
- /note-it
- Record implementation notes for this issue before shipping
## Source text · SKILL.md · MIT
Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 422bfb59360c4725.
BEGIN THIRD-PARTY FILE 422bfb59360c4725
````text
---
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