79 lines
7.8 KiB
Markdown
79 lines
7.8 KiB
Markdown
|
---
|
|||
|
|
summary: Decision + day-1 pilot plan for the vault-native backlog (task notes + push-first surfacing + Bases kanban spike), including the perspectives-panel verdict and the Fable-orchestrator/cheap-subagent execution plan
|
|||
|
|
tags:
|
|||
|
|
- scope/global
|
|||
|
|
- type/decision
|
|||
|
|
- domain/task-management
|
|||
|
|
- tool/claude-code
|
|||
|
|
- project/cc-os
|
|||
|
|
status: accepted-pending-pilot
|
|||
|
|
last_reviewed: 2026-07-06
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
# Vault-native backlog: decision and pilot plan (2026-07-06)
|
|||
|
|
|
|||
|
|
Research behind this decision: [[backlog-system-options-research]].
|
|||
|
|
|
|||
|
|
## Decision
|
|||
|
|
|
|||
|
|
Build the personal cross-project backlog **inside the SecondBrain vault**: one note per backlog item (`task` note type), a push-first surfacing layer, Obsidian Bases kanban views as the visual dashboard, and a minimal deterministic CLI. Forgejo issues remain the code-execution tracker (rule: **Forgejo = code/arch/deployment work inside a repo; vault = everything else**; vault tasks may wikilink/reference Forgejo issues). Fallbacks, in order: Backlog.md (if the Bases board spike fails), Planka + community MCP (if markdown-native fails or a standalone/mobile dashboard becomes a hard requirement).
|
|||
|
|
|
|||
|
|
## Perspectives panel verdict (4 agents: devils-advocate, simplifier, implementer, premortem)
|
|||
|
|
|
|||
|
|
The panel kept the vault-native direction but **inverted the build order**. Consensus corrections to the original proposal:
|
|||
|
|
|
|||
|
|
1. **The load-bearing layer is push/surfacing, not the data store.** A board that must be opened and a SessionStart hook that fires only when a session starts both fail the ADHD constraint (out of sight = forgotten). The recurring-maintenance scenario (frozen spigots) fails in any week with no Claude sessions. → Push first, board later.
|
|||
|
|
2. **Three reliability requirements or the system is "theater within three months"** (premortem): (a) time-aware idempotent `tick` with a staleness catch-up check, (b) SessionStart text summary of due/P0 items, (c) one-field quick-add capture.
|
|||
|
|
3. **Daemon contradiction resolved honestly** (implementer): a `systemd --user` *timer* (one-shot daily, not a daemon) firing `tick` + an ntfy/email push is the minimum genuine fix for no-session weeks. Recurrence math must be elapsed-time catch-up ("instantiate all missed occurrences since last tick"), never one-session-one-tick.
|
|||
|
|
4. **YAGNI cuts** (simplifier): no recur rule engine (simple offsets like `recur: +1y`); no full CLI at launch (`tick` + quick-add only; list/move/next deferred to demand); board built only after live task data exists (a Bases saved view is minutes of work once notes exist); AI comms drafting (tenant emails) is week-3; effort field + quick-win filter is week-4.
|
|||
|
|
5. **Spike before building** (implementer): verify Base Board / bases-kanban against fixture notes — multi-property filters, ordinal priority sort (use sortable encodings: P0–P3, E1–E3; never low/medium/high strings), drag-drop frontmatter write-back, missing-property rendering, mobile (expect desktop-only). Also spike the Obsidian-open-buffer vs. external-frontmatter-write collision, and verify CLI YAML serialization round-trips byte-identically with Obsidian's `processFrontMatter` (serializer churn pollutes git diffs and widens the conflict surface with the existing `vault_sync.py` SessionEnd push).
|
|||
|
|
6. **Task-rot defense**: the quarterly someday-review is itself a recurring P0 task in the system (dogfooding, zero extra code).
|
|||
|
|
7. **Fair challenge accepted** (devils-advocate): Backlog.md was dismissed too fast (wikilinks do resolve into its files); it stays the named fallback and the ergonomic template for the CLI. And the morning surface should eventually include top Forgejo issues (via `tea`) so the two trackers get one unified decision point (week-2).
|
|||
|
|
|
|||
|
|
## Task note schema (v1 — to be formalized via /os-vault:design-template new-type lifecycle)
|
|||
|
|
|
|||
|
|
```yaml
|
|||
|
|
---
|
|||
|
|
summary: <one-line>
|
|||
|
|
tags: [scope/global, type/task, <client|project|domain facet>]
|
|||
|
|
status: backlog | next | doing | done | someday
|
|||
|
|
priority: P0 | P1 | P2 | P3 # sortable encoding, verified in spike
|
|||
|
|
due: YYYY-MM-DD # optional
|
|||
|
|
recur: +1y | +6m | +3m | +1m # optional, simple offset only — no rule engine
|
|||
|
|
---
|
|||
|
|
<body: context + wikilinks to how-tos, client notes, property/contractor notes,
|
|||
|
|
Forgejo issue URLs — the Notion rental-property pattern>
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
Open spike question: whether `status`/`priority` live as frontmatter fields (Bases-friendly, likely) vs. tags — decide during the spike, record in vault-conventions.md.
|
|||
|
|
|
|||
|
|
## Pilot plan — Fable orchestrates, cheap models do grunt work (runnable in one day)
|
|||
|
|
|
|||
|
|
Fable's role throughout: sequencing, design decisions, spike-result judgment, reviewing every subagent deliverable before it lands, updating vault-conventions.md and cc-os docs/ADR at the end.
|
|||
|
|
|
|||
|
|
**Phase 0 — schema + fixtures (parallel, ~30 min)**
|
|||
|
|
- haiku subagent: create `_templates/task.md` + 8–10 fixture task notes in the vault (real content: spigot winterization due 2026-10-15 recur +1y; Woodfin HVAC/electrical/plumbing checkups; 2–3 cc-os someday items — including "adopt Storybloq's handover-doc pattern" as the first captured down-the-road idea; 1–2 client items). Mechanical work from a spec Fable writes.
|
|||
|
|
- Fable: write the spec; verify facet/frontmatter correctness against vault-conventions.md.
|
|||
|
|
|
|||
|
|
**Phase 1 — the two spikes (the riskiest assumptions, before any CLI code)**
|
|||
|
|
- Bases board spike: human-in-the-loop (Obsidian GUI required). Fable/haiku prepares a step-by-step checklist: install Base Board (and bases-kanban as alternate), build a board over `type/task` fixtures, test the six capabilities from panel point 5. Gate: pass → continue; fail → switch dashboard track to Backlog.md, keep everything else.
|
|||
|
|
- sonnet subagent: concurrent-write spike — script that externally rewrites frontmatter while the file is open/dirty in Obsidian; document observed behavior (reload/prompt/clobber) and the serializer round-trip check.
|
|||
|
|
|
|||
|
|
**Phase 2 — the three must-haves (parallel once Phase 1 passes)**
|
|||
|
|
- sonnet subagent: `tick` — deterministic, idempotent, elapsed-time catch-up (advance done+recurring tasks by their offset, flag overdue); plus `backlog add --quick "title"` (defaults: status=backlog, priority=P2). Ruby, Sandi Metz style, thin bins over a small lib — mirror the os-adr `lib/` + `bin/` pattern in cc-os. Includes model-free tests.
|
|||
|
|
- sonnet subagent: SessionStart surfacing hook for the os-vault plugin (Python, matching existing hooks): terse 3–5-line block of due + P0 items, plus the ≥7-days-since-last-tick staleness check that runs `tick` catch-up inline. Timestamp state file in the vault `.state/` (gitignored).
|
|||
|
|
- haiku subagent: `systemd --user` timer + service units firing daily `tick`, with ntfy (or mail) push when property-domain tasks come due — the no-session-week safety net.
|
|||
|
|
- Fable: review all three (correctness, invariants, naming per [[cc-os-plugin-skill-naming-convention]]), integrate into `cc-os/plugins/os-vault/`, run `bin/refresh-plugins`, verify a fresh session surfaces the fixtures.
|
|||
|
|
|
|||
|
|
**Phase 3 — close-out (Fable)**
|
|||
|
|
- Update vault-conventions.md (task type), cc-os CLAUDE.md + build docs, and record the decision as an ADR in cc-os.
|
|||
|
|
- Live for one week with real tasks. Week-2 review gates (each pre-captured as a task note): noisy summary → filter tighter; board friction → revisit Backlog.md; capture demand → extend CLI (`list/move/next`); add Forgejo top-issues to the morning surface.
|
|||
|
|
|
|||
|
|
**Explicitly deferred (each captured as a `someday` task, not built):** recur rule engine, effort/quick-win filter, AI comms drafting, mobile dashboard, per-domain board polish, Planka migration.
|
|||
|
|
|
|||
|
|
## Success criteria (from premortem)
|
|||
|
|
|
|||
|
|
1. Recurring tasks cannot silently miss a week (timer + staleness check both firing).
|
|||
|
|
2. Due/P0 items visible every working morning with zero navigation (session surface, later board).
|
|||
|
|
3. Capturing a task costs one command or one sentence to Claude.
|