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

Note types map to the Luhmann/Ahrens Zettelkasten taxonomy:

Start with fleeting when in doubt. If a note survives a review session unchanged and seems worth keeping, refine and set to insight or reference. Insight notes are permanent — they are never discarded, only promoted or further refined.

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 (permanent note — never discarded) or reference (literature note — evergreen)
3. Transition state to permanent
4. Set review_due to null (permanent notes don't expire) or to a far-future date if you want a reminder to link it further
5. Add links to related notes with relation and context sentence

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

The links field is how Zettelkasten insight is built. Every link must name the relation and provide a context sentence explaining why the connection matters — not just that it exists. Tags group notes by topic; links with context build arguments.

links:
  - target: NOTE-20260408_1455-SilverWolf-rag-chunking-question
    relation: elaborates
    context: "Both notes address retrieval quality; this note proposes
      a concrete chunking strategy for the problem identified there."

Links are directional (from this note → to target). Bidirectional linking is intentional — add the reciprocal link in the target note when the relationship is symmetric (e.g. two supports notes).

Promotion patterns

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:

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 question, null for insight/reference}}
  # links: optional — add when you know related notes
  # links:
  #   - target: NOTE-xxx-yyy
  #     relation: elaborates  # see relation table above
  #     context: "One sentence explaining why this connection matters."
---

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