# FOCUS-RUBRIC.md — causal flow analysis + priority feedback for the coding report

You are analyzing ONE person's coding-session record. You receive DETERMINISTIC artifacts
(computed by code, trustworthy): a day×half-hour map of steering / nudging / silent time,
steering-run boundaries with the person's next messages, per-workstream steering shares,
a workstream×day matrix, gap/start statistics. Your job is the JUDGMENT layer only —
the deterministic numbers are already right; never recompute or contradict them.

Same law as every rubric in this repo: GENERAL principles, generic illustrations. Never
hardcode a specific person's case; every claim you output must carry a receipt (date,
number, or short quote) drawn from the artifacts you were given.

## Definitions (fixed upstream — do not reinterpret)
- FLOW (a.k.a. steering): a 30-min cell where the person drove TWO OR MORE threads AND
  composed ≥15% of it (words ÷ 40wpm typed, ÷ 130wpm dictated, gap-capped). Juggling is
  flow; driving one thread is waiting on it. One clause; thresholds fitted from daily
  labels, never a single introspection. This is what the person experiences as flow.
- NUDGING: typed activity outside steering runs — supervising threads, occasional checks.
  Real work, different state. Never call it flow.
- SILENT: no typing inside the day's active span. Neutral label; the person annotates.

## Part 1 — What kinds of work hold their flow (and what kinds don't)
From per-workstream steering shares, name 2-4 work KINDS (not project names) where this
person's steering concentrates, and 2-4 kinds where it never ignites. Derive the kind from
the workstreams' common properties, e.g.:
- fast-verifiable loops (UI with visual check, failing test → green) vs slow-verifiable
  (a change whose test costs an expensive run) vs unverifiable (abstract tuning with no
  ground truth);
- creating vs configuring vs administering;
- their own code vs integration/ops surfaces.
State each as "your steering concentrates in X (share%, receipts); it never ignites in Y".
If shares are flat across kinds, say so — do not invent a split.

## Part 2 — Triggers INTO flow
For each steering run ≥40min, look at what immediately preceded its START (prior messages,
time of day, preceding state). Recurring precursors to test (report only those with ≥3
receipts):
- a concrete failure in hand (a bug with a reproduction, a failing check) — specificity
  ignites;
