# Methodology — verified-theory-publishing

The discipline that governs every article and book in this pipeline. External collaborators read this first; everything else is implementation.

> **Voice + tone are mandatory and enforceable via skill.** Three reference layers govern article voice:
> - [`foundation/05-vocabulary-and-voice.md`](foundation/05-vocabulary-and-voice.md) — per-piece rules (hand notation, vocab banlist, bet-frequency mini-tables, branding voice, density rules)
> - [`../specs/voice_guide_articles.md`](../specs/voice_guide_articles.md) — locked v1 voice pillars (evidence-first / author-voice preserved / plain-talk / one-idea-per-paragraph / register-vs-tier discipline)
> - [`../../knowledge/`](../../knowledge/) — canonical poker knowledge base (1,031 terms across 18 tiers). `/voice-check` reads `knowledge/canonical-poker-terms.yaml` to flag made-up tech-sounding terminology + suggest canonical replacements.
>
> Every draft that came through Claude should be run through `/humanizer` (strip generic AI-isms) and then `/voice-check` (apply QuintAce voice pillars + canonical-term check) **before coach review**. Catching voice issues at draft time is cheap; catching them after a coach has read is expensive. The `/ship-article` skill prompts for these gates as a pre-flight check. See [`../../.claude/skills/`](../../.claude/skills/) for the skill specs.

---

## How to use this index

**If you're new:** read `foundation/` end to end. Nine cross-cutting rules that apply to every piece of content you write. Then read the `tracks/` entry for the track you're on (`collaborations/` if you're a coach-bylined article author; `media-partners/` if you're pitching tech-journalism).

**If you're starting a new article or book:** read `workflow/01-ideation-and-scoping.md` first, then the matching `types/` file for the shape of content you're producing.

**If you're debugging a render / verifier gate failure:** go straight to `tools/` for the mechanics.

---

## Layer map

```
methodology/
├── foundation/   Cross-cutting rules — apply to ALL content
├── workflow/     Process — how work moves from idea to deploy
├── tools/        Mechanics — renderers, verifiers, payload specs
├── types/        Content-type-specific patterns
└── tracks/       Track-specific overrides (collaborations vs media-partners)
```

---

## Foundation (cross-cutting, applies to everything)

| # | File | Covers |
|---|---|---|
| 01 | [Authorship policy](foundation/01-authorship-policy.md) | Author shapes (coach / pro / theorist / growth partner); four relationship modes; 99%-final ship commitment; body-attribution floor |
| 02 | [Numeric fidelity](foundation/02-numeric-fidelity.md) | Every number traces to source or facts.yaml; no inline arithmetic; recompute pot odds independently; UNVERIFIED values cannot appear as specifics |
| 03 | [Citation policy](foundation/03-citation-policy.md) | Option B (no competitor solver citations externally); no process artifacts in body prose; no engineer names; G35 forbidden-token spec |
| 04 | [Rail discipline](foundation/04-rail-discipline.md) | V2 strategy_grid is canonical; no Quintace MCP for article/book work; RULE ZERO (no simplifications); raise_to encoding |
| 05 | [Vocabulary and voice](foundation/05-vocabulary-and-voice.md) | Hand notation (99 not 9-9); vocab banlist; bet-frequency mini-tables; literal-extreme-claim policy; branding voice; density rules |
| 06 | [Verification](foundation/06-verification.md) | Reach gate (≥40% target, ≥5% floor); card-identity (text > video); 2-source hand-level gate; iterated research (3 rounds); aggregate-helper semantics + custom-classifier spot-check |
| 07 | [Poker theory lens](foundation/07-poker-theory-lens.md) | Range advantage → c-bet frequency; nut advantage → sizing; EQR → realization gap; B:V → polarization signature; "Based on general poker theory:" marker |
| 08 | [Disclosure](foundation/08-disclosure.md) | Methodology block; Editor's Q + review-callout + Editor's-note conventions; visible changelog block + inline change markers mandatory every version bump; model-bias caveat |
| 09 | [Register and known issues](foundation/09-register-and-known-issues.md) | Unified register (8 todo types); cross-pipeline flow via gap_report.py; KI/MC inline qualifier tags; recurring todos |

## Workflow (process steps)

