fplkit 2.10.0__tar.gz → 2.11.0__tar.gz

{fplkit-2.10.0 → fplkit-2.11.0}/.agents/README.md

@@ -34,6 +34,8 @@ The four product skills (gw-prep, squad-builder, update-gw-prep, preview-ingest)
 
 These levels are a judgement, not a measurement. `max` is untested here and probably not worth its time and cost; a gameweek of gw-prep run twice, once at these levels and once with classic at `max`, is the experiment that would settle it. Change a level in the block and in its row together: `tests/test_skill_effort_levels.py` reads each skill's frontmatter and every `Agent tool parameters` block, and holds each row of this table to the block its Where cell names (`orchestrator` is the frontmatter; the other labels are the sub-agent blocks in document order), so a swapped, missing or misspelt row fails there rather than being dropped.
 
+The maintainer skills (release, release-notes, create-pr, build-test-plan, ab-brief) set no effort level and are not held to this table: they run once per release or PR, interactively, and follow the session's effort. ab-brief is the exception worth knowing, since the effort that matters is the vault session's, not its own, and it says in its brief which level that session should start at.
+
 How far each key reaches, quoted from the Claude Code docs as read on 14 October 2026:
 
 - `model` in the frontmatter ([skills, Frontmatter reference](https://code.claude.com/docs/en/skills#frontmatter-reference)): "The override applies for the rest of the current turn and isn't saved to settings. The session model resumes when you send your next prompt." So a follow-up question about the output ("why sell X?") is answered on the session model.

{fplkit-2.10.0 → fplkit-2.11.0}/.agents/TOOLS.md

@@ -42,7 +42,7 @@ see [Feed coverage warnings](../docs/command-reference.md#json-output).
 |---------|-------------|------|--------|-------------|---------|
 | `init` | Set up fpl-cli with your FPL IDs and optional features | No | General | No | direct-api |
 | `status` | Show FPL gameweek status and upcoming deadlines. JSON `metadata` carries `gameweek`, `format` and `season` (hyphenated label, e.g. `2026-27`) - `season` is the directory segment skills must use when writing alongside fpl-cli's own reports. `data.gameweek_info` carries `finished` beside `bonus_confirmed` and `league_tables_updated`, read from FPL's processing feed (`event-status`) for each game shown (the classic one alone when no format is configured): `true` only when every game's feed says so, `false` as soon as one says otherwise, and `null` otherwise - always `null` while the gameweek is in progress (the feed can report the days played so far as settled), and also whenever some game's feed could not answer and none said no, so with both formats `null` can mean one confirmed and the other was unreadable. `finished` comes hours before the league-table refresh (issue #424), so a skill gating a league recap should wait on `league_tables_updated` being `true`, and table mode prints both beside "Finished" | Yes | General | No | direct-api |
-| `doctor` | Check the setup for dead IDs, stale data, and config problems: resolves each configured ID against the live API (reporting the team/league name back so a wrong-but-valid ID is visible), verifies per-team data files (team ratings, managers, season preview intel, finances, player prior) describe the current season's clubs, reports whether the calibrated quality ceilings were measured against the newest completed season (the one season-derived artefact frozen in code, so a rollover with no recalibration leaves the scoring scale anchored to a cohort that has turned over), and reports which config/data/cache directories are in use. With `--providers`, probes the external data sources instead: live shape-and-volume checks against the FPL and Draft APIs (including that the draft game's club list agrees with the main game's by club code, since every draft path translates club ids through it), the vaastav and Core-Insights datasets, Understat, and football-data.org, including that every club resolves across sources and that players actually join by name (both Understat checks call the enrichment's own gate and matcher on the payload the scoring commands scan, so probe and runtime cannot disagree; a club resolving does not mean its players' names line up) and that the Core-Insights per-gameweek files parse to records through the parsers the scoring commands use (the drift that otherwise surfaces as plausible but wrong output). Distinguishes broken (needs a fix today) from stale (self-corrects, or waits on an upstream fix the tool works around). Exits non-zero when something is broken | Yes | General | No | direct-api |
+| `doctor` | Check the setup for dead IDs, stale data, and config problems: resolves each configured ID against the live API (reporting the team/league name back so a wrong-but-valid ID is visible), verifies per-team data files (team ratings, managers, season preview intel, finances, player prior) describe the current season's clubs, reports whether the calibrated quality ceilings were measured against the newest completed season (the one season-derived artefact frozen in code, so a rollover with no recalibration leaves the scoring scale anchored to a cohort that has turned over), and reports which config/data/cache directories are in use. With `--providers`, probes the external data sources instead: live shape-and-volume checks against the FPL and Draft APIs (including that the draft game's club list agrees with the main game's by club code, since every draft path translates club ids through it), the vaastav and Core-Insights datasets, Understat, football-data.org, and the Premier League's awards feed the draft Player of the Month voucher reads (run through the recap's own parser, with its winners joined on FPL codes), including that every club resolves across sources and that players actually join by name (both Understat checks call the enrichment's own gate and matcher on the payload the scoring commands scan, so probe and runtime cannot disagree; a club resolving does not mean its players' names line up) and that the Core-Insights per-gameweek files parse to records through the parsers the scoring commands use (the drift that otherwise surfaces as plausible but wrong output). Distinguishes broken (needs a fix today) from stale (self-corrects, or waits on an upstream fix the tool works around). Exits non-zero when something is broken | Yes | General | No | direct-api |
 | `fixtures` | Show fixtures for a gameweek. With custom analysis on, FDR is the venue-aware ATK/DEF mean `fpl fdr` and `fpl preview` show, so one match reads the same on all three; `-m/--mode` picks `difference` (default) or `opponent`, an unrated club scores a neutral 4.0 rather than the FPL API's 1-5 difficulty, and when the ratings cannot support difficulty at all, table mode warns on stderr and JSON adds a `team_ratings_unusable` entry to `metadata.warnings` (always present, empty or not). With it off, the raw FPL API 1-5 difficulty, and an explicitly passed `-m` reports on stderr that it does not apply. JSON `metadata` carries `custom_analysis`, `fdr_scale` (`team_ratings_1_7` / `fpl_api_1_5`) and `fdr_mode` (null when it does not apply) | Yes | General | No | direct-api |
 | `player` | Look up a player's stats, xG, ownership and fixture run. Before GW10 `quality_score` blends last season's pedigree in and JSON `metadata.warnings` says so (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded), same as `fpl stats --value`; `understat_team_unmatched` joins it for any club Understat carried no players for, whose whole squad loses xG enrichment. JSON includes `ep_next` (predicted pts next GW) and `ep_this` (current GW), emitting `null` when FPL has no projection; panel shows `xPts` (ep_next) when available, omits the segment when FPL has no projection. `--detail` (`-d`) shows GW-by-GW performance and, for FWD/MID with sufficient history, xGI sustainability (per-match GI-xGI divergence -> form modifier). With `custom_analysis`: JSON adds `info.adjusted_npxg_per_90` (fixture-adjusted) and `info.raw_npxg_per_90` (Understat season avg); panel shows `adj. npxG/90: X.XXX (raw: Y.YYY)`. Under a draft league (format not classic) the `Draft:` line says how the player came to stand where he does, from a replay of the league's draft, waivers and trades (issue #460): `Owned by Alice (round-3 pick)`, `Owned by Bob (GW4 waiver pickup; Cam's round-5 pick)`, `Available (released by Dan in GW5; Dan's round-9 pick)`, `Available (undrafted)`, round unknown where the draft's picks are lost, with a `Draft history:` line beneath when the chain has a step the line does not name; JSON keeps `info.draft_ownership` and adds `info.draft` (owner, acquisition, gameweek, drafter, round/pick, counterparty, full `history`), null with a `draft_provenance_unavailable` warning when the history cannot be shown complete | Yes | General | No | direct-api |
 | `stats` | List players with filtering and sorting. `--value` adds quality/value per £m columns; `--window N` sets rolling lookback (3-10) for `rolling_pts_per_m`. Before GW10, `--value` quality scores blend last season's pts/90 pedigree with this season's observation and the command says so (stderr notice quoting the observation's weight band; JSON `metadata.warnings` code `early_season_prior_informed`); when last season's history cannot be loaded they are pure observation and the notice says that instead (`early_season_small_sample`, before GW6). `understat_team_unmatched` is raised once per club Understat carried no players for, whose whole squad scores without xG. GK ceilings scale with the calendar-possible sample, reaching full scale at GW6. Sortable by `ep_next`/`ep_this` (FPL predicted points; `ep_this` is only meaningful before the gameweek's first kickoff — FPL rolls it forward to `ep_next` as each player's match finishes); both in JSON output (emit `null` when FPL has no projection; table renders `—`). Players with no projection sort to the bottom in either direction. Under a draft league (format not classic) the table adds a Draft column: the owner, tagged with how they came by him (`R3` round-3 pick, `GW4 W` waiver, `GW9 FA` free agent, `GW7 T` trade; issue #460), or `Available`; table only, JSON carries no draft column | Yes | General | No | direct-api |
@@ -55,7 +55,7 @@ see [Feed coverage warnings](../docs/command-reference.md#json-output).
 | `returnees` | Track injured and suspended players due back soon, so a returnee can be claimed in draft before they are fit or planned around in classic. Reads the FPL availability news, filters to returns inside a window (`--window N`, 1-38) and through a source-aware quality bar, and diffs against the stored watchlist for week-over-week changes. Most flagged players carry no parseable return date, so date-unknown entries are the norm rather than the exception; `--enrich` searches the web for fresher timing on those and on stale-news entries (needs a Perplexity key; skips with a note without one) and shows it beside the FPL news, never over it. `--all` bypasses the quality bar and deliberately does not persist the snapshot. JSON `metadata` carries `window`, `escalation_window`, `stash_upgrade_margin`, `transitions_available`, `transitions_baseline_gameweek` (the gameweek `transition` is measured against — every run in a gameweek diffs against the last state stored before it, so a repeat run reports the same changes), `quality_bar_available`, `quality_bar_applied` and `enrichment_requested`/`_available`/`_note`/`_count`/`_rate_limited` (true when the search provider rate-limited the run even after retrying — the one failure a re-run is likely to clear); `data` is `{entries, departures}`, each entry carrying `quality.basis`/`quality.meets_stash`, `expected_return`/`return_gameweek`/`return_source`, `escalation_eligible`/`escalation_basis`, `transition`, and `enrichment` (null unless enriched) | Yes | General | No | direct-api |
 | `preview` | Run full pre-gameweek analysis and generate report. `--save` writes to `<output dir>/<season>/gw{N}-preview.md`; `--scout` writes to `<research dir>/ai-scout-reports/<season>/gw{N}-scout-preview[-referenced].md` | No | General | No | via-agent |
 | `review` | Review a completed gameweek - squad performance and standings. `--save` writes to `<output dir>/<season>/gw{N}-review.md`; `--compare-recs` reads `gw{N}-recommendations.md` from the same season directory and grades the captain, each transfer and each waiver or free-agent move against it; transfer rows that sell the same player are read as ranked alternatives for one sale and graded once, as followed if any candidate was bought and as one miss otherwise; waiver rows that share a drop are read as one conditional chain, each claim keeping its own row: the move made is credited to the claim it filled wherever that claim sits in the chain, a claim below the one that landed is marked not needed rather than not executed, a claim skipped above one that was made is a miss, and a chain abandoned part-way is one miss where it was left, the claims below that marked as fallbacks not reached; the captain line sets the recommended captain against the armband in captain points (raw score times that week's multiplier, Triple Captain included), the armband being the vice's when the captain played no minutes, and adds the change to the team total when the recommended captain was in the side that scored; one who was not in the squad or played no minutes is labelled so rather than priced at 0; on a wildcard or free hit week, where the recommendation is a squad, each player brought in is graded against the recommended 15 instead, and a recommended name that fits more than one player is left ungraded with a warning on stderr rather than matched to the first; a part of the file it could not read (the captain, the transfers or the waivers) is left ungraded the same way, the warning naming the file, rather than grading every move unadvised, and a file nothing could be read from is not compared at all. Under `--summarise` the personal analysis is handed next gameweek's fixtures — every club's opponent and venue plus each squad player's positional FDR (1-7 team ratings with custom analysis on, the FPL API's 1-5 difficulty with it off, carrying the same scale footer and unrated-club caveat the FDR tables print, plus any warning that the ratings cannot support difficulty) — so its "Next Week" calls are grounded in fixtures rather than in one week of points; with no next gameweek to look at, that section is narrowed to fixture-independent observations and points at `fpl gw-prep`, and a gameweek already played is marked retrospective. The answer is then checked back against that block — a cited FDR the block never printed, or any fixture claim made without one — and against the sections its prompt asked for: an answer missing a `## ` heading, ending mid-sentence, or that the provider cut off at its token ceiling is retried once, told what the last draft lacked (a refused answer is flagged but never retried, and a retry that errors keeps the first attempt), and a still-incomplete one is warned about on stderr (detail in `data/debug/synthesis_corrections.txt` under `--debug`, where `synthesis_meta.json` also records how many answers were judged, which was kept, and the tokens they spent between them) and carries the same list as a callout in the saved report. The summary is an add-on the review does not depend on: the two provider roles resolve independently, and a role with no usable key is skipped with the reason on stderr (`Community narrative skipped: ...` / `Personal analysis skipped: ...`) while the review prints, saves and exits 0 — so one key produces that half rather than nothing, and a saved report names each skipped half in a warning callout of its own. A gameweek it cannot resolve - one still being played, an id the season does not have, a season with nothing finished yet - is refused with the specific reason on stderr and exit 1; stdout carries the review or nothing | No | General | No | via-agent |
-| `league-recap` | Recap a completed gameweek - awards, standings, and banter. Saves to `<output dir>/<season>/gw{N}-league-recap[-draft].md`, opening on a fixed `# Gameweek N Recap: <league name>` title the report writes itself, editorial or not; the editorial is asked for a `## ` headline beneath it and never a title, and whatever heading it opens with anyway is demoted to that level or, when it only restates the title, dropped, so the model's heading is never the document's (issue #349). Records every run into the league history ledger (`<data dir>/league_history/`) as a side effect, for draft alongside each held draft's picks (`drafts/draft-{id}.json` in the draft partition, saved once while the API still serves them, since a scheduled redraft drops them for good; `league_history_draft_picks_conflict`, `_lost` (once per draft), `_unsaved` and `_unchecked` name a disagreement with the API, a draft held before anything saved it, a run that could not save, and a `league.drafts` list it could not read), backfilling classic gaps at a coarse tier automatically; `--backfill-detail` rebuilds earlier gameweeks in full (one request per manager per gameweek). A rebuild keeps the name and position already recorded for each player instead of restamping them from today's bootstrap, and never drops a code the gameweek already resolved; it reads the earliest recorded row rather than the newest, so a gameweek an older version already restamped is repaired rather than re-copied. The club is not carried but *derived*, from the gameweek's own fixtures: FPL's live data records which fixtures each player's club played, so a double gameweek settles his club outright and a single narrows it to two, with one `element-summary` request spent only where today's club is absent from that pair (proof he has moved); today's club being one of the two is left unanswered rather than assumed, so a recorded club still wins there. That reaches the two cases a carry structurally cannot — a first capture and a coarse-to-detailed upgrade, neither of which has a recorded squad — and it supersedes a stale recorded club rather than preserving it, with `league_history_club_rederived` naming how many were replaced. A club that blanked has no fixture to intersect and falls back to the recorded club, then today's; name and position are not derivable from fixtures at all and stay carry-only. Everything the gameweek itself answers (points, cards, pick flags, blank status) is still re-derived, and a `league_history_identity_carried` warning names how many players were kept. A rebuild likewise never writes away a league position or cumulative total it cannot re-derive: draft has no per-manager history endpoint and its standings describe a later gameweek, so a replayed draft gameweek keeps the figures already recorded (`league_history_standings_carried`) instead of nulling them, which used to cost the ledger every position that gameweek held and collapse the streaks built on them. Where they were already lost, every run restores them from the ledger itself — the last superseded line that recorded them (a gameweek captured repeatedly while it was still settling holds a stale position in its first capture and the settled one in its last), or a cumulative total re-summed from earlier gameweeks — with no flag and no request (`league_history_standings_repaired`); a draft gameweek's table is derivable from `gross_points` alone at the league's start gameweek. A draft row also records the waiver claims its manager lost to a rival (`lost_claims`, kept apart from `transactions` because nothing moved — no points, no net, and never the denial that is the cascade of the manager's own accepted claim), so an outbid manager is not written into the permanent record as one who never tried; a gameweek captured before that field existed reads it back as unrecorded rather than as "lost none", is named by the coverage report, and is re-recorded by `--backfill-detail` while the league's transaction feed still serves it; a replay that finds fewer claims than the gameweek recorded keeps the recorded list (`league_history_claims_carried`). Those claims also make the waiver wire's races visible (issue #330): the editorial's waiver roster closes with every player more than one manager claimed, who won him and who was beaten to him at what priority, and a week where at least three managers claimed the same player (`MOST_CONTESTED_MIN_CLAIMANTS`) and one of them can be seen to have won him gets a Most Contested award beside Waiver Genius and Waiver Disaster — derived from the manager rows by `contested_draft_claims()`, never recorded, never a report section of its own, and absent from `--format json`, whose rows already carry the `lost_claims` and `transactions` they are regrouped from. The editorial is told to write each race as its own clause and never fold two into one ("respectively"), and is checked against the races afterwards (issue #357): a manager it names as beaten to, or winning, a contested player in a role that player's line does not give them triggers one regeneration told which claims were wrong (a retry that errors keeps the first attempt), and a kept editorial that still fails is saved as written with the wrong claims named on stderr, in a `synthesis_contested_misattribution` JSON warning, and in a callout above the editorial in the report. The same retry and reporting cover four checks on either format: a manager's net overall, pre-hit swing or another move's swing pinned on one named move (`synthesis_net_misattribution`, issue #359), a tie word ("joint-lowest", "tied for last", "joint-seventh") on a gameweek score or league position no two managers hold, or on the season's highest or lowest score where its season record was scored only once (`synthesis_unsupported_tie`, issues #359 and #494), a placing on the week the manager's gameweek score does not earn, said of the week ("third on the week") or set beside that score ("finished eighth on 31", a league position read as the week's finish) (`synthesis_wrong_gameweek_placing`, issue #486), and an escape from last place given to a manager who finished there ("He escaped the wooden spoon" of the week's lowest scorer, or "clear of the foot of the table" of the manager bottom of it) (`synthesis_escape_misattribution`, issue #488); and a fourth on draft (issue #390): the net overall, or the other kind's figure, said of one kind of a manager's moves ("his waiver moves netted +3 overall" of a -1 waiver and a +4 free-agent pickup, `synthesis_kind_net_misattribution`), for which a roster line that mixes kinds now gives each kind's net beside the net overall. A fifth, on draft (issue #459), holds the editorial to not reciting a race as a list: a paragraph naming the race's player and three or more of its beaten managers (`synthesis_contested_roll_call`) earns the same retry and reporting, but as a broken brief rather than a contradiction of the data, since the sentence is true, so the retry, stderr and the report callout say that instead. The prompt's GW Standings section names the week's highest and lowest scores, every shared score and position (Pos, and Prev where any is shared) and any season totals the league's tie-break placed apart, so "joint" has a line to be held to, and the roster lines call the manager's net "overall". Biggest Bench Haul (both formats) ranks on the best legal XI's gain over the XI that counted — one keeper, the eight legal formations, the doubled player held in place — never on the bench's raw sum, which counted a keeper who could not have played and outfielders no formation had room for (issue #350); its detail names the swap, a manager with bench points but no better XI is no candidate, and the raw sum stays on the row as `bench_points` (the API's `points_on_bench`) because the coarse tier can record nothing else. Coverage gaps and capture warnings go to stderr; the command exits 0 even when the store is unreadable. A `--save` whose report cannot be written exits 1 with `Failed to save report: <reason>` on stderr; under `--format json` that is the `{command, error}` envelope, with the codes of any capture warnings named in the message and any editorial printed on stderr first (issue #474). `--format json` emits one row per manager (the captured ledger row shape) plus `metadata.coverage`, `season_phase`, `notes_pack`, `synthesis_summary`, `synthesis_attempts` (answers judged: 1, or 2 after a retry), `synthesis_shipped_attempt` (which of them shipped) and `synthesis_usage` (input and output tokens summed over every answer judged; all three `null` when no editorial came back), `warnings` (always present, each entry a stable `code` plus rewritable `message` - codes listed in [Command Reference](../docs/command-reference.md#league-history)) `first_capture_store_path` (always present; the partition directory on a first capture, `null` after) and `draft_picks_saved` (always present; the draft-picks snapshots this run wrote, empty on classic). Fines are ruled *and recorded* against every captured gameweek, backfilled ones included: the detailed replay rules every configured rule, the coarse tier rules only what cohort points support (`last-place`, `below-threshold`) and records that `red-card` went unruled. `last-place` is ruled against every manager level on the gameweek's lowest score rather than whichever of them the cohort's arrival order reached first; because rulings are frozen at capture and the ledger is append-only, gameweeks recorded before that was true are swept on every run and the recorded ruling appended against the managers they left out, with no flag and no request (`league_history_tied_last_place_repaired`) — and where the row data cannot settle who was level, since the gameweek does not record whether it was ruled on gross or net points, the manager is named by `league_history_tied_last_place_ambiguous` rather than fined on a guess. Season totals print under `Season Fines` on console and as a `# Season Fines` report section, but only at the two milestone gameweeks (GW19 and the finale) - every other week those surfaces stay a this-week view and `league-fines` answers the season question on demand. The `## Season Fines` prompt section and `metadata.season_fines` are ungated: the editorial gets the running totals every week as optional colour (never a required beat), and a scripted consumer sees no calendar-driven appearance and disappearance. Bottom-half gameweeks and green-arrow droughts no longer surface as streaks at all (their run only drives the season count). Streak conditions also keep reset-surviving season occurrence counts ("their sixth gameweek win of the season"), each surfaced on its own rule (see [Command Reference](../docs/command-reference.md#league-recap) for the per-count table): wins and last places on multiples of 3 plus any second-half first, captain blanks and waiver hauls/backfires on multiples of 5, hits on multiples of 3, weeks on top on multiples of 5, bottom-half gameweeks on multiples of 10 in the second half only, and green-arrow droughts on an unbroken run of 5 or 10 (gameweeks spent leading the league never count towards a drought — the leader could not have climbed). Some counts carry same-week peers alongside the milestone — past a fixed floor for counts that stay small, or within a relative window for counts that climb all season. A firing count reaches the report's `## Season Counts` subsection and the editorial's League History section; at the two milestone gameweeks both surfaces carry every nonzero count as the season set-piece. Every line states its span and any not-judged gameweeks beside the number, and every nonzero count is emitted in `metadata.notes_pack.season_count_entries` regardless. The editorial's League History section also states the league's highest and lowest gameweek score this season with who scored each and when, counted as the standings count the week (gross, or net under `use_net_points`) and qualified by any gameweek not every score of which was recorded, and the system prompt allows a season superlative ("the week of the season") only where that line names it (issue #494); prompt-only, absent on the league's first gameweek, and in `metadata.notes_pack.season_record_entries` with `points` and `holders`. A recap of the most recently finished gameweek keeps working once the next gameweek has started: the league table describes that later gameweek from its deadline onward, so the run takes the replay path (figures from each manager's own gameweek history, positions and cumulative totals derived rather than read off the table) and raises a `league_standings_moved_on` warning, instead of reconciling two different gameweeks' numbers against each other and exiting 1 with the ledger row unwritten. `--summarise` with no usable synthesis key no longer aborts the run: the recap, report and ledger capture all proceed, and a `synthesis_provider_unavailable` warning says the editorial was skipped; an editorial the provider cut off at its token ceiling is regenerated once, told it was cut off (a refused editorial is never regenerated, even with a wrong claim in it), and one the provider stopped early on that is still the one kept is written out as it stands with the reason on stderr, a `synthesis_stopped_early` warning in JSON, and a line in the report's warning callout above the editorial (issue #372). A gameweek that cannot be resolved at all exits 1 in both output formats - it used to exit 1 under `--format json` with a generic `"Could not resolve a gameweek to recap."` and 0 in table mode - and the resolver's own reason (`Gameweek 7 is not yet finished`) now reaches the error envelope and the stderr prose alike. On the league's opening gameweek only (GW1, or its own `start_event`), each classic manager's FPL-wide prior-season record — seasons played, last season's points/rank/top-% finish, best season — is fetched from the manager-history endpoint (one request per manager, that gameweek only, and only with `--save`/`--output` or `--summarise`; a league created after GW1 shares the fetch with its league-start offset) and rendered as a `# Prior Seasons` report section and a locked `## Prior Seasons` prompt section with an explicit count; tenure is phrased FPL-wide because entry and league IDs are reissued each season, and a manager with no record or a failed fetch is named as such rather than omitted. Nothing of it reaches the ledger or the JSON rows; draft has no such endpoint and no such section. Every recap, classic and draft, also carries a Standout Players section (issue #455), read off the squads and live points the bench haul already uses: the week's top scorers in any manager's squad and its costliest blanks (2 points or fewer; in classic the one that counted for the most managers first, in draft the best by FPL's pre-season draft rank and, on a live recap from GW19, by season points per game, since the rank is never updated; a draft player neither can rank is left off, and no line states the rank or average, which only the heading and JSON carry), each with the managers he counted for, how long a blank played when it was under the hour, and any who left him on the bench, as one sentence per player that the console and, with `--summarise`, a `## Standout Players` prompt section print, never the saved report, where the editorial already tells the same week in prose (issue #482); `--format json` carries it as `metadata.standout_players`, every player row with the main game's `id` (under `--draft` too) and `code` beside it. A draft recap's lines also say how each player came to the manager they name (issue #458): the draft pick, the waiver or free-agent move, or the trade, the latest as of the recapped gameweek (a `-g` replay shows its own week), from a replay of the league's draft, accepted transactions and processed trades that must end where FPL's own ownership list does and match the week's squads, with the draft's picks read from the choices feed or, once it serves another draft, the saved snapshot, or, where neither has them, who drafted whom rebuilt from each manager's squad at the draft's gameweek with the earlier moves undone (the line then says "who drafted him" with no round, `round_unknown` in the JSON, and a `draft_rounds_unknown` notice replaces the warning). If the history cannot be shown complete (or a read fails, a failed trades read included once a trade has happened) the lines read without it and a `draft_provenance_unavailable` warning says why; draft rows carry `acquisition` in the JSON, classic rows do not. Before a live capture collects, it reads the recapped game's processing feed (`event-status/` on `FPLClient`, `pl/event-status` on `FPLDraftClient`, both `get_gameweek_status()`): when the feed's match days for the recapped gameweek show bonus unconfirmed or the league tables still "Updating" (`GameweekStatus.still_processing()`), it warns on stderr, in a `league_tables_updating` JSON warning and in a callout at the top of a saved report that positions and totals may be stale, and records the gameweek anyway, since a later run supersedes it and a missed draft gameweek cannot be recaptured; a reconciliation failure in that window keeps its own diagnosis and adds that it may be timing. Only a definite signal warns: an unreadable, slow (5s), reshaped or unrecognised feed is a debug log, and a replay never reads it (issue #424) | Yes | General | No | via-agent |
+| `league-recap` | Recap a completed gameweek - awards, standings, and banter. Saves to `<output dir>/<season>/gw{N}-league-recap[-draft].md`, opening on a fixed `# Gameweek N Recap: <league name>` title the report writes itself, editorial or not; the editorial is asked for a `## ` headline beneath it and never a title, and whatever heading it opens with anyway is demoted to that level or, when it only restates the title, dropped, so the model's heading is never the document's (issue #349). Records every run into the league history ledger (`<data dir>/league_history/`) as a side effect, for draft alongside each held draft's picks (`drafts/draft-{id}.json` in the draft partition, saved once while the API still serves them, since a scheduled redraft drops them for good; `league_history_draft_picks_conflict`, `_lost` (once per draft), `_unsaved` and `_unchecked` name a disagreement with the API, a draft held before anything saved it, a run that could not save, and a `league.drafts` list it could not read), backfilling classic gaps at a coarse tier automatically; `--backfill-detail` rebuilds earlier gameweeks in full (one request per manager per gameweek). A rebuild keeps the name and position already recorded for each player instead of restamping them from today's bootstrap, and never drops a code the gameweek already resolved; it reads the earliest recorded row rather than the newest, so a gameweek an older version already restamped is repaired rather than re-copied. The club is not carried but *derived*, from the gameweek's own fixtures: FPL's live data records which fixtures each player's club played, so a double gameweek settles his club outright and a single narrows it to two, with one `element-summary` request spent only where today's club is absent from that pair (proof he has moved); today's club being one of the two is left unanswered rather than assumed, so a recorded club still wins there. That reaches the two cases a carry structurally cannot — a first capture and a coarse-to-detailed upgrade, neither of which has a recorded squad — and it supersedes a stale recorded club rather than preserving it, with `league_history_club_rederived` naming how many were replaced. A club that blanked has no fixture to intersect and falls back to the recorded club, then today's; name and position are not derivable from fixtures at all and stay carry-only. Everything the gameweek itself answers (points, cards, pick flags, blank status) is still re-derived, and a `league_history_identity_carried` warning names how many players were kept. A rebuild likewise never writes away a league position or cumulative total it cannot re-derive: draft has no per-manager history endpoint and its standings describe a later gameweek, so a replayed draft gameweek keeps the figures already recorded (`league_history_standings_carried`) instead of nulling them, which used to cost the ledger every position that gameweek held and collapse the streaks built on them. Where they were already lost, every run restores them from the ledger itself — the last superseded line that recorded them (a gameweek captured repeatedly while it was still settling holds a stale position in its first capture and the settled one in its last), or a cumulative total re-summed from earlier gameweeks — with no flag and no request (`league_history_standings_repaired`); a draft gameweek's table is derivable from `gross_points` alone at the league's start gameweek. A draft row also records the waiver claims its manager lost to a rival (`lost_claims`, kept apart from `transactions` because nothing moved — no points, no net, and never the denial that is the cascade of the manager's own accepted claim), so an outbid manager is not written into the permanent record as one who never tried; a gameweek captured before that field existed reads it back as unrecorded rather than as "lost none", is named by the coverage report, and is re-recorded by `--backfill-detail` while the league's transaction feed still serves it; a replay that finds fewer claims than the gameweek recorded keeps the recorded list (`league_history_claims_carried`). Those claims also make the waiver wire's races visible (issue #330): the editorial's waiver roster closes with every player more than one manager claimed, who won him and who was beaten to him at what priority, and a week where at least three managers claimed the same player (`MOST_CONTESTED_MIN_CLAIMANTS`) and one of them can be seen to have won him gets a Most Contested award beside Waiver Genius and Waiver Disaster — derived from the manager rows by `contested_draft_claims()`, never recorded, never a report section of its own, and absent from `--format json`, whose rows already carry the `lost_claims` and `transactions` they are regrouped from. The editorial is told to write each race as its own clause and never fold two into one ("respectively"), and is checked against the races afterwards (issue #357): a manager it names as beaten to, or winning, a contested player in a role that player's line does not give them triggers one regeneration told which claims were wrong (a retry that errors keeps the first attempt), and a kept editorial that still fails is saved as written with the wrong claims named on stderr, in a `synthesis_contested_misattribution` JSON warning, and in a callout above the editorial in the report. The same retry and reporting cover five checks on either format: a manager's net overall, pre-hit swing or another move's swing pinned on one named move (`synthesis_net_misattribution`, issue #359), a tie word ("joint-lowest", "tied for last", "joint-seventh") on a gameweek score or league position no two managers hold, or on the season's highest or lowest score where its season record was scored only once, a place in a milestone's highs or lows table nobody shares, or a manager's own season best or worst nobody equalled this gameweek (`synthesis_unsupported_tie`, issues #359, #494 and #496), one of this gameweek's scores given the league's best or worst of the season where the season-record line names another ("a new season low of 30", "the week of the season: 65 points"), unless a manager owns it ("his own season low") (`synthesis_unsupported_season_record`, issue #496), a placing on the week the manager's gameweek score does not earn, said of the week ("third on the week") or set beside that score ("finished eighth on 31", a league position read as the week's finish) (`synthesis_wrong_gameweek_placing`, issue #486), and an escape from last place given to a manager who finished there ("He escaped the wooden spoon" of the week's lowest scorer, or "clear of the foot of the table" of the manager bottom of it) (`synthesis_escape_misattribution`, issue #488); and a fourth on draft (issue #390): the net overall, or the other kind's figure, said of one kind of a manager's moves ("his waiver claims netted +3 overall" of a -1 waiver and a +4 free-agent pickup, `synthesis_kind_net_misattribution`; a generic waiver word such as "his waiver work" may mean all of a manager's moves, as the waiver awards are, and may carry the net overall, issue #539), for which a roster line that mixes kinds now gives each kind's net beside the net overall. A fifth, on draft (issue #459), holds the editorial to not reciting a race as a list: a paragraph naming the race's player and three or more of its beaten managers (`synthesis_contested_roll_call`) earns the same retry and reporting, but as a broken brief rather than a contradiction of the data, since the sentence is true, so the retry, stderr and the report callout say that instead; so does a fine's forfeit written out word for word more than once (`synthesis_penalty_repeated`, issue #503), which the prompt allows once, headline included, every other mention in other words or, where the `fines:` block or a rule sets `penalty_phrasings`, only those (a bare "the forfeit" counts, a short aside alluding to it may be in the model's own words, and only the headline may pun on it in its own words, never into more of it or a different act), while the Fines list and the ledger keep the configured `penalty`; and so does the brief's own wording read out to the league (`synthesis_brief_echoed`, issue #517): a prompt section named as a section, "exact phrase", "at most once", "official wording" or the "Naming the forfeit" label; and so does a false claim about who was fined this gameweek (`synthesis_fine_claim_contradicted`, issue #516): a manager called the only one without a fine where the Fines section's not-fined list holds more than them (or the only one on the week's highest or lowest score while another on it went unfined), or "a double fine", "fined twice" or "two fines" for a manager with other than two fine lines. The prompt's GW Standings section names the week's highest and lowest scores, every shared score and position (Pos, and Prev where any is shared) and any season totals the league's tie-break placed apart, so "joint" has a line to be held to, and the roster lines call the manager's net "overall". Biggest Bench Haul (both formats) ranks on the best legal XI's gain over the XI that counted — one keeper, the eight legal formations, the doubled player held in place — never on the bench's raw sum, which counted a keeper who could not have played and outfielders no formation had room for (issue #350); its detail names the swap, a manager with bench points but no better XI is no candidate, and the raw sum stays on the row as `bench_points` (the API's `points_on_bench`) because the coarse tier can record nothing else. Coverage gaps and capture warnings go to stderr; the command exits 0 even when the store is unreadable. A `--save` whose report cannot be written exits 1 with `Failed to save report: <reason>` on stderr; under `--format json` that is the `{command, error}` envelope, with the codes of any capture warnings named in the message and any editorial printed on stderr first (issue #474). `--format json` emits one row per manager (the captured ledger row shape) plus `metadata.coverage`, `season_phase`, `notes_pack`, `synthesis_summary`, `synthesis_attempts` (answers judged: 1, or 2 after a retry), `synthesis_shipped_attempt` (which of them shipped) and `synthesis_usage` (input and output tokens summed over every answer judged; all three `null` when no editorial came back), `warnings` (always present, each entry a stable `code` plus rewritable `message` - codes listed in [Command Reference](../docs/command-reference.md#league-history)) `first_capture_store_path` (always present; the partition directory on a first capture, `null` after) and `draft_picks_saved` (always present; the draft-picks snapshots this run wrote, empty on classic). Fines are ruled *and recorded* against every captured gameweek, backfilled ones included: the detailed replay rules every configured rule, the coarse tier rules only what cohort points support (`last-place`, `below-threshold`) and records that `red-card` went unruled. `last-place` is ruled against every manager level on the gameweek's lowest score rather than whichever of them the cohort's arrival order reached first; because rulings are frozen at capture and the ledger is append-only, gameweeks recorded before that was true are swept on every run and the recorded ruling appended against the managers they left out, with no flag and no request (`league_history_tied_last_place_repaired`) — and where the row data cannot settle who was level, since the gameweek does not record whether it was ruled on gross or net points, the manager is named by `league_history_tied_last_place_ambiguous` rather than fined on a guess. Season totals print under `Season Fines` on console and as a `# Season Fines` report section, but only at the two milestone gameweeks (GW19 and the finale) - every other week those surfaces stay a this-week view and `league-fines` answers the season question on demand. The `## Season Fines` prompt section and `metadata.season_fines` are ungated: the editorial gets the running totals every week as optional colour (never a required beat), and a scripted consumer sees no calendar-driven appearance and disappearance. Bottom-half gameweeks and green-arrow droughts no longer surface as streaks at all (their run only drives the season count). Streak conditions also keep reset-surviving season occurrence counts ("their sixth gameweek win of the season"), each surfaced on its own rule (see [Command Reference](../docs/command-reference.md#league-recap) for the per-count table): wins and last places on multiples of 3 plus any second-half first, captain blanks and waiver hauls/backfires on multiples of 5, hits on multiples of 3, weeks on top on multiples of 5, bottom-half gameweeks on multiples of 10 in the second half only, and green-arrow droughts on an unbroken run of 5 or 10 (gameweeks spent leading the league never count towards a drought — the leader could not have climbed). Some counts carry same-week peers alongside the milestone — past a fixed floor for counts that stay small, or within a relative window for counts that climb all season. A firing count reaches the report's `## Season Counts` subsection and the editorial's League History section; at the two milestone gameweeks both surfaces carry every nonzero count as the season set-piece. Every line states its span and any not-judged gameweeks beside the number, and every nonzero count is emitted in `metadata.notes_pack.season_count_entries` regardless. The editorial's League History section also states the league's highest and lowest gameweek score this season with who scored each and when, counted as the standings count the week (gross, or net under `use_net_points`) and qualified by any gameweek not every score of which was recorded, and the system prompt allows a season superlative ("the week of the season") only where that line names it (issue #494); prompt-only, absent on the league's first gameweek, and in `metadata.notes_pack.season_record_entries` with `points` and `holders`. It also states a manager's own highest or lowest gameweek score this season when this gameweek set or equalled it, beside the record before it ("above their previous highest of 61 in GW9"), once the manager has ten recorded gameweeks of their own behind it; the system prompt allows "their best week of the season" only where such a line says so (issue #496). Prompt-only too, and in `metadata.notes_pack.personal_record_entries` for every manager every week, with `points`, `holders`, `previous_points` and `previous_holders`. At GW19 and the finale the report's League History section adds Season Highs and Lows, two tables ranking every manager's own highest gameweek score highest first and lowest worst first, places shared on a tie, which the editorial also gets, in `metadata.notes_pack.personal_record_tables`. A recap of the most recently finished gameweek keeps working once the next gameweek has started: the league table describes that later gameweek from its deadline onward, so the run takes the replay path (figures from each manager's own gameweek history, positions and cumulative totals derived rather than read off the table) and raises a `league_standings_moved_on` warning, instead of reconciling two different gameweeks' numbers against each other and exiting 1 with the ledger row unwritten. `--summarise` with no usable synthesis key no longer aborts the run: the recap, report and ledger capture all proceed, and a `synthesis_provider_unavailable` warning says the editorial was skipped; an editorial the provider cut off at its token ceiling is regenerated once, told it was cut off (a refused editorial is never regenerated, even with a wrong claim in it), and one the provider stopped early on that is still the one kept is written out as it stands with the reason on stderr, a `synthesis_stopped_early` warning in JSON, and a line in the report's warning callout above the editorial (issue #372). A gameweek that cannot be resolved at all exits 1 in both output formats - it used to exit 1 under `--format json` with a generic `"Could not resolve a gameweek to recap."` and 0 in table mode - and the resolver's own reason (`Gameweek 7 is not yet finished`) now reaches the error envelope and the stderr prose alike. On the league's opening gameweek only (GW1, or its own `start_event`), each classic manager's FPL-wide prior-season record — seasons played, last season's points/rank/top-% finish, best season — is fetched from the manager-history endpoint (one request per manager, that gameweek only, and only with `--save`/`--output` or `--summarise`; a league created after GW1 shares the fetch with its league-start offset) and rendered as a `# Prior Seasons` report section and a locked `## Prior Seasons` prompt section with an explicit count; tenure is phrased FPL-wide because entry and league IDs are reissued each season, and a manager with no record or a failed fetch is named as such rather than omitted. Nothing of it reaches the ledger or the JSON rows; draft has no such endpoint and no such section. Every recap, classic and draft, also carries a Standout Players section (issue #455), read off the squads and live points the bench haul already uses: the week's top scorers in any manager's squad and its costliest blanks (2 points or fewer; in classic the one that counted for the most managers first, in draft the best by FPL's pre-season draft rank and, on a live recap from GW19, by season points per game, since the rank is never updated; a draft player neither can rank is left off, and no line states the rank or average, which only the heading and JSON carry), each with the managers he counted for, how long a blank played when it was under the hour, and any who left him on the bench, as one sentence per player that the console and, with `--summarise`, a `## Standout Players` prompt section print, never the saved report, where the editorial already tells the same week in prose (issue #482); `--format json` carries it as `metadata.standout_players`, every player row with the main game's `id` (under `--draft` too) and `code` beside it. A draft recap's lines also say how each player came to the manager they name (issue #458): the draft pick, the waiver or free-agent move, or the trade, the latest as of the recapped gameweek (a `-g` replay shows its own week), from a replay of the league's draft, accepted transactions and processed trades that must end where FPL's own ownership list does and match the week's squads, with the draft's picks read from the choices feed or, once it serves another draft, the saved snapshot, or, where neither has them, who drafted whom rebuilt from each manager's squad at the draft's gameweek with the earlier moves undone (the line then says "who drafted him" with no round, `round_unknown` in the JSON, and a `draft_rounds_unknown` notice replaces the warning). If the history cannot be shown complete (or a read fails, a failed trades read included once a trade has happened) the lines read without it and a `draft_provenance_unavailable` warning says why; draft rows carry `acquisition` in the JSON, classic rows do not. On the gameweek that closes one of FPL's months (bootstrap `phases`, read by `FPLClient.get_months()`; a draft league uses the main game's), the recap adds Manager of the Month (the month's top scorer, named with the rest of the top three) and Dud of the Month (its lowest) to the console, the report's Awards and, with `--summarise`, the editorial's, summed from the ledger the way FPL's own month table sums it (net of hits, except a hit for the month's first gameweek, which FPL never charges), ties shared, and both withheld with the reason when any manager in the month's table lacks a score (or, on classic, a hit) for one of its gameweeks, or when the recap reads only part of the league (classic standings past one page); derived every run, never stored (issue #425). The halfway (GW19) and final (GW38) recaps list each completed month's awards under `Monthly Honours` on console and as a `# Monthly Honours` report section, the printed season fines table's rhythm; the editorial gets the same list on those two recaps and on every month's last gameweek, and `metadata.monthly_honours` carries it every week. The month a classic recap closes is cross-checked against FPL's own month table (`?phase=N`) before either award is placed, a disagreement withholding both everywhere and raising `league_month_table_disagrees`; the editorial's tie check reads a month tie against that month's own table; months the bootstrap does not list readably skip both with `league_months_unavailable`. A draft league that sets a `player-of-the-month` entry under `fines.draft_vouchers` also gets the Premier League's Player of the Month (issue #492), read from the Premier League's own awards feed (`PremierLeagueClient`, whose player id is FPL's `code`) and announced once, by the first recap of the latest finished gameweek after the award is out (so a skipped recap still gets it, and a replay of an older gameweek never claims it or asks the feed; the announcing recap writes a record under the draft partition's `awards/`): an Awards line naming who held him for the month's last gameweek, bench included, read off the ledger's squads every run (with who held him when, where he changed hands), and a Fines section line saying that manager may hand out one fine, the voucher's `penalty`, to anyone they choose. A grant, never a ruling, so `league-fines` never counts it. Nobody holding him at the month's end means no voucher, said so; a month-end gameweek that cannot say (a missing or unknown row, an unidentified pick, a league read in part) withholds it with the reason, and the first latest-gameweek recap that can say settles it, once; an unreadable or reshaped feed, or a winner whose code FPL does not know, is "not checked" with `player_of_the_month_unchecked`, never "no award"; the voucher's `overrides` (month to code) win over the feed. `metadata.player_of_the_month` carries every completed month's winner (`player` with `code`, no `id`), owner, holders and announcement gameweek every week; classic never shows it. Before a live capture collects, it reads the recapped game's processing feed (`event-status/` on `FPLClient`, `pl/event-status` on `FPLDraftClient`, both `get_gameweek_status()`): when the feed's match days for the recapped gameweek show bonus unconfirmed or the league tables still "Updating" (`GameweekStatus.still_processing()`), it warns on stderr, in a `league_tables_updating` JSON warning and in a callout at the top of a saved report that positions and totals may be stale, and records the gameweek anyway, since a later run supersedes it and a missed draft gameweek cannot be recaptured; a reconciliation failure in that window keeps its own diagnosis and adds that it may be timing. Only a definite signal warns: an unreadable, slow (5s), reshaped or unrecognised feed is a debug log, and a replay never reads it (issue #424) | Yes | General | No | via-agent |
 | `league-fines` | Show who has been fined this season and how much of it was actually ruled, folded out of the league history ledger. Reads local files only - no network - so it works for any season still on disk (`--season 2025-26`). Nothing is re-ruled: a fine is counted exactly as its gameweek recorded it — including one `league-recap` appended against a manager who tied for last and was left out at capture. Counts, never money (`penalty` is free text; settlement and escalation are not modelled). Every gameweek that could not be ruled is named beneath the table - never captured, unreadable, captured before rulings were recorded, captured with no rules configured, or captured at a fidelity that could not rule a given rule. `--format json` emits one entry per recorded manager, fined or not, each with `counts` (zero included), `total`, `fined_gameweeks`, `ruled_gameweeks`, `unruled_gameweeks`, `first_recorded_gameweek`, `last_recorded_gameweek` and `is_fully_ruled`; `metadata` carries `season`, `fpl_format`, `league_id`, `gameweek`, `start_gameweek`, `rule_types`, `total_fines` and `qualifiers`. Exits 1 with the shared error envelope when no league id is configured for the format | Yes | General | No | direct-api |
 | `captain` | Analyse and rank captain options for next gameweek. Your squad is the default, so an absent `classic_entry_id` exits 1 with an `error` envelope naming `--global` rather than returning the global list as though it were your options; `metadata.my_squad_mode` says which list the payload holds, and `metadata.warnings` carries `captain_global_fallback` when there is no squad to rank yet (before the first deadline) or `captain_no_next_gameweek` when there is no next gameweek at all (finished season, or the next one unpublished). An entry ID that does not resolve is a failure, not a fallback, worded exactly as `squad` words it (`get_own_squad_picks`, `agents/common.py`). JSON candidates include `adjusted_npxg_per_90` and `raw_npxg_per_90` when fixture adjustment is active. Consistency tiebreaker (CV-xGI percentile) phased in GW6-10. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the GW1-9 shrinkage rather than pulled toward the position mean | Yes | Classic | Yes | via-agent |
 | `differentials` | Find differential picks - high potential, low ownership. Inverted consistency bonus (volatile players score higher, phased in GW6-10). Before GW10 the score's quality baseline carries the prior blend (last season's pedigree weighted by confidence) rather than position-mean shrinkage, so a quiet-starting elite is not ranked below a one-game wonder; the ownership, matchup and consistency bonuses stay pure observation; JSON `metadata.warnings` carries the early-season notice while the blend is live (`early_season_prior_informed`, or `early_season_small_sample` when history could not be loaded) plus `understat_team_unmatched` for any club Understat carried no players for, table mode prints them to stderr. Players ruled out of the gameweek (0% chance, or no minutes from GW6) are held out of the blend rather than handed last season's standing. The gameweek stamped into JSON `metadata` is fetched after the agent succeeds, not before it runs, so an unreachable API is reported as the agent's failure in both output formats rather than as a client error under `--format json` and an agent error in table mode | Yes | Classic | Yes | via-agent |
@@ -105,6 +105,7 @@ Skills write their own outputs (`gw{N}-recommendations.md`, `gw{N}-squad-builder
 | release | `skills/release/` | Cut a release end-to-end: preflight, notes via release-notes, approval gate, publish GitHub release (tag drives PyPI publish + changelog automation) | Full: Claude Code (local), Codex, Cursor, Copilot. Partial: Claude Code web (publish step handed to user) |
 | create-pr | `skills/create-pr/` | Open a PR for the current branch: conventional-commit title (the changelog line) + why-first prose body in the fpl-cli PR description style | Full: Claude Code, Codex, Cursor, Copilot |
 | build-test-plan | `skills/build-test-plan/` | Build a runnable test plan for the user-facing changes shipped between two releases, written for a live-data session in the fpl-workspace vault (deep per-change research, carries forward the previous plan's BLOCKED/FAIL items) | Full: Claude Code (parallel research sub-agents). Partial: Codex, Cursor, Copilot |
+| ab-brief | `skills/ab-brief/` | Write the brief a fresh fpl-workspace session runs to A/B a reviewed league-recap prompt or check change (gate on review, classify fresh runs vs corpus replay, pin both arms' SHAs, per-shape expectations), subscribe to the PR, and act on the `ab-handback` review the vault session posts back | Full: Claude Code (PR subscription wakes the session). Partial: Codex, Cursor, Copilot (no subscription) |
 
 ## Analysis Agents
 

fplkit-2.11.0/.agents/skills/ab-brief/SKILL.md

@@ -0,0 +1,401 @@
+---
+name: ab-brief
+description: >
+  Write the brief a fresh fpl-workspace (vault) session runs to A/B a
+  league-recap prompt or editorial-check change, once its fpl-cli PR has
+  been through code review, and act on the handback review that session
+  posts on the PR. Use when the user says "A/B brief", "prompt for a vault
+  session", "give me a prompt for a fresh vault session to A/B this", or
+  "write the brief for the A/B"; as the step the create-pr skill names
+  after review for a PR touching fpl_cli/prompts/ or a data section the
+  model is shown; and when a review carrying the ab-handback marker lands
+  on the PR.
+model: opus
+compatibility:
+  claude-code: full (GitHub MCP on the web, gh locally; subscribe_pr_activity for the wake-up)
+  codex: partial (no PR subscription, so the user says when the handback is posted)
+  cursor: partial (no PR subscription)
+  copilot: partial (no PR subscription)
+---
+
+<!-- Runs in the fpl-cli repo; its brief runs in a fresh fpl-workspace session. -->
+
+# A/B Brief
+
+Hand a league-recap A/B to a dedicated vault session, and close the loop
+when its results come back.
+
+A change to a prompt, a data section the model is shown, or an editorial
+check is verified by the vault's harness (`.claude/scripts/recap_ab/` in
+fpl-workspace) before it merges: CLAUDE.md's prompt-change rule. The work
+splits across two sessions, and this skill is the seam between them:
+
+- **The fpl-cli session owns the code.** It writes the change, takes it
+  through code review, runs this skill, and makes every fix the round
+  turns up.
+- **The vault session owns the test.** It has the FPL credentials, LLM
+  keys, real leagues and the drafts corpus, and it never changes fpl-cli.
+
+The forward leg is copy and paste: this skill prints a brief, the user
+pastes it into a fresh vault session. The return leg is a PR review: the
+vault session posts one comment-only review on the fpl-cli PR, which wakes
+this session because Step 6 subscribed it to the PR first.
+
+**This session never runs the A/B or the replay, not even "just to
+check".** Twice in October an fpl-cli session did the vault's work itself,
+once three whole rounds and once a corpus replay the user had to stop.
+That overlap is what the split exists to end: two sessions testing one PR
+produce two sets of numbers and no owner for either.
+
+Everything here is written for a public repo. The skill, the PR, its
+commits and the handback carry no manager names, entry IDs, manager_keys
+or league IDs; examples use Manager A, Manager B. The brief itself goes to
+a private session, but write it to the same standard so a pasted fragment
+can never leak.
+
+## Step 1: The gate
+
+Refuse to write a brief, and say exactly what is missing, unless all three
+hold. A brief written early pins a SHA the review is about to move, and
+the vault session then spends a round on code nobody will ship.
+
+1. **The branch has an open PR.** `gh pr view --json number,state,headRefOid`
+   locally, or the GitHub MCP `list_pull_requests` with
+   `head: rossgroomio:<branch>` on the web.
+2. **A code review has been posted, and every thread on it is resolved or
+   replied to.** Read the threads (`pull_request_read` with
+   `get_review_comments`, or `gh api graphql`). An unresolved thread whose
+   last comment is a reply counts as answered. A thread deliberately left
+   open as the A/B merge gate is fine: name it, because Step 5 resolves it
+   when the gate clears. A review carrying the ab-handback marker is an
+   earlier round's result, not a code review, and does not satisfy this.
+3. **The head you will pin includes the review fixes.** Each fix reply
+   names a commit; check every one is in the head
+   (`git merge-base --is-ancestor <fix sha> <head sha>`). A reply saying
+   "pushing next" with no such commit on the branch means the fix is not
+   there yet.
+
+Report the CI state on that head (`get_check_runs`, or `gh pr checks`) but
+do not block on it. Briefs in October went out with CI still running and
+it never mattered: the round takes longer than CI, and a red CI is a code
+problem this session fixes on its own clock.
+
+## Step 2: Classify the change
+
+From the diff against the merge-base (Step 3), say which test the change
+needs:
+
+- **Fresh model runs** when what the model is shown, or the model itself,
+  changes: either prompt (`fpl_cli/prompts/league_recap.py`'s system or
+  user prompt), a data section the model is shown (what a
+  `format_recap_*` function emits, or the recap data keys it reads, often
+  set in `fpl_cli/cli/_league_recap_data.py` or `league_recap.py`), the
+  synthesis model or its settings (`llm.synthesis` in
+  `fpl_cli/config/defaults.yaml`, `fpl_cli/api/providers/`), or the retry
+  loop (`fpl_cli/cli/_synthesis_retry.py`).
+- **A replay of the saved drafts corpus** when the editorial checks change
+  (`fpl_cli/prompts/league_recap_checks.py`). Never model runs for a check
+  change alone: the corpus already holds the drafts, and a replay judges
+  them in seconds where fresh runs cost an hour and add noise.
+- **Both** when it does both.
+
+Name every check whose `retry_instruction` changed or is new. A replay
+shows which drafts would now retry, never how the model reads the new
+wording; only fresh runs show that, so a new or reworded retry tips a
+check-only change towards fresh runs too.
+
+This is an expectation, not the verdict. The vault's `triage.sh` dry-runs
+both builds and is authoritative; the brief states what you expect and
+tells the vault session to stop if triage says otherwise. A disagreement
+is itself a finding: either the diff does something its author did not
+see, or the classification above has a gap.
+
+## Step 3: Gather
+
+Collect everything the vault session cannot cheaply rediscover. It starts
+with no knowledge of the PR, and every fact it has to dig out of fpl-cli
+is time spent and a chance to guess.
+
+**Both arms as full 40-character SHAs.** Control is the PR's merge-base
+with main, treatment is the PR head:
+
+```bash
+git fetch origin main <branch>
+git merge-base origin/main origin/<branch>    # control
+git rev-parse origin/<branch>                 # treatment
+git log --oneline <control>..origin/main      # has main moved on?
+git diff --stat <control> origin/main -- fpl_cli/
+```
+
+Copy the SHAs out of command output, never type one. One October brief
+went out with placeholder SHAs, and one session typed a SHA from memory
+and broke a uvx run. If main has moved on, say whether those commits are
+docs, tests or CI only (an empty `fpl_cli/` diffstat). If they touch
+`fpl_cli/`, stop and put it to the user: the PR should probably merge main
+first, so the round tests what will ship.
+
+**Only what you have read in full.** Every expectation in the brief about
+a file, probe, earlier change or count comes from reading the whole thing,
+never a preview, a diffstat or an inference. The first real brief told the
+vault session that a probe wrote the forfeit once, from the probe's first
+600 characters (it wrote it twice), and that an earlier PR had changed the
+prompt, from a diffstat that included console code (it had not). Each cost
+the round a stop. Where you could not check, write it as a question the
+dry run or the corpus answers, not as an expectation.
+
+**What the change is meant to do, per sentence shape, and what counts as
+a regression.** Quote real sentence shapes in full from the reports the
+issue cites or the PR's tests, with every manager name replaced by
+Manager A, Manager B. Never trim a sentence into a test-shaped fragment:
+one October fix brief did, and the PR's test passed while the real
+sentence was still missed. For each shape, say what treatment should write
+instead (or that it should be unchanged) and what would be a regression,
+and name the file each shape was quoted from so the vault session can find
+it. If an expectation you want sits uneasily with the PR's own rule (puns
+wanted in headlines, while the prompt's "no others" covers the headline
+too), put that to the user before writing the brief: left in, it becomes a
+definitional call the vault session makes mid-round, and the call moves
+the count. The brief that listed expected changes per shape ran fastest and cleanest
+of all the October rounds, because grading became a comparison against a
+written expectation instead of a judgement made from scratch.
+
+**The baseline.** The previous round's numbers for the same measure, from
+the linked issue or earlier PR bodies, numbers only. If no round has
+measured it, say so and say where the first measurement will come from
+(often control's own runs, or a replay of older control drafts), and do
+not predict its size: the first brief expected "a clear share" of repeats
+in control and the round found 1 in 10, which left the vault session
+deciding whether a wrong guess was a stop. "Better" is then stated against
+whatever control measures, not against a guess.
+
+**The gameweek.** The most recently finished one per
+`fpl status --format json`, unless the PR's evidence came from a specific
+gameweek (an issue quoting one week's recap), in which case name that
+gameweek and say why. The evidence week is where the failure is known to
+show, so it is the strongest test.
+
+**Run counts.** For fresh runs where the gate is a frequency, 40 draft and
+4 to 5 classic per arm. A round of 8 draft runs per arm in October was too
+small to call first time, and the re-run cost more than doing 40 once.
+Draft is the gate by default because it has the most checks and the most
+variance; where the change's evidence lives in classic (a classic-only
+section, a failure the issue saw only in classic), raise classic and say
+why. Replay rounds need no run counts.
+
+**The round name** for `RECAP_AB_ROUND`, as `pr<N>-gw<GW>` (`pr507-gw8`).
+
+**For a replay: which corpus rounds, and what recheck data.** List the
+rounds on the vault's main (`.claude/scripts/recap_ab/corpus/`, via the
+GitHub MCP `get_file_contents` on `rossgroomio/fpl-workspace` or a clone).
+Read the README's "Rechecking saved drafts": a check that reads a recap
+data key older snapshots lack judges those drafts on less than its build
+computes, so the replay needs `RECAP_AB_RECHECK_DATA` carrying that key for
+each round's gameweek and format, merged with any round's own
+`recheck-data.json`. Say what the key should hold and where its value
+comes from. Name the rounds whose snapshots already carry the key (a round
+recorded on this PR's own build does), since the override would replace
+their values. Read each probe you expect a result from in full.
+
+The replay's control will not reproduce a round recorded on an older build
+wherever a check changed in between. For each round, run
+`git log --oneline <round's recorded sha>..<control> --
+fpl_cli/prompts/league_recap_checks.py` and name the expected
+non-reproductions with their PR, giving every SHA involved in full: the
+first round's vault session met one such miss, guessed the SHA of the
+commit that explained it, and broke a replay before looking it up.
+
+**Whether a second control exists:** an earlier corpus round, at the same
+gameweek, holding control model runs (dry runs and probes alone cannot be
+pooled), whose control prompts are byte-identical to this control's. One
+October round pooled with its predecessor this way and halved the control
+runs it needed. Read what changed between the two builds in the code that
+writes the prompt (`fpl_cli/prompts/league_recap.py` and the recap data it
+reads), not a diffstat: `fpl_cli/cli/` also holds the console and saved
+report, which the model never sees. If you cannot tell, say the dry runs
+decide and leave it there. If no such round exists, say so, so the vault
+session does not go looking.
+
+## Step 4: Write the brief
+
+Fill in `references/brief-template.md` in its order; the template carries
+the wording that must survive verbatim in spirit, and the reasons stay
+here so the brief stays short enough to read before the round starts.
+
+- **The opening line** points the vault session at the harness README
+  first. The harness changed after most October rounds; a session working
+  from memory of an earlier round runs an older procedure.
+- **The role boundary** is near the top and absolute. In two October
+  rounds the vault session pushed fixes to the fpl-cli PR branch, and one
+  opened an fpl-cli PR. Both times the user asked it to, which is why the
+  boundary holds even against the user's own request mid-round: a fix made
+  in the vault session is invisible to the fpl-cli session that owns the
+  PR, which then pushes over it or reviews code it never saw.
+- **A fresh `origin/main` checkout of the vault.** A leftover branch from
+  an earlier round once caused git and stop-hook noise that read as a
+  broken test.
+- **Stop conditions at every step that has an expectation** (triage, dry
+  run, anything in the brief that does not match). "If anything in this
+  brief doesn't match what you find, stop and ask me" caught a missing
+  corpus in one round. A brief is written from one repo about another; a
+  stop costs a message, a wrong round costs an hour. Stops are for set-up
+  facts (triage, dry-run diffs, corpus contents, SHAs), never for results:
+  a number that differs from what the brief hoped for is the finding, and
+  the brief should not predict one in the first place.
+- **Landing** is spelled out because every October session needed a
+  follow-up message to land its round. Never write a blanket "don't commit
+  anything": one October brief did, and that round's drafts were lost
+  before the next round needed them. The rule is that anything naming
+  managers stays under `data/debug/`, and the corpus is the one tracked
+  exception.
+- **Out-of-scope findings and harness gaps are listed, not fixed.** One
+  round spent about an hour building unscoped harness and kept it only
+  because the user asked. A small harness fix the round cannot run
+  without may ride the round's vault PR; anything bigger is a finding.
+- **Scratch paths outside the harness's own scripts** are written
+  `${TMPDIR:-/tmp}/...`, the fallback the harness's `common.sh` already
+  uses, never a bare `$TMPDIR/...`. A fresh vault session may not set
+  `TMPDIR`; the pr545 brief's `cp -R "$FPL_CLI_CONFIG_DIR"
+  "$TMPDIR/pr545-config"` expanded to a path at the filesystem root, so
+  the session improvised `/tmp` and logged a harness gap that was really
+  a brief gap.
+- **The handback** (below) is required in full, because in October the
+  whole vault transcript, progress chatter included, was pasted back and
+  the fpl-cli session had to dig the results out.
+
+Before printing, read the brief once as the vault session will: every SHA
+is 40 characters and came from command output, no `<placeholder>` or
+"TBD" is left, every number has a source, every expectation comes from
+something you read in full, and no manager name or ID appears anywhere in
+it.
+
+## The handback
+
+One comment-only pull request review on the fpl-cli PR (event `COMMENT`,
+no inline comments, never `APPROVE` or `REQUEST_CHANGES`), posted once,
+after the vault PR is open if the round has one. It is a review rather than
+a plain comment because only the review reaches the fpl-cli session: in
+#507's first round a plain handback comment landed and the subscribed
+session never woke, while in its second the same text posted as a
+comment-only review woke it. Its first line is the marker, an HTML comment
+GitHub does not render:
+
+```
+<!-- ab-handback pr=<N> head=<40-char sha the round tested> round=<round> -->
+```
+
+Both sessions post as the same GitHub identity, and a session watching a
+PR is told to skip echoes of what it posted itself. The marker is how this
+session tells the handback apart from its own reviews and comments: it
+never writes one, so a review carrying it is an A/B result to act on. It also carries
+the head the round actually tested, which Step 5 checks.
+
+Then a heading, `## A/B handback for <round>, from the fpl-workspace
+session`, and two blocks:
+
+- **Block A, "PR body".** First-person prose in the create-pr skill's
+  style and length budget (up to three short paragraphs, plus caveats in
+  italics), numbers only, ready to go into the PR body as written.
+- **Block B, "Findings".** A verdict line (`ship`, `fix then re-run
+  fresh`, `fix then replay`, or `don't ship`), the vault PR link if one was
+  opened, then one entry per finding: kind (regression, check false
+  positive, missed catch, out of scope, harness gap); check code if any;
+  the sentence shape in full with managers as Manager A, Manager B; what
+  should have happened; and the test shape to add.
+
+The review lands in a public repo, and GitHub keeps edit history and
+sends notification emails, so a name in it cannot be taken back. The vault
+session writes it to a file under `data/debug/`, runs the vault's
+`.claude/scripts/recap_ab/handback_check.py` over it, and posts that
+exact file as the review body only on exit 0 (the GitHub MCP
+`pull_request_review_write`, or `gh pr review <N> --comment --body-file`).
+The script reads every manager the vault's
+ledger has recorded and fails (exit 1) on any spelling of a full name, any
+part of one no other manager shares, an entry ID, manager_key or league
+ID, and on a footballer who shares a manager's name, which has to be
+reworded by club and position; there is no allow-list. Exit 2 means it
+could not check, which is not a pass. If the script is missing or exits 2,
+the vault session does not post; it prints the handback in chat and says
+why, and the user carries it across. It never edits the review once
+posted: a correction is a second short comment-only review, opening with
+the same marker and a heading that says it corrects the first, through the
+same check.
+
+## Step 5: Closing the loop
+
+When the handback lands (a review event wakes this session; otherwise
+the check-in finds it or the user says it has been posted; read it from
+the PR's reviews, and its comments too in case an older brief's session
+posted a plain comment):
+
+1. **Check the marker.** Its `pr` is this PR and its `head` is the head
+   the brief pinned, or a later head the brief allowed ("if the PR has
+   moved on, use its current head and say so"). For a later head, read
+   what changed between the two: if it changes what the model sees or the
+   checks, the round tested something other than what was briefed, so say
+   so to the user before acting on the numbers. A review or comment with
+   no marker is not a handback, whoever wrote it.
+2. **Put Block A into the PR body**, replacing whatever caveat said the
+   A/B had not run, keeping the body inside the create-pr style.
+3. **Treat each Block B finding like a review comment.** Fix and push
+   (`chore(review): ...` commits, per CLAUDE.md), or say on the PR why
+   not, in one comment covering every finding you are not fixing. Never
+   reply to the handback review itself: the vault session is not
+   listening, and a reply there reads as a thread for nobody.
+4. **Re-run Step 2 on the new head.** If the fixes change what the model
+   sees, write a fresh-run brief for the new head; if they touch only the
+   checks, a replay brief; either way the next round's handback comes back
+   the same way, and this session stays subscribed. A verdict of
+   `fix then re-run fresh` or `fix then replay` is the vault session's
+   expectation, and Step 2 on the actual fixes decides. Scope the round by
+   the diff, not by the finding: a system-prompt line reaches every arm,
+   so a fix aimed at the phrasings arm alone still re-runs the plain
+   treatment arm when it touches the system prompt (#507's first fix did).
+   An earlier round's arm is reused only where its build is unchanged and
+   the new dry runs show the same data sections, and a follow-up round
+   whose predecessor's vault PR is still open continues on that PR's
+   branch under the same round name with new labels, so both rounds are
+   graded together and land together.
+5. **If no fix is needed**, say the A/B gate is cleared, and resolve the
+   thread left open as the gate (reply first, saying which round cleared
+   it). Merging stays the user's call.
+6. **Out-of-scope findings** become issues only once the user agrees: list
+   them for the user with a one-line proposal each.
+
+A `don't ship` verdict goes to the user before anything else: it may mean
+the approach is wrong, which is their decision, not a fix to push.
+
+## Step 6: Deliver
+
+1. **Subscribe this session to the PR's activity before printing**
+   (`subscribe_pr_activity`), so the handback review wakes it, and say so.
+   Subscribing after printing races a fast replay round. The wake has
+   worked once, so also arm one backstop `send_later` check-in about two
+   hours after delivery that reads the PR's reviews for the marker; re-arm
+   it twice at most, then tell the user once that the next message from
+   them will bring you back. Where either tool is missing (a local session,
+   another agent), tell the user to come back here and say when the
+   handback is posted.
+2. **Print the brief in one fenced block** for copy and paste, with a
+   fence longer than any fence inside it (`~~~~` around a brief that holds
+   ```` ``` ```` blocks), so the copy comes out whole.
+3. **Above the block, not inside it, say how to start the vault session:**
+   a fresh session on `rossgroomio/fpl-workspace`, Opus, at xhigh effort
+   for a round with fresh runs and high for a replay alone. October's
+   fresh rounds ran at xhigh; a replay at high took under four minutes.
+
+## Common mistakes
+
+- Running triage, a dry run or a replay here "to check the brief": that
+  is the overlap this skill exists to end
+- A placeholder or hand-typed SHA, or a short one
+- A sentence shape trimmed to the fragment a test matches
+- "Don't commit anything" in place of the landing rules
+- A scratch path written `$TMPDIR/...` with no `:-/tmp` fallback
+- Printing the brief before subscribing to the PR
+- A brief that asks for the handback as a plain comment, which does not
+  wake the subscribed session
+- An expectation built from a preview, a diffstat or a guess at a count
+- Treating the handback as an echo of this session's own review, or
+  editing the PR body with the vault session's transcript instead of
+  Block A
+- A manager name in the skill, the brief, the PR or a commit