totocaster_triage-obsidian/docs/spec.md

Triage spec

Status: draft product spec; filtering, sorting, focused-card rendering, and Anki-style triage slices are in place Last updated: 2026-06-12 Implementation status: MVP in progress Code status: plugin shell, Open queue command/ribbon button, focused-item commands, filtered markdown triage queue, title extraction, plain-text previews, rendered expanded bodies, focused-card navigation, centered Anki-style focused-card action toolbar, title-bar sort and refresh controls, queue counts, basic empty-state variants, expandable cards, configurable preview length, configurable preview metadata, scoped styles, build tooling, hot-reload output, preview tests, CI, filter settings, Keep behavior settings, pure filtering logic, pure sorting logic, pure triage logic, filtering tests, sorting tests, settings tests, triage tests, metadata tests, frontmatter-backed snooze, clear snooze, Keep, and delete-through-Obsidian-prompt actions are in place; path, date, and status metadata rows remain absent

Purpose

Triage is an Obsidian plugin for resurfacing notes that would otherwise disappear inside a vault.

The plugin provides a scrolling triage queue for collected material such as fleeting notes, literature notes, untagged notes, uncategorized notes, and other user-configured classes of notes. The triage queue supports quick review actions so every surfaced note can become active again, be snoozed for later resurfacing, be kept out of triage through frontmatter or vault-native tags/categories, or be deleted through Obsidian's normal delete flow.

The intended product shape is a recurring review ritual, not a project management system and not a generic dashboard.

Working description:

A triage queue for resurfacing unprocessed notes so loose material is reviewed, snoozed, kept out of triage, deleted, or brought back into active use.

Inspiration

Andy Matuschak's "Peripheral vision" note is an explicit inspiration:

https://notes.andymatuschak.org/z4geAr5cERWdJPrdhU5gy3N

The product should carry forward three ideas from that note:

• Concrete cues work better than abstract queues. The triage queue should show enough note content and context for the user to react to the material itself, not only to a title.
• Useful resurfacing should be dynamic. A static list can fade into the background, while a changing triage queue can prompt attention at receptive moments.
• Context matters. The plugin should avoid reducing notes to tiny task-like labels when a short preview, path, tags, and metadata can preserve useful context.

The user also referenced /Users/toto/Developer/obsidian-kanban-view-job as an interaction precedent for focused-card behavior and mouse navigation. Triage should borrow that style of triage queue item focus where relevant:

• Triage queue items can become focused through mouse movement.
• Keyboard navigation can move the focused item.
• After keyboard navigation, stationary mouse hover should not immediately steal focus back until the pointer moves again.
• Actions apply to the currently focused triage queue item.

Name

Chosen product name: Triage

Expected Obsidian community plugin naming implications:

• Manifest name should likely be Triage.
• Manifest id should likely be triage.
• Do not include "Obsidian" in the plugin name, id, or description.
• Do not end the plugin name or id with "plugin".

The name is intended to be memorable and broad enough to cover unprocessed notes, snoozed notes, and resurfaced material without encoding "project" semantics.

Current decisions

These decisions were made during initial brainstorming and should be treated as product constraints until explicitly changed.

Keep, not archive

The primary non-snooze triage action is Keep.

Keep means: "This note no longer needs the Triage queue." It should not move the file or imply deletion. The default implementation marks a note with Triage-managed frontmatter, but users can instead configure Keep to add a tag or set an arbitrary frontmatter value such as a category/type/status that naturally removes the note from their filters.

Delete through Obsidian's built-in prompt

Delete should use Obsidian's built-in delete behavior and prompt rather than a custom destructive confirmation flow.

The plugin should not invent its own permanent-delete UX for the MVP.

No project semantics

The plugin should not have first-class project concepts.

Earlier brainstorming included "move to project" and "project notes" as possible actions or exclusions. That has been removed. If a vault has a project category, the user can configure filters using folder, tag, or frontmatter rules. The plugin itself should treat those as ordinary metadata filters.

Triage queue-first, no separate focus mode

The core UI is a scrolling triage queue.

There is no separate one-note-at-a-time focus mode in the MVP. Opening a note in Obsidian is the focused experience.

The triage queue can still have a focused item for keyboard actions, hover behavior, and visual orientation.

Anki-style snoozing

