Decision Log

Chronological record of decisions made. Never edit past entries—append only.

2025-12-21: Initial Stack Selection

Context: Needed to finalize stack decisions to unblock rally-hq development. Research phase complete with framework comparisons and AI-friendliness scoring.

Decisions:

Key factors:

1. SvelteKit over Next.js — Simpler mental model for AI. No hooks/effects/hydration complexity. Remote Functions eliminate API route boilerplate. Personal preference against React.

2. Supabase as single platform — Opinionated frameworks pick platforms. 100K MAU on $25/mo Pro plan vs Clerk's ~$500/mo. Official MCP server for AI tooling. Poor experience with Clerk on non-React frameworks.

3. Drizzle over Prisma — Zero dependencies, SQL-like syntax ("if you know SQL, you know Drizzle"), no codegen step.

4. Tailwind 4.0 — 5x faster builds, no config file, current as of Jan 2025.

5. Vitest 4.x — Stable browser mode, visual regression testing, works great with Svelte.

Research sources:

• Next.js 16.1 (Dec 2025) - https://nextjs.org/blog/next-16-1
• SvelteKit 2.49.0 (Dec 2025) - https://svelte.dev/blog/whats-new-in-svelte-december-2025
• Supabase Dec 2025 updates - https://github.com/orgs/supabase/discussions/41231
• Tailwind 4.0 (Jan 2025) - https://tailwindcss.com/blog/tailwindcss-v4
• Vitest 4.0 (Oct 2025) - https://vitest.dev/blog/vitest-4
• Drizzle 0.45.x - https://www.npmjs.com/package/drizzle-orm
• shadcn-svelte - https://github.com/huntabyte/shadcn-svelte

Hypotheses to validate:

1. SvelteKit's simpler model will produce more reliable AI-generated code
2. Remote Functions will eliminate API route boilerplate
3. Supabase as single platform will reduce integration complexity
4. Drizzle's SQL-like syntax will be more AI-friendly
5. Property-based tests from types will catch more bugs

Status: Approved. Proceeding to rally-hq initialization.

Template for Future Entries

## YYYY-MM-DD: Decision Title

**Context:** Why this decision was needed.

**Decision:** What was decided.

**Alternatives considered:**
- Option A — pros/cons
- Option B — pros/cons

**Rationale:** Why this choice over alternatives.

**Consequences:** What this enables or constrains.

**Status:** Proposed | Approved | Superseded by [link]

2025-12-21: Stack Pivot to Go + HTMX + Svelte Islands

Context: After completing the initial stack selection (SvelteKit), engineering audit revealed a contradiction: Go + HTMX was rated "A" for AI-friendliness while SvelteKit was rated "B+", yet SvelteKit was chosen. The original rationale ("no component ecosystem") was weak—AI doesn't need component ecosystems, it needs simple patterns.

Decision: Pivot to Go + HTMX for the core application (80%) with Svelte islands as escape hatches for complex interactivity (20%).

Alternatives reconsidered:

Rationale:

1. AI Code Generation Optimization — HTMX pattern is "request → handler → HTML → browser." No hooks, effects, hydration, or client state. This is the simplest possible pattern for AI to generate correctly.

2. Primitive-First — HTMX is ~14kb and uses browser-native HTTP, HTML, CSS, and SSE. No framework abstractions to confuse AI or bloat bundles.

3. Escape Hatch — Svelte islands provide opt-in complexity for the 20% of features that genuinely need rich client interactivity (drag-drop, rich text, complex visualizations).

4. Mobile/Network Friendly — Smaller bundles, no hydration, progressive enhancement means forms work without JS.

Consequences:

• Enables: Simpler AI patterns, smaller bundles, faster TTFB, progressive enhancement
• Constrains: Must learn Go + Templ, can't use existing shadcn-svelte components directly
• Islands boundary: Clear decision matrix for when to use HTMX vs Svelte island

Hypotheses updated:

Status: Approved. Supersedes "Initial Stack Selection" entry.

Index