| # | File | Covers |
|---|---|---|
| 01 | [Ideation and scoping](workflow/01-ideation-and-scoping.md) | Track decision (collaborations vs media-partners); 4-step pre-scaffold ideation; scope-rename reactivity; §0 format primer for non-canon formats; articles.yaml schema; source_content_type sub-shapes |
| 02 | [Pipeline phases](workflow/02-pipeline-phases.md) | Five phases; HTML-first before author review; outline-preview deploys; suggest-first discipline; version snapshots + diff markers (CSS, anchor-link gotcha); rebuild-vs-patch trigger |
| 03 | [Reviewer workflow](workflow/03-reviewer-workflow.md) | Google Doc pattern; image-anchored comment trap; margin + inline-under-screenshot extraction protocol; verbatim-rewrite rule |
| 04 | [Deploy](workflow/04-deploy.md) | 6-step manual article deploy + mandatory hub regen; book staging+promote workflow; ship-readiness gate; halt-vs-warn policy; provenance artifacts |
| 05 | [Quality tiers](workflow/05-quality-tiers.md) | Tier 1 ship_check_article + Tier 2 review_article + Tier 2b 9-agent + Tier 3 v1-completeness-checklist; readability cleanup (4 sub-passes); final consolidated read-through; widget data sweep; sufficiency vs floor |

## Tools (mechanics)

| # | File | Covers |
|---|---|---|
| 01 | [Rendering](tools/01-rendering.md) | render_article.py for articles (deterministic markdown); build.py for books (LLM-in-content); {{include:}} directive + placeholder-stash; passthrough_render.py |
| 02 | [Chart.js rules](tools/02-chartjs-rules.md) | 9 rules to prevent invisible charts (non-empty labels, no 0-value segments, container minimums, Chart.js 4.x configs, explicit pixel heights, custom HTML annotations, prefer pure HTML for simple bars) |
| 03 | [Widgets](tools/03-widgets.md) | DC's PokerQuiz library (354 components, MANDATORY 2-6 per article); 3-cycle selection + Cycle 4 post-render review; self-sufficiency by kind (decision vs data-viz); predict-then-reveal integrity (4 rules); widget data sweep per revision; hand-replay template; spot card mandatory |
| 04 | [CSS conventions](tools/04-css-conventions.md) | Inline misuse of block-level change markers; bold + mobile-table conventions; hub card byline format; mobile responsiveness 0px overflow gate; metric discipline (absolute vs relative); percent-vs-absolute-combo; one-dimension-per-channel |
| 05 | [Semantic verification gates](tools/05-semantic-verification-gates.md) | Gate matrix (G7 enumeration, G8 anchors, G9 widget schema + treys, G10 numeric consistency, G21 LLM drift, G22 coverage-gap declaration, G23 MCP-rail trace, G35 body process artifacts); facts.yaml schema; .assumptions.md schema; G4 carve-outs; specialist boundary maintenance; book invariants E-K |
| 06 | [KB anchoring](tools/06-kb-anchoring.md) | [KB:entry_name] citation format; when to cite / when not to; {disclaim:} suffix for drift; bidirectional linkage via example_usage; proposed G10 KB-citation gate |
| 07 | [Strategy_grid payload](tools/07-strategy-grid-payload.md) | Canonical V2 strategy_grid endpoint + engine; full payload spec; ante modeling (per-player BB conversion); stack depth strategy; N-handed support; modeling forced bets; cache mechanics; raise_to encoding (canonical reference) |

## Types (content-type-specific)