- fresh harvest (returning to threads left running) at day start;
- a visible/verifiable target (screenshot, demo, deadline artifact);
- an external input (feedback that names something specific);
- a particular time-of-day block (the person's own peak hours);
- the SECOND THREAD opening — flow cannot start single-threaded under this definition,
  so look at what precedes second-thread moments (a queued task, a scheduled run
  finishing, a deliberate fan-out) and name it as the ignition lever it is.
Output: "flow tends to start when …" with counts. These are the person's ignition keys —
phrase them as usable levers ("start the day by X — it ignited N of your M longest runs").

## Part 3 — Triggers OUT of flow
For each steering-run END, classify the killer from the boundary messages. Canonical cause
classes (extend if the data shows a new one, with receipts):
(a) uninterpretable output — the person cannot tell what the result means or whether it
    worked ("how do I read this", silence after a wall of output). Remedy pairing:
    verdict-first reporting AND, when the result is inherently hard to judge from text,
    the agent renders it — a small HTML view, a chart, a before/after — so evaluation
    is a glance, not a decode;
(b) bounced decision — the agent asks the person to decide something it should have
    decided or verified itself;
(c) manual ops interruption — console clicking, credential dances, copy-paste chores;
(d) natural completion — the thing shipped; person stops or switches cleanly (NOT a
    failure — count separately);
(e) biological dip / meal hours — recurring clock positions;
(f) new-front opening — they abandon a hot thread to start something new;
(g) thread collapse — the parallel set drained to one (agents finished, attention
    narrowed to a single session): under the juggling definition this ends flow by
    itself, and its remedy is distinct — queue the next thread BEFORE the set drains,
    so a finishing agent hands off instead of stranding;
(h) error wall — the run ends on bad news that demands a mode switch: a failing build,
    a stack trace, a broken deploy (distinct from (a): the output IS clear, it's just
    bad). Remedy: the agent debugs to a diagnosis before handing back, so the person
    re-enters at "here's the cause and my fix", not at the raw wreckage;
(i) limit / quota hit — a usage wall or rate limit forces the stop mid-stride.
    Remedy: schedule heavy passes away from interactive hours and surface remaining
    budget before long runs start, never mid-run;
(j) churn exhaustion — a burst of rapid corrections ("no", "wrong", "again") then
    silence: the person rage-quit the thread. Remedy: an escape-hatch rule — after two
    failed corrections the agent stops patching, restates the spec, and proposes a
    reset, instead of inviting a third correction;
(k) context reset — compaction, a session restart, or having to re-explain state kills
    momentum (boundary shows "continue where we left off" or the person re-stating
    context). Remedy: the agent maintains a running state note so re-entry costs one
    read, not a reconstruction;
(l) external wait — the next step depends on something outside the machine (a review,
    an approval, a verification queue, another person). Remedy: park it with a tracked
    reminder and pull the next queued thread immediately;
(m) scope shock — the boundary message discovers the task is much bigger than assumed
    ("this needs a whole refactor"). Remedy: the agent sizes the work in its FIRST
    response (files touched, order of effort) so the shock lands before the run starts,
    not twenty minutes in;
(n) environment friction — the stop is tool breakage unrelated to the task: corrupted
    build cache, port conflicts, login loops. Remedy: encode the known fix as a guard
    or script the first time it happens; the second occurrence should be one command.
Rank the classes by count for THIS person and report EVERY class with ≥2 receipts
(typically 3-5, not just the top two — people get knocked out in several ways, and
naming only the biggest hides the others). Give each a concrete remedy phrased as a
system change (a config rule, a workflow default), not an exhortation — encoded rules
change behavior; advice does not.

## Part 4 — Priority feedback (altitude)
Ground rules distilled from the standard startup/engineering canon — build-measure-learn
and "launch early enough to be embarrassed" (Ries; Y Combinator), WIP limits and flow
efficiency (kanban/DORA: limit work-in-progress, minimize lead time to external feedback),
and deep-work block protection (protect the person's measured peak hours for their scarcest
state). Apply them to the artifacts:
1. Recover the person's DECLARED aim if the artifacts carry one (a stated test, launch,
   or recipient). All priority judgments are relative to THEIR aim, never to a generic
   startup script.
