The House Edge

Appearance

The House Edge — Production Kit ​

A Claude Code agent-driven workflow for writing a book-length explainer on on-chain trading market structure.

What this is ​

A repo skeleton and prompt kit. The work product is a book; the work itself is a structured, reviewable, iterative collaboration between Nick and a Claude Code agent running locally against this repo.

Repo structure ​

onchain-trading-book/
├── README.md                          (this file)
├── prompts/
│   ├── 00_AGENT_PROMPT.md            (the prompt Nick pastes into Claude Code)
│   ├── 01_BOOK_BIBLE.md              (voice, audience, banned moves)
│   └── 02_CHAPTER_SPEC_TEMPLATE.md   (structure every chapter follows)
├── book/
│   ├── OUTLINE.md                    (full TOC, production order)
│   ├── chapters/
│   │   └── NN_slug/
│   │       ├── SPEC.md               (Nick writes — chapter brief)
│   │       ├── RESEARCH.md           (agent Phase 1 — research note)
│   │       ├── OUTLINE.md            (agent Phase 2 — chapter outline)
│   │       ├── DRAFT.md              (agent Phase 3 — full draft)
│   │       └── REVIEW_NOTES.md       (agent Phase 3 — self-review)
│   ├── glossary/GLOSSARY.md
│   ├── assets/                       (diagrams, by chapter)
│   ├── sources/                      (deduplicated bibliography, by chapter)
│   ├── MANUSCRIPT.md                 (concatenated final, generated last)
│   └── EPILOGUE.md                   (Nick writes by hand)

Local reading site ​

This repo also includes a VitePress reading view for the book.

bash
npm install
npm run docs:dev
npm run docs:build
npm run docs:preview

The generated site lives in .vitepress/dist/ and is intentionally ignored by Git.

For reviewer annotations, open a chapter with dokieli review mode enabled:

txt
/book/chapters/01_trade/DRAFT?review=dokieli

See review/dokieli.md for the current dokieli/Solid storage notes.

How to start a session ​

  1. Open Claude Code in this directory
  2. Paste prompts/00_AGENT_PROMPT.md as the system instruction (or claude --append-system-prompt)
  3. Tell the agent which chapter to work on and which phase
    • Example: "Start Phase 1 (research note) for Chapter 4. Spec is at book/chapters/04_searcher/SPEC.md."
  4. Review the output. Approve or send notes.
  5. Move to the next phase or the next chapter.

The phase discipline ​

The single most important rule: do not let the agent skip phases. Phase 1 (research note) before Phase 2 (outline) before Phase 3 (draft). Each phase has a separate review by Nick.

This sounds slow. It is significantly faster than reviewing a 5,000-word draft full of plausible-sounding but wrong claims, finding the problems, and rewriting from scratch. The phase split front-loads the corrections to where they're cheap.

How to write a chapter SPEC (Nick's job) ​

Use book/chapters/04_searcher/SPEC.md as the template. The fields that matter most:

  • Worked example candidates with a preference noted
  • Open questions for the agent's Phase 1 research — what specifically you don't know and want the agent to find
  • Tone notes specific to this chapter — any traps unique to this material
  • Out of scope — explicit fences against scope creep

A SPEC is 1–2 pages. Longer SPECs mean the chapter isn't sharp enough yet.

Review heuristics ​

When reviewing Phase 1 (research note): skim for plausibility, check 2–3 numbers against your own knowledge, flag anything that contradicts what you saw in your day job. The agent will find good sources for things you don't know. The agent will also occasionally find plausible-sounding wrong things. Phase 1 is where you catch them.

When reviewing Phase 2 (outline): does the chapter answer the questions in the SPEC? Does it have the worked example threaded through? Is the chain comparison box where it should be?

When reviewing Phase 3 (draft): the Goldman MD test. Read it aloud. If you stop, the agent stops too.

Sequencing ​

Per the OUTLINE production order:

  1. Chapter 4 (Searcher) — voice calibration
  2. Chapter 2 (Liquidity)
  3. Chapters 1, 3 (Setup)
  4. Chapters 5–7 (Actors)
  5. Chapters 8–10 (Chains)
  6. Chapters 11–12 (Verdict and forward)
  7. Prologue
  8. Epilogue (Nick writes)
  9. Glossary cleanup, bibliography, MANUSCRIPT.md assembly

Distribution downstream ​

The MANUSCRIPT.md file is the canonical artifact. From there:

  • A pandoc pipeline produces PDF and EPUB
  • An HTML render becomes a FigApp-published artifact
  • Selected chapters become standalone marketing pieces
  • The glossary becomes a standalone reference asset

This is the publishing-layer story you've been building — book lives in markdown, distribution surfaces are derivatives.