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.