# Writer Guide Rules every writer follows, regardless of track. For the step-by-step "what do I actually type" sequence, see [`WORKFLOW.md`](WORKFLOW.md). **Two ways to use this guide**: - **Copy-paste prompts** (below) — works in any Claude surface (claude.ai chat, Claude Code, Cursor) - **Claude Code skills** — `/draft-article` (scaffold a new ad-hoc piece), `/classify-article` (5-facet taxonomy walkthrough), `/check-gaps` (live coverage matrix), `/ship-article` (render + ship-check + PR). Plus the methodology + meta skills (`/methodology-feedback`, `/update-methodology`, `/skill-feedback`, `/update-skill`). Full list: [`.claude/skills/README.md`](.claude/skills/README.md). ## Pick your track | Track | Owner | |---|---| | [`da-pipeline/`](da-pipeline/) — V1 Core DA, V2 Five-Section, V3 Pro Hand Collection, V4 Range Grid, V5 Quiz, V6 Hand of the Week, V7 Big Blunders | **Harold + Chris** | | [`ad-hoc/`](ad-hoc/) — mechanism walkthrough, plot twist, legends graded, myth-busting, in-session, exploit files, comic, media partners | **Thanh** | ## Quick-start Claude prompts (copy-paste ready) These get you from "I have an article folder" → "I have a v1 draft I can edit." Edit the `` and paste into your Claude chat (claude.ai), Claude Code CLI, or Cursor / VS Code with Claude. ### Prompt A1 — Draft a new DA-pipeline article Use this after copying `da-pipeline/_template/` to `da-pipeline/hand-XXXX-YY/` and pulling the tool data. ``` I'm writing a DA-pipeline article for hand-XXXX-YY in the QuintAce articles repo. Read these files: - da-pipeline/hand-XXXX-YY/tool_trace.json (the source data) - da-pipeline/_template/.md (the format spec — pick the file matching your format) - WRITER_GUIDE.md (the rules) Draft `da-pipeline/hand-XXXX-YY/.md` following the format spec EXACTLY. Rules (non-negotiable): 1. Every solver / equity / range / frequency claim must trace to a value in tool_trace.json. If you can't trace it, don't make the claim — flag it instead. 2. No specific EV numbers in prose (qualitative only — "clearly favorable", "thin edge"). 3. No hedge words ("clearly", "obviously", "of course", "naturally"). 4. Round numbers to 1 decimal place. Use `~` for approximate. 5. Use ♥️ ♦️ ♣️ ♠️ suit symbols, never letters. When you finish drafting, output a "Claims trace" section after the draft listing every claim with the JSON path it traced to. ``` Replace `` with `core_da`, `five_section`, `pro_hand_collection`, `range_grid`, `quiz`, `hand_of_the_week`, or `big_blunders` depending on which format you're producing. ### Prompt A2 — Draft a new ad-hoc article (classify + scaffold, no prose yet) Use this after copying `ad-hoc/_template/` to `ad-hoc/articles//`. ``` I'm writing an ad-hoc article at ad-hoc/articles//. My brief: - Title: - Hook: - Audience: - Coach (if any): - Partner (if any): Read these files first: 1. ad-hoc/methodology/_taxonomy.md ← THE 5-FACET CLASSIFICATION MODEL 2. ad-hoc/methodology/INDEX.md 3. ad-hoc/methodology/foundation/*.md (cross-cutting rules) 4. ad-hoc/_template/v1.md (frontmatter scaffold — note the taxonomy block at top) 5. WRITER_GUIDE.md (rules below) Then do this, in order, and STOP after each step for me to confirm: STEP 1 — Classify the article. Walk the decision tree in ad-hoc/methodology/_taxonomy.md and propose: - taxonomy.anchor: A=ambassador | B=partner | C=quintace voice - taxonomy.trigger: 1=famous | 2=topical | 3=mechanism | 4=series - taxonomy.usp_primary: alpha off-tree | beta multiway | gamma non-fmt | delta non-game | epsilon exploit | zeta methodology - taxonomy.usp_secondary: list of additional USPs, often [] - structure: hand-analysis | range-analysis | catalog - format: prose | comic Then write the taxonomy.demonstrates field — one or two sentences in plain English on what this article uniquely proves about QuintAce. If you can't write it cleanly, your usp_primary is probably wrong; reconsider. Also tell me which methodology/types/article-.md file applies and quote the section pattern from it. Output as a yaml block. Show me the coverage state: which USP cells are under-served right now (see _taxonomy.md "Coverage matrix") and whether my classification fills a gap. WAIT for me to confirm the classification before continuing. STEP 2 — Fill v1.md frontmatter. After I confirm the taxonomy, populate v1.md with the full frontmatter block (taxonomy, structure, format, title, byline, audience, draft_state: outline, drafted_on, coverage_gaps: [], etc.). STEP 3 — Write outline.md. Based on the structure I chose: - hook (one paragraph) - thesis (one sentence) - evidence-to-gather (bullet list — each evidence point names a pull_.py script + what it should query) - section structure (matching methodology/types/article-.md) - open questions - planned coverage gaps STEP 4 — Solver-pull plan. List the pull_.py scripts I'll need to write. For each: what game state (format / stakes / blinds / position / action history / hero hand / board), what data the script extracts, and what JSON filename it writes to. DO NOT draft body prose yet — I want to see classification + outline + pull plan, confirm the angle, then write prose in a separate session. ``` ### Prompt A3 — Iterate on an existing draft After outline + data pulls, ask Claude to fill in prose. ``` Continue drafting ad-hoc/articles//v1.md. Read: - ad-hoc/articles//outline.md (the agreed structure) - ad-hoc/articles//*.json (all solver outputs in the folder) - ad-hoc/methodology/foundation/*.md (rules) - ad-hoc/methodology/types/.md (section pattern) For section , draft the prose. Every solver/equity/range/frequency claim must cite a value present in one of the *.json files. After each numeric claim, add an HTML comment with the file + path, like: Rules: - No specific EV numbers (qualitative only) - No hedge words - Round to 1 decimal - Suit symbols ♥️ ♦️ ♣️ ♠️ - Strip the source-citation HTML comments before final ship (they're a drafting aid) ``` ### Prompt A4 — Pull solver data Ask Claude to write a pull script. ``` Write a pull script at ad-hoc/articles//pull_.py that calls the V2 strategy_grid endpoint to fetch . Game state: - Format: - Stakes / blinds: - Position(s): - Action history: 
  - Hero hand / board: 

