ginnoir/famapp
1
0
Fork 0
Code Issues 7 Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add post-v0.1 backlog triage design

Browse Source 
Capture approved issue map, P1 batch order, E2E plans,
and implementation-pass scope for the next work batch.
This commit is contained in:
ginnoir
2026-07-03 22:26:35 -05:00
parent 3d825fba20
commit 72e868dda1
1 changed files with 197 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/superpowers/specs/2026-07-03-backlog-triage-design.md
+197
View File
@@ -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/<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