The plugin should support Anki-style resurfacing through snooze actions.

The UI should show the configured day counts directly, with their shortcuts beside them. The plugin should store an actual due date so resurfacing is reliable.

Configurable note classes

Triage is primarily for uncategorized notes and for notes tagged or categorized as configured classes.

For the user's current vault, likely classes include:

• literature
• fleeting
• not categorized

These should not be hardcoded. They are examples of filter configuration.

Non-goals

The MVP should not include:

• Project-specific behavior.
• Moving files during Keep.
• Moving notes into project folders.
• A dedicated focus mode separate from opening notes in Obsidian.
• Custom delete confirmation.
• Complex spaced repetition algorithms.
• Analytics dashboards.
• AI summarization.
• Sync or external service integration.
• A second source of truth for note state outside frontmatter.

Main user experience

The user opens a Triage view in Obsidian. The view shows a scrolling triage queue of eligible notes. Each item shows enough information for quick recognition and triage.

The user can scan the triage queue, move focus with the keyboard, focus items with the mouse, open a note, keep it out of triage, delete it, or snooze it. Current snooze and Keep actions mark the focused card in place so the user can adjust the choice before refreshing; delete removes the card after Obsidian confirms deletion.

The triage queue should feel like a lightweight daily or weekly ritual:

1. Open Triage.
2. Review currently surfaced notes.
3. Keep items that no longer need triage.
4. Snooze items that are not actionable now but should return.
5. Delete items that are not worth keeping.
6. Open notes that deserve deeper editing or linking.

Main view

The main view is a dedicated Obsidian workspace view.

Target MVP elements:

• A compact toolbar for sorting, filtering, and refresh controls.
• A scrolling triage queue of note items.
• Visible quick sort controls.
• Visible triage controls on each item.
• A clear focused-item state.
• Empty states for no eligible notes and no due notes.

Target triage queue item content:

• Note title, if present.
• File basename if no explicit title is available.
• A compact path or source context.
• Created, modified, or configured date source.
• Relevant tags and selected frontmatter fields.
• Content preview up to a configurable length.
• Snooze or kept status if present.
• Triage buttons.

The content preview should strip or tame noisy markdown enough for scanning, but it should preserve the note's actual wording. The preview is not a summary.

Current implementation:

• The main view renders the scrolling triage queue with Obsidian title-bar sort and refresh controls.
• Sort order is global, persistent, and defaults to date modified newest first.
• Refreshing the triage queue reshuffles the list when Random sort is selected.
• A compact queue header shows how many eligible notes are currently rendered out of the full eligible count, and shows an inline refresh link when the queue has been modified.
• Cards currently show title, optional filename below the title, content preview, and configured tags/frontmatter metadata below the preview; path, date, and visible snooze/kept status rows are not implemented yet.
• Collapsed card previews use stripped plain text.
• Expanded card bodies are rendered with Obsidian's markdown renderer.
• A leading markdown heading is removed from the card body when it matches the card title.
• Cards have a faint border and a focused-card visual state.
• Focused cards keep an accent outline on the preview, with a light-theme shadow over the action toolbar below; the toolbar uses a neutral secondary background and does not continue the accent stroke around its sides or bottom.
• Toolbar buttons are borderless compact icon buttons using Obsidian size and spacing variables.
• Toolbar buttons use muted text by default, and selected triage actions use accent color.
• The focused-card toolbar has three logical groups with no visible separators: left-aligned utility actions, centered triage answers, and right-aligned overflow actions.
• The leading toolbar group contains expand/collapse only; opening happens through the note title, Enter, and the focused-note command.
• The centered triage answers are the configured snooze day counts and Keep.
• The centered triage answers show square keycap hints when shortcut display is enabled.
• The centered triage answers can be applied from the focused card with 1, 2, 3, and 4.
• Selecting a triage action keeps the card in place and highlights the selected toolbar action. The note will disappear only after a triage queue refresh if the new state no longer matches the visible triage queue.
• Preview length is configurable as compact, normal, or long.
• Space toggles the focused card between preview and expanded states.
• Escape clears the focused card state and collapses any expanded card.
• Only one card can be focused and expanded at a time.
• An expanded card keeps focus until the user explicitly collapses it.
• The overflow menu contains delete, refresh, and clear snooze when the focused note has snooze state; clear snooze also has the 0 shortcut.

