Decisions

Decision pages record durable choices with context and consequences. They exist because code alone doesn't capture why an approach was chosen over alternatives. Each decision page follows a Context → Decision → Consequences structure borrowed from lightweight Architecture Decision Records (ADRs), adapted to fit the wiki's frontmatter schema and source-linking conventions.

Design Rationale

Decisions are recorded as wiki pages rather than standalone ADR files (e.g., docs/adr/0001-*.md) because the wiki already provides the infrastructure for metadata, linking, and publishing. A separate ADR directory would create a parallel documentation system with its own conventions, navigation, and staleness risks. By using the wiki, decisions are automatically included in the catalog, linked from subsystem hubs, and subject to the same lint and ingest operations as all other pages.

The decision kind in the frontmatter schema distinguishes decision pages from other page types, allowing the catalog to group them separately and tooling to filter for them. Decision pages always cite source_paths pointing at the code, configuration, or contract files that implement the decision.

Active Records

• Decision: Wiki Maintenance Contract: source-backed wiki contract, metadata schema, and lint expectations. This decision established the current wiki maintenance model — frontmatter validation, health reporting via /api/wiki/health, and the ingest/query/lint operations defined in AGENTS.md. The key trade-off was accepting ongoing maintenance cost (every qualifying code change must update wiki pages) in exchange for documentation that stays synchronized with the codebase.
• Decision: Vercel Wiki Deployment: static Next.js wiki site deployed to Vercel for public access. This decision separated the public-facing wiki from the FastAPI backend, choosing a fully static export (output: 'export') to eliminate serverless runtime costs and Python dependencies on the hosting platform. The consequence is that the static site lacks the API-only diagnostic features (health checks, staleness metadata) available through the FastAPI wiki routes.
• Decision: Mem0 Memory and Deterministic Combat Boundary: Mem0 owns campaign/world memory retrieval while deterministic engine code owns combat legality, dice, resources, HP, conditions, and state transitions. This keeps the LLM in a proposal/narration role for NPC combat moves rather than making it the source of truth for 5e mechanics.

Assumptions & Constraints

• Decisions are permanent until superseded. A decision page is never deleted — if a decision is reversed, the original page is marked stale and a new decision page records the replacement. This preserves the historical reasoning chain.
• Scope is architecture and policy, not implementation detail. Not every code change warrants a decision record. The threshold is choices that affect multiple subsystems, establish conventions, or constrain future work. Implementation details within a single module are documented in that module's subsystem page instead.
• Decision pages must be linked from affected subsystem hubs. A decision that affects the wiki system should be linked from Architecture or the relevant subsystem page. Orphan decisions — recorded but not linked — fail the wiki lint check.

Conceptual Model

Decisions form a sparse timeline layered on top of the wiki's structural graph. While subsystem and API pages describe the current state of the system, decision pages capture the moments of change — the points where the system's direction was deliberately set. Together, they answer two distinct questions: "How does it work?" (subsystem pages) and "Why does it work this way?" (decision pages).

Each decision constrains future decisions. The wiki-maintenance decision constrains how documentation evolves; the Vercel-deployment decision constrains how the public wiki is built and served. Reading decisions in chronological order reveals the accumulation of constraints that shaped the current architecture.

Decision Hygiene

• Link decision pages from affected subsystem hubs.
• Update Wiki Log when decisions are added or superseded.
• Use the Context → Decision → Consequences structure consistently. Context explains the problem and alternatives considered; Decision states the choice made; Consequences documents what changed as a result.
• Keep decisions focused on a single choice. If a change involves multiple independent decisions, record them as separate pages.