note-management

Note Management

Intro

Notes are processkit's capture layer — the place where ideas land before they are ready to become backlog items, decisions, or artifacts. Inspired by the Zettelkasten model: capture fast (fleeting), refine deliberately (permanent), link explicitly, and promote when something becomes actionable. The review cycle is what gives notes their value — unreviewed notes are just noise.

Overview

Note types

Type	When to use	Review horizon
fleeting	Quick thought, idea, or observation — not yet refined	Within 1 week
insight	A conclusion or realization from experience or reflection	Within 1 month
reference	Pointer to an external source, with your own summary	Evergreen
question	An open question you want to revisit	Until answered

Start with fleeting when in doubt. If a note survives a review session unchanged and seems worth keeping, promote to insight or reference.

Note file location and format

Notes live in context/notes/ as individual Markdown files with YAML frontmatter:

context/notes/
  NOTE-20260408_1432-amber-fox-better-error-messages.md
  NOTE-20260408_1455-silver-wolf-rag-chunking-question.md
  ...

File naming: {id}.md where {id} is the full ID returned by generate_id("Note", slug_text=title). No separate INDEX.md — the SQLite index (via index-management) replaces it.

---
apiVersion: processkit.projectious.work/v1
kind: Note
metadata:
  id: NOTE-20260408_1501-amber-fox-error-field-names
  created: 2026-04-08
spec:
  title: "Error messages should cite the field that caused the \
error, not just the error code"
  type: insight
  state: captured
  tags: [ux, error-handling, api-design]
  review_due: 2026-04-15
---

When a validation error returns `code: 400`, the user has no way to
know which field failed. Every error response should include `field`,
`message`, and a `docs_url` for context. I've seen this pattern
in Stripe's and GitHub's APIs — it's the right model.

Capturing a note

When the user says something note-worthy ("remember this", "I had an idea", "note that"):

1. Generate the Note ID via generate_id("Note", slug_text=title) → e.g. NOTE-20260408_1432-amber-fox-better-error-messages
2. Pick the type: fleeting (quick thought) or one of the specific types if already clear
3. Write the title as a self-contained claim or question — not a topic label. "Error messages should include the field name" is a note title; "Error messages" is a topic, not a note.
4. Set review_due: today + 7 days for fleeting, today + 30 days for insight/question, none for reference
5. Write context/notes/{id}.md — no INDEX.md update needed

Notes are discovered and queried via the SQLite index (index-management). To list active notes, use:

query_entities(kind="Note")
search_entities(text="<keyword>")

There is no hand-maintained INDEX.md — the index is authoritative.

Running a review session

A periodic review session works through all notes whose review_due has passed or is within 2 days:

For each overdue note, make one of four decisions:

Promote — the idea is ready to become a real primitive:

1. Create the downstream entity (WorkItem, DecisionRecord, etc.)
2. Add promotes_to: { kind: WorkItem, id: BACK-042 } to the note frontmatter
3. Transition the note to promoted

Keep as permanent — the note is worth keeping but not yet actionable:

1. Refine the body if the capture was rough
2. Set type to insight or reference
3. Transition state to permanent
4. Set a new review_due (30-90 days out)
5. Add links to related notes or entities

Archive — the note is no longer useful:

1. Transition state to archived

Defer — not ready to decide yet:

1. Keep state at captured
2. Extend review_due by 7 days
3. Add a one-line note on why it was deferred

Linking notes

Notes should not stand alone — the value of a knowledge base comes from connections. Link explicitly:

• Reference the note in the primitive it informed: <!-- originated from NOTE-003 -->
• Add related notes in the note body: Related: NOTE-007 (similar concern about validation in the CLI)
• When promoting, add a backlink in the created WorkItem's description

Promotion patterns

Note type	Common promotion target	Trigger
question	WorkItem (spike), Discussion	The question needs research or a team answer
insight	DecisionRecord	The insight captures a choice that was made
fleeting	WorkItem (task/chore)	The quick idea turns out to be actionable
reference	Artifact	The source becomes a formal reference material