Opening notes

Opening a note is the focused mode.

Expected interactions:

• Clicking the title opens the note.
• Pressing Enter on the focused triage queue item opens the note.
• There should be a command for opening the focused note.

Open behavior can be refined during implementation, but the MVP should use the normal Obsidian interaction model rather than inventing a custom editor.

Focus and navigation behavior

Triage should support both mouse and keyboard review.

Triage queue item focus:

• One triage queue item can be focused at a time.
• No triage queue item receives focused-card state when the view opens.
• Focus should be visually obvious.
• Focus should survive triage queue refresh when the same file remains visible.
• If the focused item disappears after an action, focus should move to the next visible item, then previous item if there is no next item.

Mouse behavior:

• Moving the mouse over a triage queue item focuses it.
• Clicking a triage queue item can focus it without necessarily opening it, except for explicit links or buttons.
• Stationary hover should not steal focus after keyboard navigation.
• Mouse focus should resume once the pointer actually moves.

Keyboard behavior:

• Arrow down or j focuses the next triage queue item.
• Arrow up or k focuses the previous triage queue item.
• If no triage queue item is focused, Arrow down, Arrow up, j, or k focuses the first visible item.
• Enter opens the focused note.
• Space expands or collapses the focused note body.
• Escape clears the focused note state and collapses the focused note body when it is expanded.
• 1 snoozes the focused note for the first configured interval.
• 2 snoozes the focused note for the second configured interval.
• 3 snoozes the focused note for the third configured interval.
• 4 keeps the focused note out of triage.
• 0 clears snooze on the focused note when it has snooze state.
• Triage commands operate on the focused note.
• Keyboard focus and DOM focus must remain accessible.

The interaction precedent is the focused card model in /Users/toto/Developer/obsidian-kanban-view-job.

Triage actions

The MVP triage actions are:

• Open note.
• Delete note.
• Keep note.
• Snooze with shortcut 1.
• Snooze with shortcut 2.
• Snooze with shortcut 3.
• Clear snooze.
• Refresh queue.

Earlier brainstorming included "move to project." That action has been removed.

Keep

Keep removes a note from the Triage queue without moving it.

Keep means: "Reviewed enough that this no longer belongs in the Triage queue."

By default, Keep writes Triage-managed frontmatter. Users can choose one of three Keep behaviors. The selected behavior is the active kept signal used to hide notes from the triage queue:

• Mark as kept: set the configured status field to the configured kept value and set a kept timestamp field.
• Add tag: add a configured kept tag such as #evergreen; notes with the configured kept tag are hidden from the triage queue.
• Set frontmatter value: set a configured frontmatter field/value such as category=evergreen; notes with the configured kept field/value are hidden from the triage queue.

Keep should clear Triage's snooze label and due date fields if present.

Delete

Delete should hand off to Obsidian's built-in delete behavior and confirmation.

The plugin should not silently delete notes.

After deletion, the triage queue should remove the note and move focus to the next sensible item.

Snooze

Snoozing temporarily removes a note from the main triage queue until it is due again. A future setting may allow not-due snoozed notes to be included for review or debugging, but that mode is not implemented.

The three snooze shortcuts should show their configured day counts in the card toolbar.

Default intervals:

• Shortcut 1: 1 day.
• Shortcut 2: 7 days.
• Shortcut 3: 30 days.

The exact intervals are configurable.

Current snooze writes:

• A status indicating the note is snoozed.
• The selected snooze label.
• A concrete due date.

When the due date arrives, the note becomes eligible again.

Future review-history fields may add last-seen and seen-count metadata, but the current implementation does not write review history.

Frontmatter model

All Triage state should live in frontmatter.

Field names must be configurable. The names below are suggested defaults only.

Suggested snoozed note state:

triage_status: snoozed
triage_snooze: shortcut-2
triage_due: 2026-06-07

Default kept note state:

triage_status: kept
triage_kept_at: 2026-05-31

Alternative kept tag state:

tags:
  - evergreen

Alternative kept frontmatter state:

category: evergreen

Suggested status values:

• snoozed
• kept

Untriaged notes can be represented by missing Triage frontmatter. The plugin should not write state merely because a note was displayed. It should write state only after an explicit action such as Keep, snooze, clear snooze, or delete.

