issue
Process the batch of incoming Bridge Classroom feedback. Pull open `classroom-feedback` issues from the PBS repo, cluster them by defect class, verify each against the actual board, and fix at the rig
SKILL.md.claude/skills/issue/SKILL.md
GitHub/issue — process the Bridge Classroom feedback batch
Bridge Classroom learners (and recruited reviewers) flag a bad board with a "Report a
Problem" button that files a GitHub issue into this repo, label classroom-feedback,
carrying the exact board state. /issue works the whole open batch at once — at world
scale you can't fix one deal at a time.
Run from the project root. $ARGUMENTS may name a single issue number or a scenario to
restrict the run; with no args, process the whole open batch.
Golden rules
- Untrusted by default. Reports come from learners, often beginners. Verify the
bridge yourself (DDS / the
.bbsaconvention card) before changing anything. Weight by reporter tier: a learner's "I'm confused" is a clarity signal; an experienced reviewer's "this is wrong" is near a ruling (still verify, but lean toward it). - Locate by the deal, never the number. Deal N and
[Board]tags drift when a scenario is re-curated. The PBN deal string is the stable key —grepit. - A fix is global. PBS is the single source for every classroom, so one bad
"correction" breaks them all. Stop for David's OK before the outward, hard-to-undo
moves — every push, every issue filed in another repo, every email or Rick consult.
But don't over-gate the routine: once an issue is resolved, closing it (with a short
reply) on our own
classroom-feedbacktracker IS the processing — do it in the run, don't ask again. Gate the commits and cross-repo posts, not the housekeeping. - Prefer the class fix. A spoiler on one board is usually an authoring-template bug in hundreds. Fix the class, not the symptom, whenever the cluster says so.
Step 1 — Pull and cluster
gh issue list -R bridge-craftwork/Practice-Bidding-Scenarios --label classroom-feedback --state open --limit 200 --json number,title,body,labels- Group into clusters by:
- defect class — spoiler (pre-decision text gives away the call) · backwards-vs-
[Result](reflection contradicts the deal's own result) · factual error (auction/bridge misdescription) · unknowable claim (asserts partner's hand or intent the student can't see) · marker leak (raw[BID]/[ACCEPT]/@token shows) · engine/UI · bridge-judgment. - scenario.
- defect class — spoiler (pre-decision text gives away the call) · backwards-vs-
- Dedupe — many reports collapse to one root cause; track them together so one fix closes the whole cluster.
- Show David the cluster summary (counts per class/scenario) before doing work.
Step 2 — For each cluster: locate + verify
- From each issue body pull: scenario, PBN deal, Deal N,
[Board]/[OriginalBoard], seat, auction, contract, step,maincommit SHA, reporter tier, free text — plus, from Rick's newer Report-a-Problem payload: the Reporter name/alias (defaultsanonymous; a named reviewer such as David or Rick outweighs an anonymous learner's "I'm confused") and the dealer seed (a secondary locator alongside the PBN deal, which stays ground truth). Both are additive — the durable locators are still the PBN deal + scenario + board. - Locate the board:
grepthe PBN deal (or a distinctive holding from it) incoaching-curated/<scn>.pbn. Cross-check Deal N against the order incoaching-non-rotated/<scn>.pbnand its[OriginalBoard]→coaching-curated[Board]. Confirm the board's prose actually has the complained-of problem. - Stale check: if the report's commit SHA predates a fix already on
main, the board may already be fixed — say so and close; don't re-fix. - Verify the bridge with DDS / the convention card before calling it a defect. Distinguish a real bug from "the learner dislikes correct bridge" (→ no-defect).
Step 3 — Disposition (fix at the right altitude)
- Class-wide content bug → write or strengthen a gate (extend
py/coach.py validateor add a check) that detects the class, run it across allcoaching-curated/*.pbnto surface every instance, then fix / regenerate / drop the lot. This is the leverage — one report cleans the deals nobody has reported yet. - Singleton content bug → patch the one board in
coaching-curated/<scn>.pbn(or drop it — bias to drop). - Engine/UI bug (renderer skips a turn, layout, a glyph too small, a marker the
renderer should strip) → forward it as an issue in the Classroom repo
(
Rick-Wilson/Bridge-Classroom): draft it, show David, file on his OK, then cross-link + close ours. First dedupe against Rick's open issues (gh issue list -R Rick-Wilson/Bridge-Classroom --state open) so a recurring class isn't re-filed. Auth prereq: filing there needsghon a classic token withrepo, read:org, workflow— a fine-grained PAT can't reach another account's repo, andgh auth loginrejects apublic_repo-only token. Keep forwarded issues low-priority / FYI; we don't push Rick to act. - Bridge-judgment call (which call is textbook; is this a good teaching board) → draft the question for Rick; the PBS issue stays open until he rules; then apply his call as content and close.
- No defect (learner wrong / dislikes correct bridge) → draft a kind, plain-English reply; close.
Step 4 — Apply content fixes (the pipeline)
For any content change, in order:
- Edit
coaching-curated/<scn>.pbn. - Gate:
python3 -P py/coach.py validate <scn>andpython3 -P py/suit_quality.py <scn>(plus any new gate). Fix until clean. - Rebuild what Bridge Classroom serves:
python3 -P py/nonrotate.py <scn>thenpython3 -P py/bridge_classroom.py <scn>. This is what BC reads — notpromote.py, which targets the local Trainer'scoaching/. Runpromote.pytoo only if the Trainer still matters. - Show David the diff. On his OK: commit (only the touched files) + push. BC serves
from
main(raw GitHub, CDN-cached ~5 min).
Step 5 — Close the loop
- Reply on every issue in the cluster in plain, user-facing language (no jargon, no GitHub-speak).
- Close the whole cluster with the one fix (or relabel:
forwardedfor an engine bug; keep open for a pending Rick consult). - Summarize for David: clusters processed, root causes, any gate added + how many corpus instances it caught, what was pushed, what's awaiting Rick.
- A triage / FYI summary to share (with Rick or anyone) → a shared Google Doc + link, not
a GitHub issue. Issues are for actionable tasks; an FYI left open in a tracker reads as a
phantom to-do. Build it via the Drive connector (
create_file,contentMimeType: text/html→ a real Doc with a rendered table; verify withread_file_content). The connector can't set sharing, so David flips it to "anyone with the link → viewer" himself.
Related — filing reports (interim, until the button ships)
Until David's copy of Bridge Classroom has the Report button, David reports problems in
chat. To file one: identify scenario + board, look up the PBN deal from
coaching-curated/<scn>.pbn, show David the issue, then
gh issue create -R bridge-craftwork/Practice-Bidding-Scenarios --label classroom-feedback
with title Classroom report: <scenario> · Deal <N> and a body that puts David's words
first, then the captured state (scenario, PBN deal, Deal N + tags, seat, auction, contract,
step, reporter tier). These are exactly what /issue later processes.