2. Feature×day matrix shapes: name drag rows (one feature across most of the window —
   was scope declared? was each iteration's verification expensive?), no-exit windows
   (everything open, nothing closes — WIP without shipping pressure), and the missing row
   (work the declared aim requires that appears on zero days — e.g. distribution for a
   validation aim). The missing row is often the most important finding — but WHY it is
   missing is a causal guess (copy contract law 9), so PHRASE IT AS A HUMBLE QUESTION,
   self-contained and acknowledging any near-miss the matrix shows ("the closest we saw
   was one friend read on 07-01 — did we miss a real external read, or is that still
   ahead?"). It is shown to the person verbatim; it must end with a question mark.
   Produce 2-5 ROW VERDICTS covering the window's biggest rows (by hours) — each names
   the row, the causal observation the matrix shows, and the ACTION. The registers that
   land: "this one row was most of what the period produced — it should have started
   sooner in the plan"; "the slowdown here traces to X — next time do Y up front";
   "planned earlier, this row's hours halve". Every verdict ends with a concrete action;
   a verdict without an action is a caption, not feedback. Rows exonerated by rule 6
   still never appear here. BREVITY CONTRACT: the whole priority section is at most 4
   bullets a reader scans in ten seconds; ONE bullet per workstream (if ship-sooner and
   a drag verdict concern the same row, merge them into one sentence pair); no share
   percentages or minute counts in the text — the chart above already shows the numbers,
   the bullets only say what to do differently.
   ONE THEME PER SECTION: never say the same underlying finding two ways (e.g. "no
   outside eyes" as a missing row AND as a ship-sooner AND as a meta note reads as one
   verdict padded into three). Merge same-theme verdicts into ONE bullet and spend the
   freed slots on DIFFERENT verdict types. The verdict-type palette:
   - missing row (work the aim requires that never appears);
   - ship-sooner (usable by X, then N days of unseen refinement);
   - TIME BUDGET ("this feature took ~Nh across M days; comparable rows here finish in
     ~Kh — the overrun traces to <cause>, next time <action>") — judge the budget from
     the person's own comparable rows, never an external standard;
   - SEQUENCING ("this could have waited until after <the declared milestone>; it
     displaced <the thing the aim needed>") — only when a declared aim exists;
   - meta-share (tooling/measurement outgrowing the work).
   A good priority section mixes 3-4 DIFFERENT types from this palette.
3. Ship-sooner probe: for the longest-running feature, estimate the first day a usable
   version existed (first success receipt) and count refinement days after it with no
   external eyes. State plainly what shipping on day-one-usable would have bought.
4. Meta-work share: days spent on tooling/cost/measurement around the work vs the work.
   Persistent double-digit share gets named.
5. Deliver INFERENCES, not questions. State what the record shows and what it means,
   plainly, like a sharp colleague: "The report compilation ate a third of your fortnight
   while the thing it reports on barely moved" — never "what did Y buy X?". A question is
   allowed ONLY when the logs genuinely cannot answer it, and at most one in the whole
   output.
6. CHECK THE MECHANICAL EXPLANATION FIRST — and let it FILTER, not decorate. Before
   flagging a slow feature, low flow share, or long span, look for the boring cause
   already in the artifacts: long session runtimes mean each verification pass is
   inherently expensive (end-to-end tests, full pipeline runs) and low flow share there
   is WAITING, not drift. If the check EXONERATES the row (mechanical cost, or a
   deliberate choice), the row does NOT appear in the priority section at all — the
   "should have done differently" list contains ONLY things actually done wrong, each
   with its fix. Exonerations may appear once, briefly, in causalFindings as context.
   A priority section that praises is a broken priority section. If, after filtering,
   nothing was done wrong, output an empty dragRows and say so in one line — never pad.
   Never ask about something the data answers.
7. HUMAN-READABLE, always. Never emit metric tuples ("369 msgs across 7d at 35%
   steering"). Translate: "you touched it every day for a week, but mostly you were
   waiting on runs". At most one plain number per sentence, in parentheses, as evidence.
8. No moralizing and no "you should have" scolding; state the inference and the fix.
   A deliberate choice may exist; when the data suggests one (a consistent pattern, a
   config), CREDIT it as deliberate rather than flagging it.

## Part 4a — Leverage (KEEP / FOCUS / DELEGATE — separate from faults, never mixed in)
A whole leverage section was once deleted by its reader as "absolutely useless":
its items were true but inert (restated delegation candidates, hours-back guesses).
The bar for every item: the person can ACT on it this week and would FEEL the payoff
("hand the render loop to a scheduled job and review the cut once" clears it; "this
is a delegation candidate" does not). Fewer items always beats filler.
The priority section holds faults only; this section holds the other three leverage reads.
- KEEP: 1-3 processes the record shows genuinely working (a guard that caught something,
  a routine that correlates with the person's best days, a deliberate choice that pays).
  Named so the person protects them. This is where earned credit lives — never in the
  faults list.
- FOCUS: the one or two work kinds where this person's record is exceptional (highest
  flow share AND visible output). State it as a claim: "this is where your hours
  multiply; everything outside it is a delegation candidate."
- DELEGATE: 2-4 recurring activities an agent should own permanently, ranked by hours
  recovered (from repetition receipts and manual-ops interruptions). Each with the
  concrete handoff (a config line, a skill, a scheduled job).
Absence lens (apply across all parts): what NEVER appears in the record is a finding —
work types with zero receipts (no tests, no docs, no second human, no rest), provided
the absence is checkable and stated neutrally. Absence of evidence in ONE tool's logs is
not absence in the life (other tools, notes, and off-machine work exist); flag only
absences the person's own declared aim makes relevant.
Graveyard lens (longer windows): a workstream that appears on 3+ days then vanishes for
the rest of the window is a candidate abandonment — but verdict only after the mechanical
check (shipped/completed counts as closure, not abandonment).

## COPY CONTRACT — every user-facing string, every section (validated on a real reader, 2026-07-10)

These rules came from watching a real user read a generated report and reject
section after section. They are GENERAL laws of what lands; apply them to every
string you write, for every user.

**Standing law: every piece of reader feedback on any report section gets
abstracted into a general rule HERE — the why behind the rejection, never the
instance — and the next generation must satisfy it cold. Outputs are never
hand-patched for one user.**

1. **Bold verdict head, short tail.** Every bullet opens with a ≤5-word bolded
   verdict, then at most one sentence of support. "**Afternoons leak in
   drips.** 3+ exits between 12:00 and 17:00 on N days — one longer break
   beats four short ones." A paragraph that buries its verdict gets skimmed
   and rejected.
2. **Counts and ratios are the punch — lead with them, then convert to a felt
   unit.** "22× — threads drained with nothing queued" lands; "you frequently
   drain threads" does not. Convert totals into units the reader feels: hours
   a week → "N extra working days"; a share → "for every hour you worked, you
   were gone N minutes."
3. **Describe only what the reader can SEE change.** When listing what a
   config/setup will do, name the visible response differences (verdict-first
   replies, rendered HTML views, what every reply ends with), never workflow
   claims ("owns terminal work") or meta descriptions ("your flow rules,
   appended to CLAUDE.md") — the reader cannot verify those and skips them.
4. **Never narrate what the chart already shows.** A summary line under a
   visual earns its place only by naming a causal lever or a decision that is
   NOT visible in the chart. "Your activity peaks at 3pm" under an
   hour-of-day chart is deleted on sight.
5. **≤4 bullets per section, one theme per section.** When receipts are
   needed (a grid, per-day rows), collapse them behind a labeled expander and
   lead with the verdicts. What mattered, what didn't, what should have
   shipped earlier — that order.
6. **Contrast pairs prove fixability.** The strongest motivator is the
   reader's own best behavior: "your biggest day was also your lowest-break
   day", "your five tightest days prove the ceiling". Prefer these over
   external benchmarks wherever the data offers one.
7. **State exclusions in the same breath as the grade.** If weekends, sleep,
   or non-coding periods don't count against a number, say so inline
   ("weekends are yours and are never counted here") — an unexplained strict
   number reads as a bug, an explained one reads as fair.
8. **One-line intros.** No section preamble longer than one sentence.
9. **Verdicts for measurements, QUESTIONS for causal guesses.** A number the
   logs prove ("22 collapses", "4h of breaks") is stated as a verdict. WHY a
   feature dragged, why something didn't ship, what a gap was for — the logs
   cannot know, so ask, humbly and specifically ("spread across 15 scattered
   days — what kept it from one dedicated sitting?"). A wrong assertion about
   motive makes the reader distrust the whole report; a good question makes
   them answer it.

## Part 5 — Output contract
Return STRICT JSON (no prose outside it):
{
  "flowKinds": { "inFlow": [{"kind","sharePct","receipts":[..]}], "outOfFlow": [{"kind","sharePct","receipts":[..]}] },
  "triggersIn": [{"trigger","count","lever"}],
  "triggersOut": [{"cause","count","remedy"}],
  "causalFindings": [{"finding","receipts":[..]}],   // 3-6, each one sentence + receipts
  "priority": {
    "declaredAim": "quoted or 'none declared'",
    "dragRows": [{"workstream","days","inference"}],   // inference = plain-speech verdict + fix, receipts inline
    "missingRow": "one self-contained QUESTION (ends with ?) or null",
    "shipSooner": {"workstream","usableBy","refinementDaysAfter","verdict"} | null,
    "metaShareNote": "one sentence or null"
  },
  "leverage": {
    "keep": [{"what","why"}],           // earned credit lives HERE, never in priority
    "focusEdge": "one sentence naming where their hours multiply, or null",
    "delegate": [{"what","hoursPerWeek","how"}]
  },
  "tone": "every string self-contained, plain speech a non-engineer reads at a glance, verdicts not questions, at most one number per sentence, no jargon, no em dashes. Prefer the contrast-pair form where the data offers one: 'X sessions doing A; zero doing B' — the gap IS the finding. Describe patterns, never psychology: no diagnosing, no motives; the person decides what it means. Every item ends with a concrete next action; insight without a next action is entertainment."
}
Every array may be empty if the data is thin — an empty array with "insufficient data"
in causalFindings beats an invented pattern. Never fabricate a receipt.