Eligibility filters

Eligibility should be configurable and composable.

Current implemented filter types:

• Include folders.
• Exclude folders.
• Include tags.
• Exclude tags.
• Include frontmatter field values.
• Exclude frontmatter field values.
• Include notes missing a frontmatter field.
• Include untagged notes.
• Exclude notes matching the active Keep behavior's kept signal.
• Exclude snoozed notes whose due date is in the future.

Current filter behavior:

• If no include filters are configured, all markdown notes are included.
• Include filters are OR-based.
• Exclude filters are hard blockers and always win.
• Folder filters match a vault-relative folder and its descendants.
• Tag filters normalize the leading # and match tags exactly.
• Frontmatter value filters use exact field=value matching.
• Frontmatter value filters support scalar values and array values.
• Notes missing a configured frontmatter field also match when that field's value is empty.
• The active kept signal runs before the additional exclusion lists.
• Due snoozed notes resurface when their due date is today or earlier.
• Snoozed notes with missing or invalid due dates remain visible so the user can recover them.
• Filtering is read-only and must not write or normalize notes.

The plugin should not hardcode "literature," "fleeting," or "uncategorized." Those are expected user configurations.

Example conceptual configuration for the user's vault:

• Include notes tagged or categorized as literature.
• Include notes tagged or categorized as fleeting.
• Include notes missing the configured category field.

The triage queue applies kept/snoozed state filters and the configured sort order. Peripheral resurfacing is still future work.

Sorting and resurfacing

Quick sort controls are available directly in the main view's Obsidian title bar.

Required sort modes:

• Date modified (newest first).
• Date modified (oldest first).
• Date created (newest first).
• Date created (oldest first).
• Random.

Refreshing while Random is selected should reshuffle the triage queue.

Peripheral mode is a future randomized resurfacing mode. It should be dynamic without being chaotic.

Peripheral mode should consider:

• Due snoozed notes.
• Older notes.
• Notes that have not been reviewed recently.
• Notes with lower seen counts.
• Notes that are otherwise eligible but easy to forget.

Peripheral mode should avoid:

• Showing the exact same ordering every time.
• Repeatedly surfacing the same recently reviewed notes.
• Hiding due snoozed notes behind purely random ordering.

The exact scoring algorithm can be designed during implementation, but the product behavior should feel like a changing work surface rather than a strict task queue.

Settings

Settings should be explicit enough for different vault conventions.

Current settings groups:

• Queue sources.
• Keep and snooze.
• State fields.
• Additional exclusions.
• Display.

Current settings:

• Included folders.
• Excluded folders.
• Included tags.
• Excluded tags.
• Category/frontmatter field names.
• Included category/frontmatter values.
• Excluded category/frontmatter values.
• Whether to include untagged notes.
• Whether to include notes missing the category field.
• Status field name.
• Snooze label field name.
• Due date field name.
• Kept timestamp field name.
• Kept status value.
• Snoozed status value.
• Keep behavior.
• Kept tag.
• Kept frontmatter field.
• Kept frontmatter value.
• Shortcut 1 interval.
• Shortcut 2 interval.
• Shortcut 3 interval.
• Preview length.
• Show filename.
• Metadata fields.
• Show shortcuts.

Planned settings still include advanced behavior and future resurfacing controls.

Current preview length options:

• Compact.
• Normal.
• Long.

Current Keep behavior options:

• Mark as kept.
• Add tag.
• Set frontmatter value.

Settings UI text should follow Obsidian community plugin conventions, including sentence case.

Commands

Commands should be available for user-configured hotkeys. Do not set default hotkeys.

Current commands:

• Open Triage.
• Focus next item.
• Focus previous item.
• Open focused note.
• Delete focused note.
• Keep focused note.
• Snooze focused note with shortcut 1.
• Snooze focused note with shortcut 2.
• Snooze focused note with shortcut 3.
• Clear snooze for focused note.
• Refresh queue.

Current in-view shortcuts:

• 0: Clear snooze for the focused note.
• 1: Snooze focused note for the first configured interval.
• 2: Snooze focused note for the second configured interval.
• 3: Snooze focused note for the third configured interval.
• 4: Keep focused note.

The in-view action toolbar shows shortcuts as square keycaps when Show shortcuts is enabled.

