# Weekly Retrospective — 2026-04-08 to 2026-04-15

**Branch:** `dev-gem` · **Author:** David Petrie · **Commits:** 21 · **Reverts:** 0

---

## At a glance

| Metric | Value |
|---|---|
| Active days | 3 of 7 (04-09, 04-10, 04-15) |
| Commit distribution | 6 · 1 · 14 — bursty, heavily today-weighted |
| Largest commit | `14fc330d` Update docs — 2,550 insertions across 20 files |
| Biggest refactor | `cbc3ff71` npm audit + auth — 1,146 ins / 1,154 del across 14 files |
| New SPEC docs | 2 (OAuth provider, API keys dashboard) |
| Hotspots | `docs/` (20+ files), `plans/14-*`, `plans/15-*`, `apps/admin_api/admin_api.ts`, `auth/` |

## What went well

- **Spec-first discipline paid off.** Two major planning artifacts landed (`be51ee29` OAuth, `a524bdd9` OAuth revision, `d9272a1b` API keys plan update at 1,496 lines) with Mermaid diagrams, phased rollouts, and explicit open questions. This matches the strongest historical pattern.
- **Docs overhaul completed.** `b7495532` (-1,165 net), `e86444e1`, and `14fc330d` (+2,550) form a coherent reorg sweep. Net content gain plus a cleaner structure.
- **Auth surface hardened aggressively in one sitting.** `cbc3ff71` (npm audit + auth fixes), `fb759068` (auth upgrades), `bdc48fa0` (auth integration test redo), `46f0f289` (removed old OPENAI key), `78c33592` (health check), `13f1649a` (arda wrapper bug). Good security hygiene.
- **Fabricator correctness fix.** `6843f658` quantity-aware line item handling — 322 insertions, looks like a real correctness improvement not a patch.
- **Zero reverts.** Over 21 commits including three 1,000+ line changes, nothing had to be rolled back.

## What didn't go well

- **Commit batching.** A 4-day gap (04-11 to 04-14) with no commits, then 14 today. Long unsaved work increases loss risk and makes bisect painful. The "Various fixes and changes after npm audit, auth test run" (`cbc3ff71`) mixes npm audit fixes, auth upgrades, and test changes into one commit — hard to review, hard to revert cleanly.
- **Two "Move docs" commits in ~24h** (`e86444e1`, `b7495532`) indicate the first reorganization wasn't right. Not expensive since docs are low-risk, but suggests planning the target structure before the first move would have saved effort.
- **"Fix diagram errors" (`8522ab96`) arrived after docs shipped.** Mermaid validation friction showed up — 11 files, 34 lines each way of pure syntax cleanup.
- **Structure → content inversion.** Two `Move docs` followed by `Update docs` (+2,550 lines) suggests the bulk generation happened before settling on the final structure.

## Patterns & observations

- **`plans/` is growing fast.** Folders 14 (OAuth) and 15 (API keys) added this week, each with a SPEC.md and SPEC_REVISED.md pair. The review-and-revise pattern is producing thorough docs but doubling file count.
- **Solo authorship.** 21/21 commits. Fine for a solo workstream, but spec docs are a second-reviewer opportunity.
- **`apps/admin_api/admin_api.ts` touched twice** — this file is going to be ground zero for both the OAuth (plan 14) and the API keys dashboard (plan 15). Expect churn here next.
- **"Add diags" (`58455aa2`, +139 lines)** without a later "Remove diags" commit — check whether those stay or get cleaned up when the diagnosed issue is resolved.

## Action items (next week)

1. **Break mega-commits.** Commit per concern: npm audit fixes, auth code, test updates — separate commits make review, bisect, and PR review dramatically easier.
2. **Add a Mermaid lint step** before committing docs. Either a pre-commit hook or a quick `npx @mermaid-js/mermaid-cli --validate` pass. This would have pre-empted `8522ab96`.
3. **Decide on `SPEC.md` vs `SPEC_REVISED.md` policy.** Either (a) rename revised → SPEC and archive original, or (b) keep both and add a one-line header pointer. Current state leaves reviewers guessing which is canonical.
4. **Pick the next plan to implement.** OAuth (14) and API keys (15) are both fully specced — start Phase A of one of them.