Retrospective Format

At the end of each phase, an implementation retrospective evaluates what worked well and what needs improvement. The goal is to refine planning documents so the next phase (or the next app built from the same foundation) starts stronger.

Purpose

The retrospective evaluates planning documents against implementation reality. It does not evaluate the code itself -- that is the job of code review and automated quality checks. The retrospective answers: "Did our plans lead to efficient implementation, or did we waste time on avoidable problems?"

Structure

Each retrospective is organized by ticket (implementation unit). For each ticket:

What Worked Well

Specific planning recommendations that translated directly into working code. These validate the decision guides and should be preserved.

Example from Phase 0: "The withTenantContext transaction wrapper pattern worked exactly as the guides prescribed -- set_config(..., true) for transaction-scoped variables, wrapping the callback in db.transaction."

What Needs to Change

Specific problems encountered during implementation, with:

1. Problem -- what went wrong
2. What happened -- the debugging story and eventual fix
3. Root cause (when applicable) -- the underlying issue, not just the symptom
4. Proposed changes -- concrete edits to specific documents, with exact wording

Example from Phase 0: "Docker Compose PostgreSQL 18 volume mount path has changed. The docker-compose.yml from TRO-6 mounted at /var/lib/postgresql/data. PostgreSQL 18 changed its data directory layout. Fix: change to /var/lib/postgresql."

No Changes Needed

Items that were flagged as risks but caused no issues. These are valuable because they confirm that certain concerns were addressed correctly and do not need further attention.

Deferred Items

Work that was consciously deferred from the ticket, with the reason and the trigger condition for when to revisit.

Additional Work Beyond Original Ticket

Scope that expanded during implementation. This feeds back into future ticket estimation -- if tickets consistently grow beyond their original scope, the estimation process needs adjustment.

Phase 0 Retrospective Findings

The Phase 0 retrospective (docs/phase-0/Phase 0 - Implementation Retrospective.md) covered 8 implementation areas and produced 50+ specific findings. Key themes:

Ordering Matters More Than Expected

The original plan had database and auth work before GCP project creation, which is impossible -- Cloud SQL requires a GCP project. The corrected sequence: scaffolding, CI, cloud infrastructure, database, auth, API, observability.

CI as the second step (immediately after scaffolding) caught an ESLint bug on the first PR that would have been silently present for weeks.

External Platform Dependencies Should Be Deferred

Inngest (background jobs) and Upstash Redis (caching) were planned for Phase 0 but had no real callers. The founder correctly identified that external platforms have ongoing cognitive cost (accounts, dashboards, secrets, billing) even at the free tier. Code-only libraries (Pino, CASL, Zod) have near-zero ongoing cost and can be added freely. The principle: scaffold the package, but do not configure production accounts until the first feature needs the service.

AI Agent Limitations Are Predictable

Multiple findings related to AI agents failing at specific tasks:

• Version numbers are stale -- every dependency version the LLM suggested was wrong. Always run npm view <package> version before adding to the catalog.
• SVG recreation from raster images requires 10+ iterations. The founder must provide exact hex colors, gradient directions, and vertex coordinates.
• Interactive CLI tools fail in non-interactive environments. Prefer manual configuration over wizard CLIs for agent workflows.
• .env loading in monorepos caused the same bug twice (TRO-9 and TRO-12) despite being documented in the retrospective after the first occurrence. Agent sessions do not read retrospectives unless explicitly prompted.

Security-Critical Code Requires Extra Scrutiny

The most dangerous bug found in Phase 0 was in tenantProcedure -- the bare db pool was passed to downstream procedures instead of the RLS-scoped transaction tx. Queries succeeded but returned data from all tenants. The bug was silent because RLS tests ran at the SQL level, not through the tRPC middleware chain.

This validated the rule: auth, RLS/tenant isolation, payments, and data access control always require manual review.

How Findings Feed Back

Retrospective findings produce three types of outputs:

1. Document changes -- proposed edits to planning guides, CLAUDE.md files, and decision documents. These are applied immediately.
2. Process changes -- new rules or checklists added to the development workflow. These are encoded in CLAUDE.md or guide documents.
3. Deferred items -- work that should happen in a future phase, tracked in Linear with explicit trigger conditions.

The feedback loop closes when the proposed changes are applied and the next phase's implementation validates them.

Cross-Domain References

• Phase Approach -- the phase model that retrospectives evaluate
• Decision-Making Process -- how decisions are made before implementation
• Agent Workflow (SPTI) -- the agent methodology that retrospectives refine
• Identity & Access -- Tenant Isolation -- the RLS patterns where the most critical Phase 0 bug was found