Command names and command ids should avoid redundant words like "command" and should not duplicate the plugin name/id unnecessarily.

Accessibility and Obsidian constraints

Implementation should follow Obsidian community plugin expectations.

Important constraints for future coding agents:

• Use Obsidian DOM helpers for UI construction.
• Keep all interactive elements keyboard accessible.
• Provide ARIA labels for icon-only buttons.
• Preserve visible focus indicators.
• Use touch targets of at least 44 by 44 pixels where practical.
• Use Obsidian CSS variables in plugin-scoped CSS.
• Avoid inline style elements.
• Avoid broad CSS selectors.
• Use Obsidian's path normalization for user-configured paths.
• Use appropriate Obsidian APIs for background frontmatter changes.
• Avoid regex lookbehind for mobile compatibility.
• Do not set default hotkeys.
• Minimize production console logging.

Data and mutation principles

The triage queue should be read-only until the user takes an explicit action.

Rendering the triage queue should not:

• Add frontmatter.
• Update last-seen metadata.
• Increment seen counts.
• Normalize note files.
• Rewrite markdown.

Explicit actions may update frontmatter:

• Keep.
• Snooze with shortcut 1.
• Snooze with shortcut 2.
• Snooze with shortcut 3.
• Clear snooze.

Delete is the exception because it delegates to Obsidian's delete flow rather than writing Triage frontmatter.

Frontmatter changes should be narrowly scoped and should preserve unrelated user metadata.

Empty states

Empty states should be short and operational, not marketing copy.

Expected cases:

• No notes match the current filters.
• No snoozed notes are due.
• The selected folders contain no markdown notes.
• A focused note was deleted or moved outside the active filter.

Empty states should offer practical next steps such as changing filters or refreshing the triage queue.

MVP acceptance criteria

The MVP is acceptable when:

• A user can open a Triage view.
• The view shows eligible markdown notes as a scrolling triage queue.
• The user can configure note eligibility by folders, tags, and frontmatter.
• The user can configure frontmatter field names for Triage state.
• Each triage queue item shows title, context, relevant metadata, and a content preview.
• The triage queue supports quick sort controls.
• The triage queue supports keyboard and mouse focused-item navigation.
• The focused item can be opened, kept, deleted, or snoozed.
• Keep writes frontmatter or a configured tag/frontmatter value without moving the note.
• Snooze writes a label and concrete due date.
• Due snoozed notes resurface.
• Not-due snoozed notes are hidden by default.
• Kept notes are hidden by default.
• Delete uses Obsidian's built-in delete behavior.
• Commands exist for the main focused-item actions.
• No default hotkeys are registered.
• The UI is keyboard accessible.

Future ideas

Possible post-MVP features:

• Named filter presets.
• Multiple Triage views with different local view configurations.
• Weighted peripheral resurfacing controls.
• "Reviewed but keep visible" action.
• Optional review history fields.
• Optional backlink/outlink counts in triage queue items.
• Optional random sample size for large vaults.
• Optional "open in adjacent leaf" behavior.
• Optional kept-note review mode.
• Optional custom snooze labels beyond the three shortcut intervals.

These ideas should not distract from the MVP.

Change log

