polymath-society 0.2.4

package/dist/pipeline/TECHNIQUES.md

@@ -0,0 +1,406 @@
+# The best ways to use Claude Code — the gap rubric
+
+Recommend from THIS catalog only. It is sourced primarily from **Boris Cherny** (he created
+Claude Code): his "tips from the Claude Code team" thread (Feb 2026,
+[x.com/bcherny](https://x.com/bcherny/status/2017742743125299476)) **and** his newer threads on
+loops, mobile/remote, and `/batch` (spring 2026). It also includes a few first-party Claude Code
+features he and the team ship: **session forking**, **`/by the way` side queries**, the **Chrome
+extension**, **slash commands**, and **`SessionStart` hooks**. If a technique isn't in this file,
+it is out of scope — no "auto mode," no `/compact`/`/clear`, no model-effort tips.
+
+---
+
+## ⛔ CRITICAL — DISCUSSING a feature is NOT USING it
+
+This person builds tooling FOR Claude Code, so their transcripts are saturated with the words
+"worktree," "pull request," "fork," "plan mode," "by the way," "teleport," etc. **A keyword in a
+transcript is NOT evidence they use the feature** — it usually means they were talking about
+building it. **Gate every recommendation on STRUCTURAL usage facts** (tool-call counts,
+`EnterPlanMode` count, session `entrypoint`s, git branch names, `duplicateOf` copies,
+`maxConcurrent`, `subagentSpawns`) — never on a keyword appearing in the text.
+
+## ⛔ Claude-auto tools — NEVER recommend or credit these
+
+Some tools Claude reaches for on its own; they are NOT the user's choice: **visualize /
+show_widget** (visual widgets & HTML), **live-preview / Claude_Preview**, **queue-ahead**,
+**deferred-tools (ToolSearch)**, **subagent fan-out**, **task orchestration
+(TaskCreate/Update)**, **web-research (WebSearch/WebFetch)**. Never write "use visualize MCP" or
+name any of these — the user just ASKS Claude for the outcome and Claude picks the tool. These are
+filtered from the builder's inputs (`CLAUDE_AUTO_CAP` / `CLAUDE_AUTO_MCP` in
+`scripts/coding-gap.mts`).
+
+---
+
+## THE PRIME DIRECTIVE — order recommendations most-difference-making → least
+
+Every recommendation carries a **`differenceRank`** (1 = the single biggest unlock for THIS
+person). The report shows them in that order. The ranking is **conditional on their data**:
+
+- **If they are NOT already running several agents in parallel** (`maxConcurrent` < 2, or
+  `parallelHours` ≈ 0) → **"Do more in parallel" is `differenceRank` 1.** For someone working one
+  agent at a time, nothing else comes close.
+- **If they already parallelize** (`maxConcurrent` ≥ 2) → **"Invest in your CLAUDE.md / tune your
+  context" is `differenceRank` 1.** Boris's framing: better context *dramatically* improves
+  performance, and it is the highest-leverage move for someone who already runs agents in parallel.
+
+Then, in general (skip any that don't apply, and honor each tip's gate):
+
+> parallel (if low) → **CLAUDE.md / context** → **Plan mode** → **give Claude test cases (auto-
+> verify, run longer)** → **subagents** → loops (if collaborative) → remote/mobile (if workstation-bound) →
+> forking → slash commands → Chrome extension → `/by the way` → skills → visuals → the de-emphasized
+> three (bug-fixing, prompting, data/analytics).
+
+Respect the person's deliberate choices in the gap config (e.g. they stay on `main` on purpose —
+never tell them to hand-juggle worktrees; `/batch` managing its own worktrees is fine).
+
+**Omission rule — a gated tip whose gate fails is DROPPED, never softened.** If the data says a tip
+doesn't apply (no PRs → no loops) it does not appear at all — a "when you someday…" card reads as
+not having looked. If the data says they ALREADY do it (recent forking, regular browser-driving,
+voice), it moves to **alreadyStrong** — never to recommendations. Judge "already do it" on the
+RECENT window: adopting a habit last week counts as doing it.
+
+---
+
+## 1 · Invest in your CLAUDE.md — tune your context  [usually the #1 unlock]
+
+**The core Boris point: better context dramatically improves performance, and tuning it is the
+highest-leverage thing you can do.** After any correction, *"just tell Claude to add that to your
+CLAUDE.md"* — one line, and it's remembered every future session so you never re-type it. Then
+ruthlessly refine it (keep it tight — under ~200 lines or Claude starts ignoring rules).
+
+- **Teams / shared context [EMPHASIZE when they collaborate]:** CLAUDE.md is checked into git, so
+  it is *shared project context* — every teammate (and every future session) inherits the same
+  conventions, commands, and architecture. On a team this compounds: one person's hard-won
+  correction becomes everyone's default.
+- **Nested CLAUDE.md per subfolder:** a subdirectory can have its OWN `CLAUDE.md`. Claude Code
+  loads it **automatically, on demand** — the moment Claude reads any file in that subtree, that
+  folder's CLAUDE.md is pulled into context. Nothing extra to wire up (the root file is loaded at
+  launch; subtree files load when touched). So subsystem-specific rules (e.g. "in `packages/x/`,
+  always do Y") belong in a CLAUDE.md *next to that subsystem*, not crammed into the root file.
+- **The sub-agents you should have defined:** recurring multi-step jobs deserve a saved, reusable
+  subagent in `.claude/agents/` — and that agent should be NAMED in CLAUDE.md so Claude reaches for
+  it. Ground this: point at a specific repeated job in THEIR sessions that should be a standing
+  subagent + a CLAUDE.md line telling Claude when to use it.
+- **How to instruct Claude to do it:** the move is dead simple and worth spelling out — you don't
+  hand-edit the file; you say *"add that to your CLAUDE.md"* / *"make that a subagent and note it in
+  CLAUDE.md,"* and Claude writes it. Say this explicitly so they know the cost is one sentence.
+- **`SessionStart` hook (only if warranted):** static CLAUDE.md holds ~95% of context (architecture,
+  conventions, exact commands, "never use X library," testing workflow). A `SessionStart` hook is
+  for *dynamic, computed* context that CLAUDE.md can't hold — a summary of recent commits, the
+  current branch, the assigned ticket, config pulled from elsewhere. Only suggest the hook if their
+  sessions show repetitive *computed* setup; otherwise CLAUDE.md is simpler and you should say so.
+- **whyItHelps must name THEIR OWN recurring standing instructions** — discover them from the
+  excerpts (common classes: a "talk to me before you change things" rule, a house convention about
+  how a rubric/output should be shaped, an "always give concrete examples" rule) — and say the fix
+  is one line: tell Claude to add them. Do NOT invent the instruction; find the one they actually
+  repeat.
+- **KEEP OUT** (so the illustration stays honest): anything Claude can read from the code, standard
+  conventions it knows, pasted code snippets (they rot — use `file:line`), README duplication
+  (`@README`), vague fluff ("write clean code").
+- **Signal:** the SAME standing instruction recurs across sessions; a thin or absent CLAUDE.md;
+  subsystem rules re-typed instead of living in a nested CLAUDE.md; repeated multi-step jobs with no
+  saved subagent.
+
+## 2 · Start every complex task in Plan mode  [EMPHASIZE — high priority]
+
+*"Pour your energy into the plan so Claude can 1-shot the implementation."* Shift+Tab twice to enter
+Plan mode; iterate the plan in detail until it's solid, then let Claude execute. If it drifts, go
+back and re-plan rather than pushing through. Skip it only when you could describe the diff in one
+sentence.
+
+- **Name the problem precisely:** skipping plan mode makes the model pause mid-build to ask for
+  feedback and drift from intent — so the person ends up steering turn-by-turn *during*
+  implementation what they could have settled once, up front. **The plan IS the feedback loop** —
+  iterating on it (with no context-switching cost, since nothing's been built yet) is what makes
+  both of you think better and produces a much better system in one shot.
+- **Ground it:** find a real session where they iterated a lot mid-implementation to fine-tune
+  something — that back-and-forth belonged in the plan.
+- **See the plan as HTML, not a wall of markdown [Tariq, "the unreasonable effectiveness of HTML
+  files"]:** while in Plan mode, ask Claude to render the design/UI as an HTML mock you can click
+  through — even a few different directions side by side — instead of a long markdown plan nobody
+  reads. HTML is information-dense and ergonomic; you catch a misunderstanding by *seeing* it before
+  any code is written, and can screenshot it back to Claude to refine. (Do NOT name the tool — the
+  user just asks Claude to "show me this as HTML.")
+- **Keep THIS rec about iterating the DESIGN — not test cases.** The "seed the plan with expected
+  results / test cases so Claude runs autonomously longer" idea now lives in its own tip (#3, Give
+  Claude a way to verify its own work). Do NOT put test-case/fixture copy in the plan-mode
+  recommendation too — the two cards must not echo. Plan mode here = settle the approach and see it
+  as HTML before code.
+- **Signal:** `EnterPlanMode` ≈ 0 while sessions are large multi-file changes; lots of
+  mid-implementation back-and-forth or `[Request interrupted by user]`; the person literally says
+  "discuss the architecture/approach first" but isn't in plan mode.
+
+## 3 · Give Claude test cases up front so it can auto-verify and run longer  [EMPHASIZE — Boris: "the most important thing"]
+
+**The single highest-leverage habit in both Claude Code talks: give Claude some way to CHECK its own
+output, and it will iterate to near-perfect on its own.** Boris, verbatim: *"Give it some sort of
+tool that it can use for feedback to check its work, and it will iterate by itself, and you're going
+to get a much better result."* Hand it a mock and a way to see the rendered result, unit tests to
+run, a screenshot to compare — *"let it iterate two or three times, often it gets it almost
+perfect."*
+
+- **LEAD WITH: "make the test cases up front, so Claude can work for much longer."** This is the
+  clearest, highest-value framing — write the expected outputs / test cases BEFORE the work starts,
+  and Claude runs autonomously far longer without stopping to ask, because it checks itself as it
+  goes. The whyItHelps should open on this.
+- **What makes a good test-case recommendation — GENERAL PRINCIPLES, illustrated with a GENERIC
+  example (never the person's own codebase; the builder specializes these to their project):**
+  **Core idea: the richer and more DETAILED the test cases handed to Claude UP FRONT, the more it
+  has to work off of — more data up front = better, more autonomous results. So the test cases you
+  recommend to THIS person (grounded in their own usage) must themselves be rich and detailed, not a
+  token example.**
+  1. **Rich and comprehensive — a LIST of behaviors, not one case.** Tell them to have Claude
+     enumerate the FULL set of behaviors/scenarios to test and test each on its own — the whole
+     surface, edge cases included, not a single happy path. Generic illustration: for a to-do app
+     that's adding an item, removing an item, editing an item, completing an item, emailing an item,
+     an empty list — a real, complete list.
+  2. **At a HIGH level of abstraction — the flows the person already keeps in their head.** Test
+     cases are USER-LEVEL flows and behaviors, the kind the person can rattle off in one breath:
+     for a to-do app, "add an item, remove an item, modify an item, send an item as an email to a
+     friend." NEVER implementation-level assertions ("make sure this function fires at this time")
+     or internal-machinery checks — the person doesn't think in those terms, and supplying them is
+     far too cognitively expensive. If a case couldn't plausibly come out of the person's mouth,
+     it's at the wrong level; Claude translates the high-level flows into detailed tests itself.
+  3. **The WHY rides along with every case — richness lives in the REASON, not in machinery
+     detail.** A test case is `example/flow → expected outcome → the reason it's correct`. A bare
+     expected value ("X = 11", "add item works") teaches Claude nothing about WHY it's right — the
+     reason is exactly the "more data up front," and it's what lets Claude verify it got things
+     right FOR THE RIGHT REASONS, not by luck. FEWER cases each carrying a reason beat a long list
+     of bare values.
+  3b. **Write every case FROM THE PERSON'S POINT OF VIEW — what they'd actually remember.** Ask:
+     given what this person is building, which cases do they already know really well in their head?
+     Those are the ones to suggest. The reason must read like the person's own recollection —
+     first-person, vivid-but-possibly-vague ("in that conversation I came up with the concept
+     myself — I thought that was brilliant"), because a vibe-level memory is all a real person has.
+     NEVER analyst/rubric language ("applies an existing model correctly but never stress-tests its
+     assumptions") — no person describes their own memories that way, and asking them to is
+     cognitively expensive. Vague is fine; Claude sharpens a vague memory into a precise check
+     itself.
+  4. **Reasons come from the PERSON, never invented.** When the card shows example cases, each
+     attached reason must be TRACEABLE to something the person actually said/argued in their
+     sessions (their own words, their own argument) — never analysis the model composed to sound
+     right. If no traceable reason exists for a case, do NOT fabricate one: frame it as "Claude
+     drafts the candidate list with proposed reasons; you correct them from memory" — the person is
+     the only source of the memorable reasons.
+  5. **Generated by Claude from the project, then reviewed.** Ask Claude to produce the rich list
+     from the actual code/spec; you review and correct it — fuller coverage than hand-typing cases.
+  6. **Up front, so it runs longer — asked for in PLAIN ENGLISH.** The list exists before the work
+     starts, so Claude checks itself after each change and runs autonomously far longer. Do NOT
+     prescribe wiring a CLI harness or command (`bun run evals`-style plumbing) — the person just
+     tells Claude in English to check against the cases; Claude handles the mechanics itself.
+  The whyItHelps APPLIES these to whatever the person is building (do NOT assume any particular kind
+  of app): a list of HIGH-LEVEL flows/behaviors their project should test, with the REASON attached
+  to at least the anchor cases — the kind of list they could say out loud in one breath. FAILED
+  cards: internal-machinery assertions (per-subsystem/per-function checks); a single thin case; a
+  run of bare `X = value` pairs with no reasons. This card may run longer to fit the list. This
+  rubric states only the principles + the generic illustration; the person-specific cases come from
+  their data.
+- **Make verification NATIVE to the artifact [Tariq's workshop — the deepest level]:** don't leave
+  yourself as the one who eyeballs correctness. Build the check *into the thing*: expected outputs
+  as fixtures, invariants that must always hold, probes that push off the happy path, and a single
+  command (or DOM/data contract) Claude can run to see pass/fail — from a human dashboard, from the
+  browser, or headlessly in CI. The Claude Code team even records these verification runs as
+  evidence.
+- **This is BROADER than plan-mode test cases (tip 2).** That was "seed the plan with a few expected
+  results." This is a *standing verification harness* Claude runs after every change, on every task
+  — so it self-corrects instead of you re-checking by hand.
+- **Ground it in THEIR work (state the principle generically; let the model find the instance):**
+  when the person builds something whose correctness they can specify — an evaluation/scoring
+  engine, a data transform, a parser — the move is to encode the expected results and invariants as
+  a self-check Claude runs itself, so it catches its own regressions. Point at where they are
+  currently the manual verifier (re-reading outputs, re-checking a view by hand after each change)
+  and show how a one-command self-check would take that off them and let Claude iterate unattended.
+- **The recommendation TITLE must be about TEST CASES and contain "test cases" (e.g. "Give Claude
+  test cases so it can auto-verify and run longer")** so the report picks the right icon. Do NOT
+  name a Claude-auto tool for the "see the result" step — the user just asks Claude to check its
+  work / show the result.
+- **Signal:** the person is the one eyeballing correctness after each change; UI/output checked by
+  hand; no test/`verify` step the agent runs itself; long sessions of manual back-and-forth that a
+  self-check would have closed. (Note: they already drive the browser a lot — the gap is turning
+  that manual checking into a check CLAUDE runs and iterates against.)
+
+## 4 · Use subagents  [EMPHASIZE — high priority]
+
+Append **"use subagents"** to any request to allocate more compute; **"use 5 subagents to explore
+the codebase"** for parallel exploration; offload heavy sub-work so the main agent's context stays
+focused. Save reusable ones in `.claude/agents/`. **[Make it visceral with THEIR work: name the
+exact request in their sessions where this was the move — e.g. a broad "explore/analyze the whole
+X→Y pipeline" ask that ran single-threaded and should have been "use 5 subagents to explore."]**
+
+- **Signal:** broad explore/analyze requests run single-threaded; low `subagentSpawns`; never saves
+  reusable agents.
+
+## 5 · Run loops for the collaborative grind  [GATE on collaboration volume]
+
+Boris runs cron loops that babysit PRs and fix CI automatically — *"every night I have a few
+thousand agents running,"* 150 PRs in a day, much of it from his phone. His actual loops:
+
+- `/loop 5m /babysit` — auto-address code-review comments, auto-rebase, shepherd PRs to production.
+- `/loop 30m /slack-feedback` — put up PRs for Slack feedback on a cadence.
+- `/loop /post-merge-sweeper` — open PRs to address review comments that were missed.
+- `/loop 1h /pr-pruner` — close out stale, no-longer-needed PRs.
+
+**[REQUIRED — quote Boris VERBATIM: the whyItHelps for this tip MUST list his exact loops with his
+exact wording — `/loop 5m /babysit` (auto-address code review, auto-rebase, and shepherd PRs to
+production), `/loop 30m /slack-feedback`, `/loop /post-merge-sweeper`, `/loop 1h /pr-pruner` — not a
+paraphrase. It is fine for this card to run longer than the others to fit them.]**
+
+Also **`/batch` for big one-off parallelizable work** (migrations): it interviews you, then fans the
+work out to *"as many worktree agents as it takes (dozens, hundreds, even thousands),"* each isolated
+in its own worktree, each testing its work before opening a PR. Usage:
+`/batch migrate src/ from Solid to React`.
+
+- **[GATE — CRITICAL: loops are almost entirely for COLLABORATIVE work — PRs, pushes, review, CI.
+  Surface loops ONLY if the STRUCTURAL data shows real collaborative volume: many `git push`/`gh
+  pr`, branch-per-feature, review activity. For a solo builder who works on `main` and doesn't open
+  PRs, this tip FAILS its gate — OMIT it from recommendations ENTIRELY, not even a light/conditional
+  "when you someday open PRs" card; recommending PR-shepherding loops to someone with no PRs reads
+  as not having looked at their data. `/batch` applies to anyone facing a large one-off migration —
+  but only mention it if a migration is actually visible in their sessions, and then inside another
+  relevant card or on its own merits, not as a vehicle to sneak the loops card in.]**
+- **Signal:** high `git push` / `gh pr` / review volume, multiple feature branches → loops fit; a
+  looming large migration or sweeping mechanical change → `/batch`.
+
+## 6 · Code from anywhere — mobile app, `/teleport`, `/remote-control`, a remote instance  [GATE on workstation-bound]
+
+Boris writes a lot of his code from the **iOS/Android app** (Claude app → Code tab): a convenient
+way to make changes without opening a laptop. And you can move a session across surfaces:
+`claude --teleport` or `/teleport` continues a cloud session on your machine; `/remote-control`
+controls a locally running session from your phone or the web (he keeps "Enable Remote Control for
+all sessions" set in `/config`). About half his engineering now happens on his phone.
+
+- **Remote instance:** stand up a persistent remote box (e.g. an **EC2 instance**) so agents keep
+  running when your laptop is closed. The **mobile app can connect straight to that remote
+  instance** — much easier than reaching a session running on your local machine — so you kick off
+  and check work from your phone. Worth the one-time setup if you're otherwise stuck coding only
+  when you're physically at your desk. **[whyItHelps SHOULD mention the iOS app connecting to the
+  remote instance as the payoff.]**
+- **[GATE — only if the person is WORKSTATION-BOUND: all sessions come from the desktop app /
+  terminal at their machine, with ZERO web or mobile `entrypoint`s. That means every bit of their
+  work is gated on being at the workstation — the unlock is being able to kick off and check agents
+  from their phone via a remote instance. If they already have web/mobile sessions, this is a
+  strength, not a gap.]**
+- **Signal:** `entrypoint`s are 100% desktop/CLI with none web/mobile → recommend the mobile app +
+  `/remote-control` + setting up a remote (EC2) instance. Icon key: "remote" / "EC2" / cloud.
+
+## 7 · Fork your session — branch the context instead of rebuilding it
+
+Forking clones a session's full context at a point, so you can chase a side path or spin up a
+parallel line of work WITHOUT re-establishing everything from scratch. It's one of the best ways to
+both **save context** and **parallelize** — you branch from a shared, already-warmed-up setup.
+
+- **[CHECK the logs — and judge on the RECENT window, not all-time: `duplicateOf` marks resume/fork
+  copies (it conflates the two). If the RECENT count shows they fork in the current window, they
+  have ALREADY adopted it — this tip FAILS its gate: OMIT it from recommendations and credit it
+  under alreadyStrong (someone who started forking last week must not be told to start forking).
+  Only surface forking as a gap when recent forking is ~absent, grounded in a moment where a fork
+  would have carried the context.]**
+- **Signal:** long sessions rebuilt from scratch when a fork would have carried the context; ~zero
+  `duplicateOf` copies in the RECENT window.
+
+## 8 · Turn repeated multi-step prompts into slash commands  [team leverage]
+
+Boris uses a `/commit-push-pr` command dozens of times a day. Commands live in `.claude/commands/`,
+checked into git — so on a **team, everyone shares the same commands** and the same "inner loop"
+workflows. It's the lighter, prompt-level sibling of a skill.
+
+- **[Ground with concrete commands THIS repo could have — DERIVE the class from their repeated
+  multi-step prompts, don't hardcode their exact wording. E.g. if they re-type a multi-step "run the
+  analysis / regrade / regenerate the snapshot" sequence, that's a `/`-command. Name 2–3 plausible
+  commands their repo is missing.]** Emphasize the team payoff if they collaborate.
+- **Signal:** the same multi-step prompt re-typed across sessions; no `.claude/commands/`.
+
+## 9 · Use the Chrome extension to automate whole browser tasks  [GATE — omit if they already use it]
+
+The Claude Chrome extension lets Claude drive a real browser and **automate complete web tasks end
+to end** — the chores that can ONLY be done through a front end: signing up for things (programs,
+awards, services), retrieving credentials/API keys from dashboards, filling and submitting forms,
+working through auth-gated or JS-only flows. Hand Claude the whole errand, not just a click.
+
+- **[GATE — CRITICAL: if their usage shows they ALREADY drive the browser regularly
+  (usage.chrome.chromeToolCalls is substantial), this tip FAILS its gate — OMIT it from
+  recommendations entirely and credit it under alreadyStrong. Recommending the Chrome extension to
+  someone who already uses it reads as not having looked at their data. Only recommend when
+  browser-driving is absent, grounded in a web chore from their sessions Claude could have run.]**
+- **Signal:** ~zero browser-driving tool calls PLUS manual web chores visible in their sessions.
+
+## 10 · Use `/btw` for side queries while an agent runs
+
+While the main agent is working, the **`/btw`** command lets you fire a side question — understand a
+piece of the codebase, sanity-check an assumption, look something up — WITHOUT interrupting or
+derailing the run. It reuses the conversation's context (so it's near-free), answers in an overlay
+that vanishes, and keeps the main task moving while you learn alongside it. The command is `/btw`,
+not "by the way".
+
+- **[Tell them they're UNDER-using this: they interrupt running work (or context-switch) to ask
+  small questions that could have been `/btw` side queries. Ground in a moment where they broke a
+  run to ask something. The recommendation TITLE should say `/btw`.]**
+- **Signal:** `[Request interrupted by user]` to ask a question; stopping a run to ask something
+  small that didn't need to halt the work.
+
+## 11 · If you do something more than once a day, make it a skill
+
+Boris's rule, verbatim — *"If you do something more than once a day, turn it into a skill or
+command"* (`.claude/skills/<name>/SKILL.md`, checked into git). **[The recommendation TITLE must be
+this GENERAL rule (Boris's wording), NOT a specific skill name. The specific instance goes inside
+whyItHelps — e.g. a multi-step startup briefing they re-type at the start of every session is the
+obvious thing to make a skill.]** Boris's examples: `/techdebt`, context-sync commands, dbt agents.
+Import instead of building: `skill-creator` ([anthropics/skills](https://github.com/anthropics/skills)),
+marketplace plugins (**commit-commands**, **pr-review-toolkit**, **security-guidance**).
+
+- **Signal:** repeated multi-step manual prompts that should be one command; no custom skills.
+
+## 12 · Have Claude explain things to you with visuals
+
+**[Problem-led: the person built their own system (rubrics, a scoring/collector pipeline, etc.) but
+doesn't fully hold how the mechanics fit together — they re-question outputs and re-derive the logic
+repeatedly. Solution: just ASK Claude to build a visual, interactive walkthrough of how it works (do
+NOT name a tool — Claude picks it; the user never "uses visualize MCP"). In their context: an
+interactive page stepping through their own pipeline makes the mechanics clear once, so they stop
+re-explaining.]** Also: the **Explanatory** output style; a **spaced-repetition** skill.
+
+- **REQUIRED in whyItHelps — the plan-as-HTML move [Tariq, "the unreasonable effectiveness of HTML
+  files"]:** the recommendation MUST include that, while in Plan mode, they can ask Claude to render
+  the design/plan as clickable HTML mockups (even a few different directions side by side) instead
+  of reviewing a long markdown plan. Seeing it as HTML is denser and more ergonomic — they catch a
+  misunderstanding before any code is written, and can screenshot it back to refine. This is the
+  most concrete, highest-value form of "explain with visuals," so lead the whyItHelps with it. (Do
+  NOT name the tool — the user just asks Claude to "show me this as HTML.")
+
+- **Signal:** repeatedly asks "how does X work" / "how are the numbers assigned" about THEIR OWN
+  system → have Claude build a visual explainer or mock site that shows how it works.
+
+---
+
+## De-emphasized (surface only on a clear, repeated instance)
+
+## 13 · Claude fixes most bugs by itself  [DE-EMPHASIZE]
+Enable the Slack MCP, paste a bug thread, say "fix"; "Go fix the failing CI tests"; point Claude at
+docker logs. **Signal:** only if their sessions show them hand-relaying bug reports / CI failures
+the agent could pull and fix itself.
+
+## 14 · Level up your prompting  [DE-EMPHASIZE]
+Challenge Claude as a reviewer, request behavior diffs; after a mediocre fix, "implement the elegant
+solution"; write detailed specs. **Signal:** low priority — only a clear, repeated instance of
+accepting a weak first attempt.
+
+## 15 · Use Claude for data & analytics  [DE-EMPHASIZE]
+CLI tools like `bq` for BigQuery directly inside Claude Code. **Signal:** only if their sessions
+show them manually running/relaying DB queries.
+
+---
+
+## Voice dictation (interface QoL — detect, don't assume)
+
+Double-tap `fn` on macOS for ~3× typing speed. **[DETECT from prompt length: consistently SHORT
+prompts → they TYPE → recommend voice AND a cheap (~$20) USB mic. LONG / run-on / speech-like
+prompts → they already dictate → treat as a STRENGTH, do NOT recommend voice.]**
+
+---
+
+**Sources:** Boris Cherny — "tips from the Claude Code team"
+([x.com/bcherny](https://x.com/bcherny/status/2017742743125299476)); the loops / mobile /
+`/teleport` / `/remote-control` / `/batch` thread (spring 2026); plus first-party Claude Code docs
+for nested CLAUDE.md ([on-demand subtree loading](https://code.claude.com/docs/en/claude-directory)),
+remote control ([docs](https://code.claude.com/docs/en/remote-control)), forking, `/by the way`,
+slash commands, and `SessionStart` hooks.

package/dist/pipeline/WRITING.md

@@ -0,0 +1,48 @@
+# Coding-report writing rubric — the house voice
+
+Every line of user-facing copy in the coding report (component strings, LLM-written
+sections, coaching, headlines) must pass this rubric. If a sentence fails, cut or rewrite it.
+
+## The one rule: NO FLUFF
+
+Fluff is any text that does not carry a fact, a number, a named thing, or a decision.
+If you delete the sentence and the reader loses nothing concrete, it was fluff. Cut it.
+
+Banned outright:
+- Throat-clearing subtitles that restate the section title in prettier words
+  ("the deliberate moves you make, and where the frontier is" → DELETE).
+- Adjective stacks that assert quality without evidence ("genuinely strong, real,
+  discriminating taste"). Show the instance instead.
+- Hedge-and-flatter filler ("a real, developing sense", "a strong signal", "honestly").
+- Meta-narration ("Here's the honest read:", "In a nutshell —", "Let's look at").
+- Generic best-practice advice not tied to THIS person's data.
+
+## Concrete or it doesn't ship
+
+- Name the thing: the skill (`deep-research`), the project (Polymath Society), the
+  session, the date, the number. Never "various tools" or "several sessions".
+- Every quality claim must be anchored to a specific instance the person will recognize:
+  "you reframed the grading rubric around load-bearing rungs on 06-12" beats
+  "strong abstraction". The point is they think "oh — it actually saw that."
+- Prefer one sharp example over three vague ones.
+
+## Nothing important in grey
+
+Grey (`text-faint`/`text-muted`) text is skimmed past and ignored. If it matters, it is
+`text-ink` (black) and weighted. Grey is only for axis labels, units, and true asides.
+Never put a real finding, a name, or a number in grey.
+
+## Make them feel seen, don't flatter
+
+Seen = you named something true and specific about how they work that they hadn't seen
+articulated. Flattery = adjectives with no referent. Calibrate praise to what's load-bearing
+and TRUE (see lib/agents/report/feel-seen-rubric.md), then point at the receipt.
+
+## Mechanics
+
+- Short. One idea per sentence. Cut every word that isn't doing work.
+- Active voice, second person ("you"), present tense.
+- A number beats a word; a named instance beats a number; the reader's own recognition
+  beats both.
+- Coaching tells them ONE concrete thing to do differently, drawn from their data — not a
+  menu, not a platitude.