Knowledge Base Drift Prevention

Problem

As game code evolves through rapid iteration, documentation (the Fun Stack, design docs, and architectural decisions) quickly becomes stale. This drift leads to a fragmented understanding between agents, designers, and engineers, resulting in regressions and conflicting implementations.

Pattern

Establish the Knowledge Base (KB) as the Single Source of Truth (SSOT), but strictly enforce a Verify-Before-Update policy and embed explicit synchronization markers (Quartz sync comments) directly within the codebase. Documentation updates must be driven by verified code changes, not hypothetical designs.

When to Use

Implementing new features or core mechanics.
Refactoring core systems, state management, or API contracts.
Adjusting game balance, rules, character stats, or configurations.
Resolving deep technical debt or fixing architectural bugs.

The 6-Step Genius Sync Protocol

When a structural, architectural, or rule-based change is required, follow this exact sequence to ensure the Knowledge Base remains synchronized with the reality of the codebase:

1. Orient

Action: Review the current state of both the Knowledge Base (Fun Stack, architecture docs) and the Code.
Goal: Identify discrepancies, outdated assumptions, or areas that explicitly require modification to support the new feature or fix.

2. Perspective Audit

Action: Analyze the proposed change or existing gap from a specific perspective (e.g., Performance, Fun, Usability, State Consistency, Network Bandwidth).
Goal: Ensure the change aligns with the core pillars of the game and doesn’t introduce regressions in other areas.

3. Hypothesis

Action: Formulate a concrete, actionable change.
Goal: Evaluate the hypothesis using an Impact vs. Confidence vs. Effort matrix. Do not proceed if the effort vastly outweighs the confidence and impact.

4. Implement

Action: Execute the change directly in the codebase.
Goal: Build the feature, fix the bug, or refactor the system. Do not write extensive documentation yet.

5. Verify

Action: Test the implemented change via runtime execution, smoke tests, automated E2E tests, or unit tests.
Goal: The code dictates reality. Ensure it works exactly as intended under real conditions before treating it as truth.

6. Update (Sync)

Action: Sync the Knowledge Base to strictly match the verified code.
Goal: Update the Fun Stack scorecard, core loop definitions, architectural markdown docs, and state schemas. Add Quartz sync comments to the code linking to the updated docs.

Quartz Sync Comments

To bridge the gap between code and documentation, embed Quartz sync comments directly in the source code near major architectural decisions, state schemas, or configuration objects. These serve as breadcrumbs for both human developers and AI agents to locate and update the corresponding documentation when the code changes.

TypeScript/JavaScript Example (In Code):

// SYNC: Docs -> dev/docs/content/standards/genies-unified-game/patterns/knowledge-base-drift.md
// Ensure the bot profile configuration strictly matches the Fun Stack documentation.
export const BOT_PROFILE_CONFIG = {
  difficulty: "hard",
  reactionTimeMs: 150,
  aggressionMultiplier: 1.2
};

Markdown/Quartz Example (At the bottom of the KB doc):

<!-- QUARTZ: 2026-07-22 agent - updated bot profile configuration sync, adjusted aggression multiplier based on playtest feedback -->

Anti-Patterns

Docs-First Fantasies: Writing extensive, highly detailed documentation for features, systems, or architectures that haven’t been prototyped, proven, or implemented in code. Reality often breaks theoretical designs.
Silent Changes: Modifying core game rules, configurations, or unified state schemas in the code without updating the Fun Stack or relevant KB documents, leading to immediate drift.
Orphaned Docs: Moving, refactoring, or deleting code without subsequently cleaning up, archiving, or deleting the associated documentation.
Ignoring Sync Markers: Changing code that is explicitly annotated with a // SYNC: Docs comment but failing to follow the link and update the targeted markdown file.
Vague Commit Links: Relying solely on git commit messages to document architectural shifts instead of updating the centralized Knowledge Base.

Acceptance Checks

Verified Reality: Code changes affecting game rules, state schemas, or architecture are accurately and comprehensively reflected in the Knowledge Base.
Protocol Adherence: The 6-Step Genius Sync Protocol was explicitly followed during the implementation and documentation phase.
Sync Markers Present: Quartz sync comments (// SYNC: Docs -> path/to/doc.md) are actively present in the codebase above critical paths, configurations, and state interfaces.
No Speculation: Updates to the Knowledge Base are exclusively based on verified, tested code, not speculative designs or unproven prototypes.
Quartz Footer: The modified markdown document contains an updated  footer reflecting the sync.

Reference

Sister Brawl: The reference implementation rigorously utilizes Quartz sync comments to track changes to character stats, solo mode behaviors, hit-stop durations, and the Fun Stack scorecard. This ensures that agents and engineers always have the correct, verified context when making subsequent adjustments.