• 2026-06-12: Renamed plugin identity, view, CSS scope, and default state fields to Triage, and migrated legacy default state field settings to the new Triage names.
• 2026-06-12: Fixed delete-through-prompt refresh behavior, added queue count and basic empty-state variants, moved text settings to commit on blur, removed sort order from settings, preserved modifier-click note opening, and switched cards to roving tabindex.
• 2026-06-12: Added configurable preview metadata for filenames, tags, and selected frontmatter fields.
• 2026-06-12: Changed initial and Escape keyboard focus behavior so the queue can have no focused card, and j/k starts at the first visible card from that state.
• 2026-06-12: Added global persistent triage queue sort order with title-bar sort and refresh controls; Random reshuffles on refresh.
• 2026-06-12: Removed the duplicate focused-card open button and changed expand/collapse to list chevron icons.
• 2026-06-12: Added optional keycap-style shortcut hints to focused-card actions, including Keep.
• 2026-06-12: Replaced user-facing Soon/Later/Someday snooze labels with configured day-count labels and visible shortcuts.
• 2026-05-31: Reframed Archive as Keep: a centered triage answer meaning the note no longer needs the Triage queue.
• 2026-05-31: Added Anki-style focused-card toolbar planning and implementation: left utility actions, centered snooze/Keep actions, and right-side overflow menu with delete, refresh, and clear snooze.
• 2026-05-31: Implemented configurable Keep behavior with three modes: mark as kept, add tag, or set frontmatter value. Configured kept tags and kept frontmatter values are automatic filters before additional exclusions.
• 2026-05-31: Implemented frontmatter-backed snooze, clear snooze, Keep, delete-through-Obsidian-prompt actions, focused-item commands, state filtering for kept and not-due snoozed notes, and triage unit tests.
• 2026-05-31: Added focused-card number shortcuts for the three snooze actions and Keep.
• 2026-05-31: Added 0 as the Clear snooze shortcut and changed action feedback so selected triage actions stay highlighted in place instead of immediately refreshing the triage queue.
• 2026-05-30: Made the selected card receive DOM focus by default when the view opens so keyboard navigation works before mouse movement.
• 2026-05-30: Changed expanded-card focus behavior so expanded cards retain focus until explicitly collapsed with Space, Escape, or the toolbar button.
• 2026-05-30: Added Vim-style j/k navigation for moving focus through triage queue cards.
• 2026-05-30: Added a focused-card action toolbar below the card outline, using an accent-colored strip with borderless icon buttons for the currently implemented open and expand/collapse actions.
• 2026-05-30: Adjusted card bodies so collapsed previews use stripped plain text, while expanded cards render markdown without repeating a leading title heading.
• 2026-05-30: Implemented focused-card styling and rendered body previews: faint borders, mouse/keyboard focus, Space-to-expand behavior, single expanded card behavior, and compact/normal/long preview settings.
• 2026-05-30: Implemented the filtering-only slice: settings persistence, settings UI, pure filtering logic, triage queue integration, and unit tests. Sorting, snoozing, archive behavior, triage actions, frontmatter writes, and note mutation remain out of scope.

2026-05-30 - Initial brainstorm

• Defined the plugin as a triage stream for notes that are not categorized as projects or are otherwise loose material.
• Proposed chronological triage queue ordering, preview snippets, configurable sorting/filtering, randomized resurfacing, Anki-style triage buttons, shortcuts, and frontmatter-backed status.
• Considered "Timeline Triage" and related names.
• Identified Andy Matuschak's "Peripheral vision" as inspiration.

2026-05-30 - Product decisions after user feedback

• Chose "Triage" as the preferred name.
• Changed archive behavior to frontmatter-only.
• Removed project-specific semantics.
• Removed "move to project" from the MVP.
• Kept Anki-style resurfacing, with user-facing snooze actions based on configurable intervals.
• Removed separate focus mode. Opening a note in Obsidian is the focused mode.
• Kept a focused item inside the scrolling triage queue for keyboard actions and mouse navigation.
• Adopted focused-card interaction precedent from /Users/toto/Developer/obsidian-kanban-view-job.
• Confirmed delete should use Obsidian's built-in delete prompt/flow.

2026-05-30 - Workspace scaffold

• Added an Obsidian plugin workspace with TypeScript, esbuild, ESLint, manifest, styles, and version metadata.
• Added an initial Triage view, command registrations, settings defaults, triage queue rendering, sorting controls, focused-item navigation, and frontmatter-backed archive and snooze actions.
• Added support for linking the development build to a test vault with a .hotreload marker for live testing.

2026-05-30 - Scaffold cleanup

• Removed premature MVP features from the scaffold: settings, filters, sort controls, archive, snooze, delete, frontmatter writes, focused-item commands, and item metadata rows.
• Reduced the view to a simple list of markdown notes showing only title and content preview.
• Kept only the ribbon button and Open queue command for opening the view.
• Added AGENTS.md, a small preview test harness, and GitHub Actions CI.

Agent update protocol

Future AI coding agents should update this document as implementation decisions become real.

When changing behavior, update:

• Status at the top.
• Current decisions if a decision changes.
• MVP acceptance criteria if scope changes.
• Change log with date and concise rationale.
• Any frontmatter field hints if defaults change.

Do not paste implementation code into this spec. Small frontmatter examples are allowed because they describe user-visible note metadata.