From 72e868dda1f96dd132d3e1b6bfaa54ed1c5883ef Mon Sep 17 00:00:00 2001 From: ginnoir Date: Fri, 3 Jul 2026 22:26:35 -0500 Subject: [PATCH] docs: add post-v0.1 backlog triage design Capture approved issue map, P1 batch order, E2E plans, and implementation-pass scope for the next work batch. --- .../specs/2026-07-03-backlog-triage-design.md | 197 ++++++++++++++++++ 1 file changed, 197 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-03-backlog-triage-design.md diff --git a/docs/superpowers/specs/2026-07-03-backlog-triage-design.md b/docs/superpowers/specs/2026-07-03-backlog-triage-design.md new file mode 100644 index 0000000..67869c7 --- /dev/null +++ b/docs/superpowers/specs/2026-07-03-backlog-triage-design.md @@ -0,0 +1,197 @@ +# 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/.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