famapp/docs/superpowers/specs/2026-07-03-backlog-triage-design.md

Backlog triage, issues, E2E coverage, and next-batch planning

Date: 2026-07-03 Status: approved (design); implementation pass not started

Goal

Turn the post-v0.1 backlog into an actionable state: one Gitea issue per item (epics with sub-issues where needed), Playwright regression plans for every bug, P1 docs/tasks/ specs, ADR placeholders for cross-cutting choices, STATUS/ARCHITECTURE updates, and a prioritized next-batch plan.

Decisions (interview)

Topic	Choice
Rich text for journal	Pull shared editor ADR + component into P1; full notes overhaul in the same batch (editor, render formatting everywhere, mobile overflow).
Batch ordering	Bugs first, then features.
Spec depth	Full backlog issues now; full docs/tasks/ only for P1; P2/P3 get issues + light epic checklists.
Organization model	Issue-centric: Gitea is source of truth for work items; task briefs are the agent execution format for P1.
API timing	API early: after bugs, API foundation for existing modules; journal and notes extend it; LLM agent last.

Approaches considered

1. Issue-centric (chosen). Gitea issues own tracking; P1 task briefs link from issues; ADRs gate cross-cutting work; E2E criteria live on issues and land with PRs.
2. Task-doc-centric. docs/tasks/ primary; Gitea thin stubs. Weaker epic/sub-issue tracking.
3. Monolithic batch plan. One mega-issue per priority tier. Fights one-issue-per-item and partial progress.

Issue map and labels

Labels: bug | enhancement | feature | epic | research
Priority labels: priority/p1 | priority/p2 | priority/p3

#	Title	Label	Priority	Notes
1	Quick-add opens create UI, not module page	bug	P1
2	Dashboard edit mode renders live widgets at true size	bug	P1
3	Garden container plant count wrong	bug	P1	Audit sibling counts
4	Bangs not editable (add edit + delete)	bug	P1
5	Notes overflow horizontally on mobile	bug	P1	Closed with / blocked by #10
6	Missing back navigation — audit + shared affordance	bug	P1	Sweep all detail routes
7	Calendar reminders overhaul	enhancement	P2	Builds on task 41
8	Lists index: inline task add + list property edit	enhancement	P2
9	Comments on lists and tasks	feature	P2	Consider generic comment component
10	Notes editor overhaul (shared rich-text)	enhancement / epic children	P1	Pulled into P1; ADR 0004
11	Bang stats dashboard widget	enhancement	P2	Related to #4; not blocking
12	Appearance / theming options	epic	P3	Feasibility first
13	Journal module	epic	P1	Sub-issues; depends on #10 + API foundation
14	API + LLM agent chat	epic	P1	API children early; agent children last
15	Pets module	epic	P2	Garden-shaped; light checklist
16	Shopping/pantry module	epic	P2	Design before build; light checklist
17	Backups & exports	epic	P2	Extends task 60; light checklist
18	GPS locations for calendar events	research	P3	Issue only
19	Lists ↔ notes cohesion	research	P3	Proposal/ADR later; not code

Epic children (file as separate issues)

#10 Shared rich-text / notes overhaul

