nn-refine

name	nn-refine
description	Use when cleaning up a specific note or before promoting it — runs atomicity, link, and title checks. Load with `nn skills get nn-refine`.
when_to_use	After nn show <id> when you want to clean up a specific note, or before considering a note for promotion. Invoke with /nn-refine.

nn-refine

Single-note hygiene: atomicity check, link suggestions, promotion eligibility, and title check.

When to use

Invoke after nn show <id> when you want to clean up a specific note. Run this skill on any draft note before considering it for promotion, or on any note that has grown stale.

Workflow

1. Atomicity check

Does the note body contain more than one independent claim?

nn show <id>

If yes — the note is not atomic. Propose a split:

• nn new --title "<claim 2>" --type <type> --content "<extracted body>" --no-edit
• nn link <new-id> <original-id> --annotation "split from" --type refines
• nn update <original-id> --content "<remaining body>" --no-edit

A note is atomic when removing any sentence would leave only one coherent claim.

2. Link discovery

Run the link suggester to surface candidate connections:

nn suggest-links <id> [--limit 20]

Review candidates and propose nn link or nn bulk-link commands. Every link requires --annotation and --type. See nn-link-suggester for the full workflow.

3. Promotion eligibility

A note is eligible for promotion when:

• Its body is focused (single claim, not a list of loosely related ideas)
• It has at least one inbound reviewed link (run nn backlinks <id> to check)
• Its status is draft or reviewed

If eligible, propose:

nn promote <id> --to reviewed      # draft → reviewed (errors on concurrent conflict)
nn promote <id> --to permanent     # reviewed → permanent (errors on concurrent conflict)

Or use direct assignment:

nn update <id> --status reviewed --no-edit
nn update <id> --status permanent --no-edit

4. Title check

Does the title name the single claim in the body? A good title is a complete, falsifiable assertion or a precise concept label.

If not, propose:

nn update <id> --title "Better title that names the claim" --no-edit

nn commands used

nn show <id>
nn suggest-links <id> [--limit N]
nn new --title "..." --type <type> --content "..." --no-edit
nn link <from> <to> --annotation "..." --type TYPE
nn bulk-link <from> --to <id> --annotation "..." --type TYPE [--to <id> ...]
nn backlinks <id> [--json]
nn promote <id> --to reviewed|permanent  # errors on concurrent modification conflict
nn update <id> [--title "..."] [--content "..."] [--status STATUS] --no-edit
nn list --long --json

Success criteria

• Atomicity: note body contains exactly one independent claim (or split proposed)
• Links: nn suggest-links was run and candidate links were reviewed
• Promotion: eligibility was assessed and a promotion command was proposed or skipped with reason
• Title: title names the single claim or a rename was proposed