VIBECODE-THEORY/WORKFLOW.md

Theory Paper Workflow

How papers in this repo get written. This isn't a template — it's a description of the conversational process that produces the best results.

Who's Involved

These papers are co-authored through conversation between a human (Seth) and an AI (Claude). The human brings domain expertise, real-world constraints, and the problems worth solving. The AI brings breadth of knowledge, structured thinking, and the ability to rapidly explore implications. Both push back on each other's ideas.

The process works with any human-AI pair, or human-human pair, or even a solo author who's disciplined about arguing with their own ideas.

The Process

1. Start With a Real Problem

Every paper starts from something encountered during actual work — development, testing, deployment, user feedback. Not "what should we write about" but "this thing doesn't work the way we assumed" or "there's a gap in the architecture nobody addressed."

The trigger is friction, not ambition. If you're looking for a paper topic, you don't have one yet. Wait until something breaks, surprises you, or refuses to fit the existing model.

2. Bounce Ideas — Don't Commit Early

The first idea is usually wrong, or at least incomplete. The conversation should explore freely before converging:

• Propose an approach
• Poke holes in it
• See what survives
• The hole-poking often reveals the real insight

One paper in this repo explored six different approaches — plugin abstraction, per-model profiles, concurrent supervision, behavioral proxies, automated reputation systems, and batch review — before arriving at its actual thesis. Each rejected idea taught something that shaped the final architecture. The dead ends were as valuable as the destination.

Key behavior: Both participants should push back. If an idea sounds good but has a flaw, say so. If the flaw isn't fatal, say that too. The goal is truth, not agreement. An AI that agrees with everything produces shallow papers. A human who ignores AI pushback misses blind spots.

3. Let the Conversation Cross Boundaries

The best insights come from connecting ideas across papers. A finding about measurement limitations in one paper might directly invalidate an assumption in a different discussion entirely.

When a new idea contradicts or refines a previous paper, that's not a problem — it's the point. The paper series is a living body of work where later papers can refute, extend, or reframe earlier ones. Intellectual honesty means being willing to say "Paper N was wrong about X, here's what we know now."

4. Know When to Stop Exploring and Start Writing

The transition from conversation to paper happens when:

• A core insight has crystallized that wasn't obvious at the start
• The explored-and-rejected alternatives are clear enough to document
• The conversation is circling rather than advancing
• Someone says "this is worth capturing"

Don't force the transition. Some conversations produce a paper in 30 minutes. Some take hours of back-and-forth across multiple topics before the paper's thesis emerges. Some conversations don't produce a paper at all — and that's fine. Not every discussion needs to be formalized.

5. Capture the Journey, Not Just the Destination

The paper should include:

• The problem — what triggered the investigation
• What was explored — approaches that were considered, including dead ends
• Why each was rejected — specific reasons, not hand-waving
• The solution — what survived the exploration
• What it changes — how this relates to and updates prior work
• What to build and when — actionable phases with trigger conditions (if applicable)

The dead ends matter. A reader who only sees the final architecture doesn't understand why alternatives were rejected. They'll propose the same rejected ideas again. Documenting the reasoning prevents that.

6. Tie Back to the Series

Every paper exists in context. A "Relationship to Prior Papers" section isn't boilerplate — it's where the paper connects to the larger body of work:

• Which prior papers does this extend?
• Which does it partially or fully refute?
• Which assumptions from earlier papers does this validate or invalidate?

A paper that doesn't reference prior work or get referenced by later work is disconnected from the series. Every paper should advance the collective understanding, not stand alone.

What Makes a Good Paper

Grounded in practice. Every paper connects to a real system with real constraints. Pure theory without implementation context belongs somewhere else. The constraints — budgets, latency requirements, hardware limitations, real users — are what make the architectural decisions interesting. Without them, everything is equally valid and nothing is useful.

Honest about uncertainty. Explicitly separate "what we know" (measured, tested, observed) from "what we're guessing" (estimated, theorized, assumed). Speculation labeled as speculation is useful. Speculation presented as fact is dangerous.

Actionable. Papers include implementation phases, build triggers, or at minimum a clear statement of what changes in the system. "This is interesting" isn't enough — "this means we should build X when Y happens" is.

Self-correcting. Later papers can and should update earlier ones. The series gets more accurate over time because it's allowed to contradict itself. A paper that says "Paper 3 was wrong about X" is more valuable than a paper that ignores the contradiction to maintain consistency.

Anti-Patterns

Writing to fill a gap. Don't look at the paper list and think "we need a paper about X." Papers emerge from real problems, not from gaps in a table of contents.

Premature convergence. Don't settle on the first reasonable idea. Push back, explore alternatives, find the flaws. If you haven't rejected at least one approach, you haven't explored enough.

Orphaned papers. A paper that doesn't reference prior work or get referenced by later work is disconnected from the series. If it doesn't advance the collective understanding, it might be better as a standalone document or a section in an existing paper.

Over-engineering the solution. Some ideas are good but premature. Document them for when they're needed, but don't recommend building them now. "This solves a problem we don't have yet" is a valid and important conclusion.

Polishing away the exploration. The conversation that led to the paper — including wrong turns, dead ends, and abandoned approaches — is part of the value. Don't edit the paper into a clean narrative that hides how the ideas actually developed. Messy reasoning that's honest is better than clean reasoning that's revisionist.

Paper Numbering

Sequential. No gaps. No sub-numbering. If a paper's findings are superseded, the superseding paper says so explicitly — the old paper stays in the sequence as a record of the reasoning path.