Skip to content

schema.md

Latest commit

 

History

History
44 lines (37 loc) · 3.04 KB

schema.md

File metadata and controls

44 lines (37 loc) · 3.04 KB
Raw

Open-loop item schema

Every item the scanner produces — and everything board/index.html renders — is a JSON object with these fields.

Fields

Field Type Required Description
id string yes Stable unique id, e.g. loop-2026-09-28-001. The scanner must reuse the same id for the same open loop across scans so items don't duplicate.
title string yes Short, actionable title. Verb-first: "Reply to…", "Finish…", "Book…".
priority string yes One of urgent, high, normal, low. See prompts/prioritization.md.
status string yes One of open, waiting (blocked on someone/something else), snoozed (deliberately deferred), dropped (removed from the board by the user — not deleted, waits in the Dropped list until resurfaced), shipped (done — confirmed by the user). The board moves shipped items to the shipped log and dropped items to the dropped list instead of hiding them.
dropped_at string no YYYY-MM-DD date the item was dropped. The scan must never resurrect a dropped item on its own — a drop stays a drop until the user says otherwise.
source_chat string yes Human-readable name of the conversation the item came from, e.g. "Job search". Shown on the card so the user can jump back to context.
source_fingerprint string yes Machine key for dedup, e.g. the chat's id + a topic hash. Same loop seen in a later scan must produce the same fingerprint.
note string no One or two sentences of context: what's blocking, what's next, why it matters.
detail string no Longer context for the Focus view: background, what was tried, what "done" looks like.
why_urgent string no One sentence: why the scanner ranked it at this urgency. Shown in the Focus view so the user can agree or override.
due string no YYYY-MM-DD deadline, when one exists.
snooze_until string no YYYY-MM-DD comeback date. Set when the user snoozes; the scan should not surface the item before this date.
shipped_at string no YYYY-MM-DD date the user confirmed shipped.
shipped_note string no What the user actually did, in their words. Proof, not a checkbox.

Example

{
  "id": "loop-2026-09-28-001",
  "title": "Reply to landlord about lease renewal",
  "priority": "high",
  "status": "waiting",
  "source_chat": "Personal",
  "source_fingerprint": "chat-9f31::lease-renewal",
  "note": "Waiting on their answer about the parking spot. Nudge if no reply by Thursday.",
  "due": "2026-10-03"
}

Rules for producers

  1. Never invent items. Every item traces to a real, observed unfinished thread.
  2. Never duplicate. Match source_fingerprint against existing items first; update the existing item instead of creating a new one.
  3. shipped is sacred. Only mark shipped when the user confirms they acted. "Produced" is not "shipped."
  4. Keep titles actionable. If you can't phrase it as a next action, it's not an open loop — it's a note. Leave notes out.