Reference: ad-hoc/methodology/foundation/04-rail-discipline.md for the rail conventions and ad-hoc/articles/uri-squid-invisible-ante/pull_uri_squid_invisible_ante.py as a working example.

Output JSON to pull_.out.json in the same folder. Include the full request payload and response so we can re-verify later.
```

## The rules

- **Evidence-first.** Every solver/equity/range/frequency claim must be backed by a tool output. If you can't point to data, don't make the claim.
- **No LLM-only additions.** If Claude drafted prose with an untraceable claim, cut it. The reviewer catches what you missed; your job is to not push known-unverified claims.
- **Hygiene check before PR (DA-pipeline only).** If `hygiene_check.md` FAILS, pause and ping Chris before opening the PR.
- **Suit symbols** `♥️ ♦️ ♣️ ♠️` — consistent, never letters.
- **Number formatting:** round to 1 decimal (`25.0%`, not `24.7697%`). `~25%` for approximate.
- **No specific EV numbers in prose.** Qualitative only ("clearly favorable equity", "thin EV").
- **No hedge words.** Strip `clearly` / `obviously` / `of course` / `naturally`. They overclaim certainty.
- **Widgets are mandatory.** Every ad-hoc article ships 2-6 interactive widgets. Two paths:
  - **Ad-hoc vanilla HTML** (ready today) — 130 working widgets in `articles//embed/`. Browse the visual gallery at [`widgets/index.html`](widgets/index.html) (live at https://quintace-external.github.io/articles/widgets/) or the text catalog at [`widgets/ad-hoc-catalog.md`](widgets/ad-hoc-catalog.md). Copy + adapt.
  - **PoCo iframe** — 354 React widgets in DC's PokerQuiz library. Pick from [`widgets/poco-catalog.md`](widgets/poco-catalog.md), request YAML clone from PoCo team (DC owns the deploy pipeline).
  - **Skill**: run `/add-widget` and it walks you through both paths. Decision matrix: [`widgets/README.md`](widgets/README.md). Budget ~45-60 min on widget selection per article.
- **Sanitize before push.** Read [`SHARING_POLICY.md`](SHARING_POLICY.md).

## Methodology updates

- **DA pipeline writers**: you cannot edit methodology directly. File suggestions via the reviewer feedback template's "Suggested Prompt / Format Change" section. CAI team triages and decides.
- **Ad-hoc writers**: you can edit `ad-hoc/methodology/*.md` directly, but every change must include a summary in `ad-hoc/methodology/CHANGES.md`. See [`WORKFLOW.md#d-update-methodology`](WORKFLOW.md#d-update-methodology).

## Writer checklist — copy into your article folder

Save as `/_writer.md`. Reviewers will look for it during triage.

```markdown
# Writer Checklist — 

**Writer**: 
**Track**: 
**Format(s)**: 
**Date drafted**: 

## Pre-write
- [ ] I know the audience (player / coach / public / partner)
- [ ] I have the source data (hand ID for DA-pipeline; outline.md + pulled JSON for ad-hoc)
- [ ] I've read the format guide / methodology type doc for the variant I'm writing

## During writing
- [ ] Every solver/equity/range/frequency claim traces to a tool output I can name
- [ ] No claim paraphrased from memory or "general poker knowledge"
- [ ] Numbers rounded to 1 decimal place; no machine precision
- [ ] No specific EV numbers in prose (qualitative only)
- [ ] No hedge words ("clearly", "obviously", "of course", "naturally")
- [ ] Suit symbols ♥️ ♦️ ♣️ ♠️ used consistently
- [ ] Format structure matches the variant template

## Pre-PR
- [ ] `tool_trace.json` (or pulled `*.json`) committed with the data I cited
- [ ] `hygiene_check.md` shows PASS (DA-pipeline) or N/A (ad-hoc)
- [ ] `ship_check_article.py ` passes (ad-hoc only)
- [ ] Article folder follows the `_template/` structure for the track
- [ ] Nothing in my changes touches the SHARING_POLICY.md never-commit list
- [ ] PR title is `[ hand-XXXX-YY]` (DA) or `[ad-hoc ]` (ad-hoc)

## After PR
- [ ] Tagged track owner (Harold+Chris or Thanh) and reviewer(s)
- [ ] Will respond to reviewer feedback within 2 working days
```

## In doubt?

- Format unclear → look at existing articles in `ad-hoc/articles/` (37 examples) or `da-pipeline/`
- Pipeline question → ping your track owner
- IP / partner data concern → don't push, ask first