This skill also provides the /note-management-capture slash command for direct invocation — see commands/note-management-capture.md. This skill also provides the /note-management-review slash command for direct invocation — see commands/note-management-review.md. This skill also provides the /note-management-promote slash command for direct invocation — see commands/note-management-promote.md.

Gotchas

Agent-specific failure modes — provider-neutral pause-and-self-check items:

• Capturing topic labels instead of claims or questions. "Error messages" is not a note — it's a tag. A note's title must be a self-contained claim ("Error messages should include the field name, not just the error code") or a specific question ("Does the auth middleware re-validate tokens on every request?"). Vague labels create a pile of notes with no re-discoverable content.
• Reviewing notes without making a decision. Reading through notes and doing nothing is not a review — it resets the review clock without advancing the note. Every note in a review session must exit with one of four decisions: promote, keep as permanent, archive, or defer with a reason and new date.
• Never archiving notes. A notes index that only grows and never shrinks stops being useful. Not every idea deserves to become permanent — many are superseded, wrong in retrospect, or simply no longer interesting. Archive aggressively; promoted and permanent notes are the signal.
• Promoting a fleeting note without refining it first. A rough, first-draft thought promoted directly to a DecisionRecord or WorkItem brings the roughness with it. Before promoting, read the note and refine: does the title accurately capture the claim? Is the body complete enough for a newcomer to understand without the original context?
• Writing notes that require the original context to make sense. "The thing we discussed about the API" is meaningless six weeks later. A note must be self-contained: include enough context that the note makes sense to the author (or an agent) who has no memory of the conversation or session where the idea was captured.
• Not writing the review decision back to the file. After a review session, every note that was touched must have its state, review_due, and (if promoted) promotes_to fields updated in the file. The SQLite index is kept current by re-indexing, but the file is the source of truth.
• Using notes as a dumping ground for everything instead of a capture layer for non-backlog ideas. Notes are for ideas not yet ready to be backlog items. Things that are clearly tasks should go directly into a WorkItem. Things that are clearly decisions should go into a DecisionRecord. Notes are the intermediate capture for things that haven't crystallized yet — not a general-purpose inbox for all project work.

Full reference

Note ID assignment

IDs are generated by generate_id("Note", slug_text=title) and follow the standard processkit timestamp-word-pair format: NOTE-YYYYMMDD_HHMM-word-pair[-slug]

Example: NOTE-20260408_1432-amber-fox-better-error-messages

IDs encode the capture time and are globally unique. No counter or INDEX.md is needed — the SQLite index replaces both.

State transitions

captured → reviewing → permanent
                     → promoted  (terminal)
                     → archived  (terminal)
captured → archived
permanent → reviewing
permanent → promoted
permanent → archived

Review cadence

Suggested cadence for a solo developer:

Frequency	Action
Daily	Capture freely — do not review
Weekly	Review all fleeting notes past their review_due
Monthly	Review all permanent notes; check if any should be promoted
Quarterly	Archive anything in permanent that hasn't been revisited in >90 days

For teams, assign a note review owner per sprint or rotate the responsibility on a weekly basis.

Note template

---
apiVersion: processkit.projectious.work/v1
kind: Note
metadata:
  id: NOTE-{{YYYYMMDD_HHMM}}-{{word-pair}}[-{{slug}}]
  created: {{date}}
spec:
  title: "{{self-contained claim or question}}"
  type: {{fleeting|insight|reference|question}}
  state: captured
  tags: []
  review_due: {{date + 7 days for fleeting, + 30 for others}}
---

{{Note body — enough context to understand without memory of the
session}}

File name: context/notes/{id}.md (the full ID, no extra suffix).

Relationship to other primitives

Primitive	How notes relate
WorkItem	Notes often promote to WorkItems when an idea becomes a task
DecisionRecord	Insight notes about choices promote to DecisionRecords
BACKLOG.md	High-priority, well-understood items go here directly — not in notes
STANDUPS.md	Standups reference the work done; notes capture the ideas generated