Decision-Making Process

Trovella uses a structured decision-making process that starts with a concentrated decision sprint, then transitions to incremental ADRs as the system evolves.

Week 0 Decision Sprint

Before writing any code, a dedicated "Week 0" sprint resolves all foundational technical decisions. The sprint uses pre-written decision guides (78 guides covering frameworks, data, security, compute, and AI workflow) as structured input, with the founder as the sole decision-maker.

Format

Each decision follows a consistent structure:

• Status: Accepted, Accepted (modified), or Deferred
• Recommendation: What the guide proposed
• Decision: What was actually chosen and why it differs (if it does)
• Rationale: Cost, risk, and alignment reasoning

Decision Groups

The Week 0 sprint organized decisions into thematic groups:

Group	Coverage	Example Decisions
A	Language, framework, monorepo	Next.js 16, React 19, TypeScript strict, Turborepo + pnpm
B	Data layer	Cloud SQL PostgreSQL 18, Drizzle ORM, shared-schema RLS
C	Identity and security	Better Auth (self-hosted), CASL (RBAC+ABAC), Secret Manager
D	Compute and deployment	Compute Engine VM, Docker Compose + Caddy, Terraform
E	API, state, developer experience	tRPC v11, Zustand, TanStack Query, Vitest
F	Remaining foundation	Inngest, Pino, Sentry, Resend, Statsig
G	AI agent workflow	SPTI, worktrees, CLAUDE.md hierarchy, custom skills
H	Quality, documentation, planning	ESLint flat config, ADRs, Linear, burnout prevention

Decision Principles

Several principles emerged from the sprint:

Accept recommendations unless there is a specific reason not to. Most guide recommendations were accepted as-is. Modifications happened when the founder had direct experience contradicting a recommendation or when ecosystem constraints required adaptation.

Defer decisions that have no current consumer. Staging environments, mobile UI, public REST APIs, and advanced monitoring were all deferred with explicit trigger conditions for when to revisit.

Pin to specific versions only when ecosystem compatibility is the constraint. For tools with large plugin ecosystems (TypeScript, ESLint), the binding constraint is plugin compatibility, not the tool's own latest version.

Cost-conscious at every layer. Every decision includes cost at current scale and projected cost at growth milestones. Free tiers first; paid only when revenue justifies.

Architecture Decision Records (ADRs)

After Week 0, ongoing decisions are captured as ADRs in docs/architecture/decisions/. Each ADR follows a standard template:

• Status and date
• Decision -- what was decided, concisely
• Context -- why the decision was needed, what problem it solves
• Decision drivers -- the prioritized criteria
• Alternatives considered -- what was evaluated and why it was rejected
• Consequences -- positive, negative, and risks
• Validation -- how the decision is enforced (ESLint rules, CI checks, CLAUDE.md rules)

ADRs are written when architecture changes -- new packages, new external services, new auth flows, new CI jobs. They are updated in the same PR as the code change, not after the fact.

ADR Index by Domain

Each technical domain in this wiki has its own ADR pages. Rather than duplicating decisions here, link to the relevant domain:

Domain	Key ADRs
Data & Storage	Schema design, migrations, tenant scoping, caching, background jobs
Infrastructure	VM compute, environment strategy, deploy pipeline, secret management
Identity & Access	Better Auth, CASL authorization, shared-schema RLS
Delivery	CI/CD pipeline, quality gates, testing, architecture enforcement
Application	Framework, routing, state management, error handling
Search & Retrieval	Search engine, indexing, hybrid search
Research & Intelligence	AI integration, research engine, MCP tools

When to Write an ADR

Write an ADR when:

• Adding a new package to the monorepo
• Integrating a new external service or SDK
• Changing the auth flow or adding a new auth provider
• Modifying the CI/CD pipeline structure
• Changing the deployment model
• Modifying the database access pattern or adding a new data store
• Making a decision that a future developer (or agent) would need context to understand

Do not write an ADR for:

• Bug fixes or implementation details
• Library version upgrades (unless they require code changes)
• Configuration changes within existing patterns
• Decisions that are already documented in CLAUDE.md rules

Decision Enforcement

Decisions are only as durable as their enforcement. Trovella uses layered enforcement:

1. CLAUDE.md rules -- agent-facing instructions that shape every session's output
2. ESLint rules -- editor-time feedback (package boundaries via no-restricted-imports)
3. dependency-cruiser -- CI gate validating the package dependency graph
4. CI quality checks -- 10 checks that must pass before deployment
5. Manual review -- required for auth, RLS, payments, and data access control changes

The enforcement layer is documented in each ADR's "Validation" section, making it auditable which decisions are enforced and how.

Cross-Domain References

• Delivery -- Architecture Enforcement -- how package boundaries and layer hierarchy are machine-enforced
• Delivery -- Quality Gates -- the CI checks that validate decisions
• Retrospective Format -- how decisions are evaluated after implementation