1. Research ADR (library choice, storage format, shared component contract)
2. Shared editor component
3. Notes create/edit wiring
4. Render formatting on all notes surfaces (index, widgets, share view)
5. Mobile overflow fix (closes #5)

#13 Journal

1. Research ADR (mood/journal libs; build-vs-adopt)
2. Schema + CRUD
3. Index (recent entries, browse all, entry-day calendar)
4. Entry detail + create (date/time required; all else optional)
5. Mood tracker view
6. Insights/stats views
7. E2E happy path
8. Journal API endpoints (additive on API foundation)

#14 API + LLM

1. Architecture ADR (token auth vs OIDC session; API shape; OpenAI-compatible provider; MCP yes/no)
2. API surface + token auth + docs for existing modules (calendar, lists, notes, garden, bangs; dashboards as needed)
3. Agent chat UI
4. Tool-calling mapped to API
5. Smoke tests (mock provider in CI)

P2/P3 epics (#12, #15–17): epic body holds a light checklist only — no child issues until that batch.

Issue body template

Every issue includes:

• Background / current behavior
• Expected behavior or feature description
• Acceptance criteria (including E2E where applicable)
• Priority label
• Links: docs/tasks/… when present, blocked-by / related issues

P1 batch order

Strict sequence:

Step	Work	Issues	Task brief(s)
1	Quick-add opens create dialogs/sheets	#1	80-quick-add-create-ui.md
2	Dashboard edit mode live widgets	#2	81-dashboard-edit-live-widgets.md
3	Garden plant count	#3	82-garden-plant-count.md
4	Bang edit + delete	#4	83-bang-edit-delete.md
5	Back-nav audit + shared header	#6	84-back-navigation.md
6	API ADR + token auth + endpoints for existing modules	#14 (API children)	ADR 0006-api-llm-agent.md + 87-api-surface.md
7	Shared rich-text + full notes overhaul (+ mobile overflow); extend notes API if needed	#10, #5	ADR 0004-rich-text-editor.md + 85-rich-text-notes.md
8	Journal module (UI + journal API in same epic)	#13 (+ children)	ADR 0005-journal-research.md + 86-journal-module.md
9	LLM agent chat	#14 (agent children)	88-llm-agent-chat.md

Rules

• API is additive; no freeze that blocks journal. New modules document/register endpoints as they ship.
• #14 epic stays open across steps 6 and 9 (API early, agent late).
• #13 depends on #10 (editor) and on API foundation existing.
• #5 closes with #10.
• Task numbering continues after 76 (80+). Do not renumber existing tasks.
• docs/tasks/README.md gains Phase 9 — Post-v0.1.
• P2/P3: Gitea issues only until their batch; STATUS may list them under Backlog.

E2E plan

Follow tests/e2e/*.spec.ts patterns (dev-login storage state, happy-path assertions). Regression tests land with each bug/feature PR, not as a separate upfront suite.

Bugs

Bug	Spec strategy
Quick-add create UI	Extend dashboard.spec.ts and/or quick-add.spec.ts: FAB action opens dialog/sheet with create controls, not only navigation.
Dashboard edit live size	Extend dashboard.spec.ts: ?edit=1 shows real widget content (e.g. Recent activity); prefer stable height assertion only if non-flaky.
Garden plant count	Extend garden.spec.ts: plant in container → count ≥ 1.
Bang edit/delete	New bangs.spec.ts: record → edit date → assert → delete → assert gone.
Notes mobile overflow	Extend notes.spec.ts at 375px: no horizontal overflow; lands with #10.
Back navigation	navigation.spec.ts or per-module: detail routes expose Back and return to parent.

P1 features

Feature	Coverage
API surface	Vitest for auth + route handlers; optional Playwright smoke only if useful.
Rich-text / notes	notes.spec.ts: formatted note visible on detail + other surfaces.
Journal	New journal.spec.ts: minimal entry → recent list → detail → mood tracker loads.
LLM agent	Smoke with mock/stub provider in test env; no live LLM in CI.

Docs and ADRs

P1 task briefs (implementation pass)

File	Covers
80–84	One brief per bug (quick-add, dashboard edit, plant count, bangs, back-nav)
85-rich-text-notes.md	Shared editor + full notes overhaul + mobile overflow
86-journal-module.md	Journal epic (split later only if execution needs it)
87-api-surface.md	Token auth + API for existing modules
88-llm-agent-chat.md	Agent UI + OpenAI-compatible tools

Format: Goal / Why / Depends on / Scope / Out of scope / Acceptance criteria / Notes. Each brief links its Gitea issue(s).

ADRs

ADR	Topic	Gates
0004-rich-text-editor.md	Library (e.g. TipTap), storage format, shared component contract	85, journal body
0005-journal-research.md	Build-vs-adopt for mood/journal UI and charts	86 implementation
0006-api-llm-agent.md	Token auth vs OIDC; API shape; OpenAI-compatible client; MCP decision	87 then 88

Triage pass stubs titles in docs/decisions/README.md (and stub files pointing at epic issues). Full ADR bodies when that step runs.

P2/P3 research (#18, #19, appearance) remain issue-only until their batch.

STATUS / ARCHITECTURE

• STATUS.md: replace stale “Ready to tag v0.1.0” next-up with Phase 9 batch order, link to this design doc and Gitea issues.
• ARCHITECTURE.md: light placeholders only (/api/v1, journal module) — no invented detail. Full diagrams when modules land.

Implementation pass (next execution session)

No application feature code in this pass.

1. Commit this design doc (done when design is accepted).
2. File Gitea issues on gitea.ginnoir.com/ginnoir/famapp for all 19 items; full children for epics #10, #13, #14; light checklists on P2/P3 epics #12, #15–17. Labels + priority as above. On auth failure: write docs/issues-drafts/<slug>.md and report.
3. Write P1 task briefs 80–88 and update docs/tasks/README.md Phase 9.
4. Stub ADRs 0004–0006 (title + pointer to epic issues).
5. Update STATUS.md Next-up; light ARCHITECTURE touch if needed.
6. Vault write-back to Famapp/_Claude.md.

Out of scope for implementation pass: Playwright code, schema changes, module implementation, full ADR research bodies.

Success criteria: every backlog item has a Gitea URL (or draft file); P1 has executable task briefs; STATUS points agents at step 1 (bugs).

Out of scope (this design)

• Implementing any bug fix or feature
• Renumbering or rewriting existing docs/tasks/01–76
• P2/P3 full task briefs or ADRs
• Live LLM integration in CI
• Forward-auth for non-famapp services
• Multi-household UI