quint-code

Notes & Micro-decisions

Not every decision needs a full reasoning cycle. "We're using RWMutex instead of channels because contention is under 0.1%" is a perfectly valid engineering choice that should be recorded — but doesn't need five steps and a Pareto front.

How notes work

/q-note

Record a micro-decision with a title and rationale. The agent validates:

  • Rationale required — why this choice? No rationale, no record.
  • Conflict check — does this contradict an active decision?
  • Overlap check — does an existing decision already cover this topic? (Rejected if >70% word overlap.)
  • Scope check — if it affects many files, suggests /q-frame instead.

Auto-capture (when /q-reason is active)

When /q-reason is active in a session, the agent may record notes automatically when it notices decisions in conversation. This is a best-effort behavior, not a guarantee — the auto-capture instructions are part of the /q-reason skill prompt. If /q-reason hasn't been invoked in the current session, the agent won't auto-capture.

For reliable note capture, use /q-note explicitly. It takes seconds and ensures the rationale is recorded properly.

When auto-capture is active, it does NOT trigger for:

  • Formatting choices, import ordering, variable naming (too trivial)
  • Topics already covered by an active decision (overlap check prevents duplicates)

Notes are not decisions

Notes are observations and micro-decisions. They are NOT architectural decisions. If you find yourself writing a note about a fundamental approach or strategy — stop. Use /q-frame → /q-decide instead.

Notes auto-expire after 90 days. If the choice is still relevant in 3 months, it deserves a proper decision record.

Notes in /q-status

/q-status shows the 5 most recent active notes. Deprecated and superseded notes are filtered out. Notes do not count toward module coverage — only decisions do.

Cleaning up notes

/q-refresh action="reconcile" scans all active notes against all active decisions. If a note overlaps significantly with a decision, it suggests deprecation. This is a batch cleanup — one command, no per-note review needed.

Next