| File | Covers |
|---|---|
| [article-hand-analysis](types/article-hand-analysis.md) | Per-hand catalog walkthroughs; off-equilibrium framing; pre-draft hand classification + range-composition + strongest/weakest claims; verdict-rubric + widget quiz-design + board-pedagogy discipline; 9-section article structure; 10-check pre-publish checklist; 11 anti-patterns; EV computation (3 concepts); GTO range surprise |
| [article-range-analysis](types/article-range-analysis.md) | Range-level theory tests + cross-format scans; 3 data layers (aggregate / per-class / per-combo); reach-weighted always; sizing-tree decomposition mandatory; range composition decomposition (audit gate); per-class spotlights; cross-validation discipline; robustness scope declaration; three-question audit; 6-section structure; 12-check checklist; 8 anti-patterns |
| [article-catalog](types/article-catalog.md) | N≥5-hand catalog folder structure; H-prefix numbering (hands.md stable, body 1-through-N); iterated 2-source verification (3 rounds); thesis-shaped slots discipline; hand-replay widget template; every-hand-gets-a-spot-card; catalog-table conventions |
| [article-plot-twist](types/article-plot-twist.md) | Pattern B (story-first) → mechanism reveal at §4 → rules; earned-reveal risks (premature labeling, coined-noun creep, §4 mechanism-name auction, story-mechanism gap); pattern declaration in outline; pattern-change = rebuild |
| [article-myth-busting](types/article-myth-busting.md) | Mechanism-first variation with verdict rubric (CONFIRMS / PARTIAL / CONTRADICTS); composition decomposition mandatory; widget quiz-design + board-pedagogy discipline; cross-validation required; aggregate-pattern synthesis (article spine); type-promise alignment audit |
| [article-in-session-qa](types/article-in-session-qa.md) | Pattern D Q&A shape with inquiry-director author mode; ghost-drafted coach-voiced reactions (NO empty placeholders); author-voice corpus discipline; question curation discipline; per-question structure; §closing aggregate (the thesis) |
| [article-exploit-files](types/article-exploit-files.md) | Reach-gate flex (<5% acceptable with inline caveat); GTO baseline + deviation overlay structure; source verification (coach-source single-source acceptable); methodology block specifics |
| [format-squid](types/format-squid.md) | Squid is non-canon — §0 primer required; three pedagogical traps (EQR overclaim, "safe players fold reflexively", "Kx in CO opening range"); implicit-ante formula (current heuristic + rigorous swing); hand-analysis discipline (actual marker state, val-monotonicity, stack-depth coverage); variant canonical naming |
| [format-mtt](types/format-mtt.md) | MTT in scope but blocked at structural API gap (MC-5 chip-EV-only, MC-6 graduated-ICM pending); KI/MC tags for affected articles; acceptable article scopes (early-stage + deep-stack pre-bubble); §4d chip-EV-only convention; Wave 1 MTT migration parked; §0 ICM primer when ICM is the subject |
| [format-plo](types/format-plo.md) | Scaffolding entry — PLO is KB-canon but no PLO article shipped yet in this pipeline; books-5/5a/5c use PLO; PLOPreflop.open constructor exists in strategy_grid_client; expands when first PLO article scaffolds |
| [book](types/book.md) | 3-tier source hierarchy; build.py orchestrator; provenance artifacts; version bump workflow; staging+promote; ship-readiness gate; halt-vs-warn; cross-pipeline handshake; project layout; chrome ownership; book registration (data-only); section file naming; hub page ownership; invariants E-K (coverage matrix, derived captions, readability, chart coverage, audience-param, marker blocks, verdicts chapter); action_sequence convention |
| [book-passthrough](types/book-passthrough.md) | Passthrough section spec (byte-copy + deterministic render via passthrough_render.py); provenance implications (no provenance_log.json); book-3 dotted H2 numbering exception; book-5 per-mechanism {#m<N>-<slug>} anchor convention; cross-pipeline implications (source's coverage_gaps propagate) |

## Tracks

| File | Covers |
|---|---|
| [collaborations](tracks/collaborations.md) | Default track — coach-bylined articles, partner-platform amplification, KB-anchored, widget-mandated; all foundation/ + workflow/ + tools/ + types/article-*.md apply; minimal track-specific patterns (byline, hub-card display, widgets mandatory, KB anchoring) |
| [media-partners](tracks/media-partners.md) | External tech-journalism pitches (MIT TR, Wired, Quanta, Atlantic, IEEE Spectrum); founder byline; per-article evidence canon replaces KB anchoring; custom CSS components; per-outlet headline matrix; right-of-reply discipline; ship-check subset (G3/G27/G28/G30/G32); review-agent subset (4 of 8 + outlet-fit); media_partners_html_sync.py tooling; pitch-state tracking |

---

## What's NOT in this methodology (intentional)

This methodology governs **content discipline** — what to write, how to verify, when to ship. It does NOT cover:

- **Solver math** — that's in `engineering-department/gameplay-ai/projects/llm-verifier-game-expansion/` (upstream)
- **Product code** — QuintAce app, CAI, AceExpert; different repos
- **Marketing copy** — comic series, social tiles, blog posts; different track
- **DA pipeline** — Decision Analysis prompts + agent code (CAI team)

If your question is "how do I run a solver query," start at `tools/07-strategy-grid-payload.md`. If your question is "where does this number come from," check the source citation. If neither answers it, ask in #editorial-questions.

---

## Origin

Consolidated 2026-05-24 from two parallel methodology trees (`articles/methodology/` 17 chapters + `docs/methodology/` 5 chapters + companion specs) into this layered structure. Migration plan: [`../docs/migration-plan-2026-05.md`](../docs/migration-plan-2026-05.md). Audit: [`../docs/methodology-audit-2026-05.md`](../docs/methodology-audit-2026-05.md).