haft

Notes & Micro-decisions

Not every decision needs five modes. "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 characterization, Pareto computation, and adversarial verification.

How notes work

/h-note

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

  • 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?
    • >70% word overlap → rejected outright
    • 50-70% overlap → warning, you can proceed
  • Scope check — if it affects many files, the agent suggests /h-frame instead. A note that touches half the codebase is not a micro-decision.

Auto-capture

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

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

Auto-capture 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 /h-frame → /h-decide instead.

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

Notes in /h-status

/h-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

/h-verify 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.

When to promote a note: If you keep referencing a note in conversations, or if the note has survived past its 90-day expiry and been waived, it's a signal that this choice matters enough for a proper decision record. Run /h-frame to start the full cycle.

Next