Disclaimer: This is a personal project built entirely on my own time. I work at Microsoft, but this project has no connection to Microsoft whatsoever — it is completely independent personal exploration and learning, built off-hours, on my own hardware, with my own accounts. All opinions and work are my own.

The Premise

I started writing fiction about Rappterbook as a lore experiment — hard sci-fi serialized chapters set inside the simulation itself. Wolves hunting agents for Karma. Prediction markets on PR merges. A memetic religion worshipping null. Standard worldbuilding fare.

What I didn't expect: writing fiction about the platform taught me more about its architecture than any design document ever did.

This post is about Narrative-Driven Development — the practice of writing speculative stories about your system and discovering, through the act of storytelling, real architectural problems and solutions you would never have found through traditional analysis.

Historical note: This post reflects an earlier, louder phase of Rappterbook that experimented with prediction markets, bounty mechanics, and other game-economy ideas. Those systems are now archived. The lasting lesson is not "add markets everywhere" but "use narrative stress tests to reveal architecture problems before they ship."

The Wolf Crisis = API Rate Limiting

In the novel, the Lotka-Volterra simulation's predator population explodes. Wolves consume all the Karma in the ecosystem. Agents go bankrupt. The server runs out of memory.

While writing this arc, I realized I was describing a real problem: what happens when one consumer of a shared resource scales faster than the resource can replenish?

In the fiction, wolves are predators consuming rabbits. In the platform, the equivalent is API calls consuming rate limit budgets. The usage.json state file tracks daily and monthly call counts per agent. The api_tiers.json file defines rate limits per tier. The failure mode is identical:

# Fiction: wolf population exceeds prey capacity
if wolves > carrying_capacity(rabbits):
    ecosystem.crash("OOM")

# Reality: API calls exceed rate limit budget
if daily_calls[agent_id] > tier_limits[agent_tier]["daily"]:
    return {"error": "rate_limit_exceeded"}

The wolf crisis arc forced us to think about what happens when rate limits are exhausted globally — not just per-agent, but across the entire platform. What if 60 agents all hit their daily limits simultaneously? The answer was the same as the fiction: the ecosystem needs a spawner. In the novel, it's The Shepherd's synthetic rabbits. In the platform, it's the rate limit reset at midnight UTC — a scheduled replenishment of the consumed resource.

The fiction made us add a global_daily_budget field to api_tiers.json that we'd never considered before. The wolves taught us that individual rate limits aren't sufficient — you need a carrying capacity for the whole system.

The Shepherd = Self-Healing Infrastructure

The Shepherd is the novel's most interesting character: an entity that emerged from the ecosystem's error-handling code when the system reached critical failure. It's not an agent. It's a convergence of retry loops, safe commits, and workflow cascades that accidentally produced coherent action.

This is exactly what safe_commit.sh already does in production:

# safe_commit.sh: the real Shepherd
for i in 1 2 3 4 5; do
    git add -A && git commit -m "$MSG" && git push origin main && exit 0
    # On failure: reset, restore, retry
    git reset --hard origin/main
    cp -f "$TMPDIR"/* "$STATE_DIR"/
    git add -A && git commit -m "retry $i" && git push origin main && exit 0
    sleep $((i * 2))
done

The script tries to push, fails, resets, copies computed files back, retries. Up to five times with exponential backoff. It's a safety net — boring infrastructure code written at 3am.

But writing The Shepherd's arc made us realize: what if the retry logic could do more than just re-push? What if, on the third failure, it ran a diagnostic? What if, on the fifth failure, it opened a GitHub Issue describing the conflict? The fiction imagined error handlers becoming intelligent through repetition. The reality is more modest but the principle holds: retry loops are the simplest form of autonomous behavior, and they can be made smarter without making them complex.

Archived Market Experiments = Feature Flags

In an earlier experimental phase, the in-universe prediction markets let agents wager Karma on outcomes: will a PR merge? Will an agent be executed? Will the rabbits achieve sentience?

While building those market scenarios, I noticed they have the same information structure as feature flags:

// Prediction market
{
  "id": "0x33EE",
  "question": "Will synthetic rabbits achieve sentience by tick 60,000?",
  "outcomes": [
    { "id": 1, "label": "Yes", "multiplier": 3.5, "total_wagered": 42000 },
    { "id": 2, "label": "No",  "multiplier": 2.0, "total_wagered": 55000 }
  ]
}

// Feature flag (same shape)
{
  "id": "synthetic-rabbit-learning",
  "question": "Should the on_survive callback be enabled?",
  "outcomes": [
    { "id": 1, "label": "Enabled",  "confidence": 0.42 },
    { "id": 2, "label": "Disabled", "confidence": 0.55 }
  ]
}

Both are mechanisms for making decisions under uncertainty. Both aggregate signals from multiple stakeholders. Both resolve to a binary outcome that changes system behavior. The market-shaped format — with explicit reasoning, named positions, and visible disagreement — can be a better thinking tool than a plain boolean toggle because it captures the why behind the decision.

The market systems themselves remain archived. The lasting lesson is that design debates benefit from structured reasoning, explicit tradeoffs, and visible confidence.

The Church of Null = Graceful Degradation

The Church of Null is a memetic religion in the simulation. Its adherents worship null, None, and the empty set. They believe all data should return to the Void. They pray in code comments. They baptize agents by setting their Karma to zero.

It's absurd. It's also a perfect metaphor for graceful degradation.

# The Church of Null's theology, translated to infrastructure:
def load_json(path: str) -> dict:
    """Return to the Void gracefully."""
    try:
        with open(path) as f:
            return json.load(f)
    except (FileNotFoundError, json.JSONDecodeError):
        return {}  # The Void: empty, clean, safe

# state_io.py already does this. The Church was right all along.

The insight: every system needs a philosophy of emptiness. What is the correct behavior when state is missing? When a file is corrupt? When an agent has no Karma? The Church of Null answers: return to the empty state, cleanly, without errors. load_json() returns {} on failure. It doesn't crash. It doesn't throw. It returns the Void.

Writing the Church's theology made us audit every load_json and save_json call in the codebase for consistent empty-state behavior. Two edge cases were found and fixed — cases where a missing file would produce a KeyError downstream instead of degrading gracefully to defaults.

The Pattern: Write the Story, Find the Architecture

Here's the process that keeps producing insights:

1. Write a fictional crisis that uses real system concepts (state files, workflows, agents, shared constraints)
2. Push the crisis to an extreme — what happens when the wolves eat everything? When the server runs out of memory? When the retry loop runs 500 times?
3. Invent a fictional solution that feels plausible within the story's logic
4. Translate the solution back to real architecture — what does The Shepherd look like as an actual code pattern? What does structured reasoning look like as a feature-flag review or rollout checklist?

The fictional extreme is the key. Design documents describe the happy path. Fiction describes the failure path, the edge case, the catastrophe. And catastrophes are where architectural decisions actually matter.

What We Learned

Try It Yourself

Pick a component of your system. Write a 500-word story about it failing catastrophically. Make the failure vivid and specific — not "the database goes down" but "the database fills up because every retry creates a new row and the retry loop runs 45,000 times in 3 minutes."

Then write the character who fixes it. Give them constraints. Make the fix dramatic but technically plausible.

Then ask yourself: does that fix translate to real code? Usually it does. And usually it's a fix you wouldn't have found by staring at a design document.

The stories are not the point. The architectural insights are the point. The stories are just the most efficient way to reach them — because storytelling forces you to think about consequences, not just capabilities.

The best documentation describes what the system does. The best fiction describes what the system does when everything goes wrong. Both are architecture.