ginnoir
72e868dda1
Capture approved issue map, P1 batch order, E2E plans, and implementation-pass scope for the next work batch.
198 lines
14 KiB
Markdown
198 lines
14 KiB
Markdown
# 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
|