xtablo-source/.planning/RETROSPECTIVE.md

# Project Retrospective

A living document updated after each milestone. Lessons feed forward into future planning.

## Milestone: v2.0 — Collaboration, Planning, and Social Sign-in

**Shipped:** 2026-05-16
**Phases:** 5 | **Plans:** 18 | **Sessions:** multiple GSD sessions

### What Was Built

- Google sign-in with Xtablo-owned user/session issuance and Apple sign-in disabled for the shipped scope.
- One-level etapes for organizing tasks while preserving existing kanban behavior.
- Tablo-owned scheduled events plus an authenticated personal planning agenda.
- Native per-tablo discussion history, posting, unread state, and realtime SSE delivery.

### What Worked

- The Go + HTMX stack handled new auth, planning, and realtime surfaces without introducing a JS framework or managed chat provider.
- DB-backed handler tests gave strong coverage for ownership, validation, and cross-tablo aggregation.
- UAT feedback during Phase 12 caught real browser behavior around duplicate rows and composer reset.

### What Was Inefficient

- Milestone close happened after v3.0 was already initialized, so archival had to preserve current v3 planning files instead of using the standard current-milestone deletion path.
- Some verification artifacts lagged behind shipped behavior, which made milestone audit status noisier than implementation state.
- Earlier v1 UAT/verification records still carry human-needed or partial statuses and should be cleaned separately if strict historical reporting matters.

### Patterns Established

- Use owned Postgres queries plus handler tests as the primary guardrail for cross-user isolation.
- Keep social identity providers as login inputs only; Xtablo sessions remain authoritative.
- For v2 realtime, SSE receive plus HTMX POST send is sufficient and keeps infrastructure local.
- Validation files should be closed immediately after phase execution to avoid stale milestone audits.

### Key Lessons

1. Archive a milestone before starting the next one, or make the close workflow explicitly support archival from a historical commit.
2. Treat `*-VERIFICATION.md` as a required phase exit artifact, not a later audit cleanup.
3. Browser UAT remains necessary for HTMX swap/reset behavior even when handler tests are green.

### Cost Observations

- Model mix: not tracked.
- Sessions: multiple interactive GSD sessions.
- Notable: most rework came from artifact hygiene and UAT-discovered browser behavior, not from core backend design.

---

## Milestone: v3.0 — Design System & Visual Polish

**Shipped:** 2026-05-17
**Phases:** 5 (13-17) | **Plans:** 16

### What Was Built

- Full CSS token vocabulary in `base.css` (colors, spacing, typography, shadows, gradients)
- 11 typed templ components: button, badge, card, modal, empty-state, table, icon-button, input, textarea, select, form-field
- Build-tag-gated `/ui-catalog` visual verification page for the design system
- Auth pages (login/signup) with gradient animated background, auth-card layout, Google Material Design sign-in button
- App shell sidebar with brand section, nav icons, tablo list section, user footer
- Project-card tablo grid with color avatars, creation date, action controls
- Tablo detail: project-card-top header, tasks-section kanban, etapes section, files `@ui.Table` with `@ui.EmptyState`
- Chat view: own-vs-others message bubbles with brand-tint right-alignment
- Planning view: day-separator event list using overview-section layout

### What Worked

- Building the design system foundation (Phase 13) before any surface work paid off — phases 14-17 moved fast because components were ready
- Build-tag catalog (`just catalog`) made visual verification frictionless between phases
- Air CSS watching (added in Phase 14) eliminated manual restart friction for the rest of the milestone
- TDD for view model logic (planning view, chat IsOwn) caught integration bugs before browser verify

### What Was Inefficient

- REQUIREMENTS.md checkboxes for DASH-01/02/03 were not ticked even after Phase 15 completed — stale data discovered only at milestone close
- Phase 13 summary one-liners were raw "Task 1 —" prefixes from the executor rather than human-readable accomplishments — cleaned manually at close
- Some ROADMAP.md phase entries had stale "1/2 plans executed" counts that didn't reflect actual SUMMARY.md files

### Patterns Established

- Design system → auth surface → dashboard → detail → auxiliary (chat/planning) is the right reskin order
- `@ui.Table` + `@ui.EmptyState` as a pair for any list view
- `@AppLayout` wraps all authenticated pages; `@AuthLayout` wraps auth pages — switching is done by changing the outer template
- Build tags (`//go:build catalog` + `//go:build !catalog` stub) as the idiom for dev-only routes

### Key Lessons

- Validate REQUIREMENTS.md checkboxes during phase completion, not at milestone close
- Phase SUMMARY.md one-liners should be written by the executor in final form; raw task names create cleanup work at milestone close
- CSS dev-watch in air is non-negotiable for any CSS-heavy phase — add it at project start, not mid-milestone
- Catalog-first is worthwhile for design systems: visual inventory before any surface application prevents design drift

### Cost Observations

- 2-day milestone (2026-05-16 → 2026-05-17)
- 150 files, +23,505/−993 lines across 128 commits
- Most expensive phase: Phase 14 (auth pages) — auth_components + auth_layout from scratch took iteration
- Fastest phase: Phase 13 Plan 05 (catalog) — 3 minutes once components existed

---

## Cross-Milestone Trends

### Process Evolution

| Milestone | Sessions | Phases | Key Change |
|-----------|----------|--------|------------|
| v2.0 | multiple | 5 | Collaboration, scheduling, and realtime work stayed inside Go + HTMX; artifact hygiene needs tighter close discipline. |
| v3.0 | multiple | 5 | Design-system-first approach validated; surface reskins moved fast. Stale requirement checkboxes and raw summary one-liners are recurring close-time friction. |

### Cumulative Quality

| Milestone | Tests | Coverage | Zero-Dep Additions |
|-----------|-------|----------|-------------------|
| v2.0 | Go handler/DB suites plus browser UAT | Strong behavior coverage; some archive artifacts deferred | Native SSE chat, server-owned sessions, Postgres-backed planning |
| v3.0 | TDD for view models (planning, chat IsOwn); browser verify checkpoints | Visual correctness tested via catalog + human UAT; unit coverage on behavior helpers | Design system (no new runtime deps); build-tag-gated catalog route |

### Top Lessons

1. Close phase validation and verification artifacts before running milestone audit.
2. Keep milestone archival before next-milestone initialization when possible.
3. Preserve browser UAT for HTMX interaction behavior.
4. Check REQUIREMENTS.md checkboxes during phase execution, not at milestone close — stale checkboxes create friction.
5. Design-system-first pays dividends: build the component library, verify in catalog, then apply to surfaces.
6. Add CSS dev-watch (Air) at project start — it's always needed for CSS-heavy work.