Triage Board

Triage Board

Turn an exploration session into a triage artifact: a ~/Desktop/triage-boards/<topic>-<YYYY-MM-DD>/ folder containing the same data in three forms — prose report.md for skimming, structured report.json for tools, and a self-contained viewer.html for the user (or a developer) to triage interactively in their browser. Tracking state (status, comments, tickets, screenshots) lives in localStorage keyed by report+date, so reviewers can each have their own annotations without a backend.

Preferences

On startup, use the Read tool to load ~/.claude/skills/triage-board/preferences.md. If missing, use sensible defaults.

Context

On startup, use Bash to verify ~/Desktop/triage-boards/schema/triage-board.schema.json exists. If missing, copy from ~/.claude/skills/triage-board/templates/schema.json on first run.

Command routing

Check $ARGUMENTS:

• help → display help, then stop
• config → interactive setup via AskUserQuestion, then stop
• reset → delete ~/.claude/skills/triage-board/preferences.md, confirm, stop
• --topic <slug> → use as the topic slug (skip Q1)
• --findings <path> → read findings JSON from path (skip Q2/Q3 — assume pre-built)
• anything else (including empty) → run the skill

Help

triage-board — Generate a structured triage artifact from session findings

Usage:
  /triage-board                       Build a new report from current conversation
  /triage-board --topic <slug>        Use a specific topic slug (skips topic prompt)
  /triage-board --findings <path>     Use a pre-built findings JSON file
  /triage-board config                Set preferences
  /triage-board reset                 Clear preferences
  /triage-board help                  This help

Output (always at ~/Desktop/triage-boards/<topic>-<YYYY-MM-DD>/):
  report.md      — Prose mirror for skimming / sharing
  report.json    — Schema-conformant structured findings
  viewer.html    — Single-file interactive triage UI (works from file://)

Examples:
  /triage-board                       After a beginner-mind PMI audit
  /triage-board --topic pmi-bulk-flows

First-time experience

If preferences.md is missing, show once: First time using /triage-board? Run /triage-board config to set defaults, or continue with sensible defaults. Then proceed.

Workflow

Step 1 — Confirm topic + scope

If --topic was passed, use it. Otherwise ask the user via AskUserQuestion:

1. Topic slug — kebab-case identifier for the folder (e.g. pmi-beginner-mind, auth-flow-audit). Suggest one based on conversation context; let them edit.
2. Date — default today (date +%Y-%m-%d); offer to override.

Final folder path: ~/Desktop/triage-boards/<topic>-<YYYY-MM-DD>/.

Step 2 — Gather findings

If --findings <path> was provided, read that JSON file (must conform to the schema; validate before proceeding).

Otherwise, mine the current conversation for discrete findings. Look for:

• Things the user (or you) flagged as bugs, UX gaps, content issues, perf issues, a11y issues
• Things with a clear where / symptom / impact / repro / triage shape, even if not all five are present
• Items the user explicitly named (B1, U7, etc.) — preserve those IDs

For each finding, assemble:

• id — [A-Z]+[0-9]+ (B# bugs, U# ux, C# console/perf/a11y). Stable across re-runs.
• severity — one of: critical | high | medium | low | info
• category — one of: bug | ux | accessibility | content | performance | console
• title — one-line summary
• where — file/route/component
• symptom — what the tester saw
• impact — why it matters to a user
• repro — step-by-step
• triage — suggested fix direction (not prescriptive)

Also gather optional:

• positives — what worked well (array of strings)
• notes — side effects of testing (data destroyed, accounts created, etc.)

Step 3 — Confirm the finding set

Show a compact table (severity + id + title only) and let the user accept / drop items via AskUserQuestion with multiSelect: true. Default = all selected.

Step 4 — Write the schema (if missing)

if [ ! -f ~/Desktop/triage-boards/schema/triage-board.schema.json ]; then
  mkdir -p ~/Desktop/triage-boards/schema
  cp ~/.claude/skills/triage-board/templates/schema.json \
     ~/Desktop/triage-boards/schema/triage-board.schema.json
fi

Step 5 — Write report.json

~/Desktop/triage-boards/<topic>-<YYYY-MM-DD>/report.json. Must validate against the schema. Include:

• schemaVersion: "1"
• meta — title / date / tester / surface / branch / scopeIncluded / scopeExcluded
• findings — array (accepted in Step 3)
• positives — array
• notes — array

Step 6 — Write report.md

Prose mirror of the JSON. Use the same severity tiers (Critical / High / Medium / Low / Info). One section per severity, findings in order of ID within the section. Each finding gets a ### <id> — <title> heading with the same fields formatted as **Where:** … / **Symptom:** … / **Impact:** … / **Repro:** … / **Triage:** ….

End with Things that worked well, Notes / side effects, and a Severity summary table.

Step 7 — Write viewer.html

Copy ~/.claude/skills/triage-board/templates/viewer.template.html and inline the JSON at the marker /*REPORT_JSON_START*/…/*REPORT_JSON_END*/. Use Python or sed for the substitution (Python preferred — handles edge cases):

python3 <<'PYEOF'
import re, json, pathlib
report = pathlib.Path('<dest>/report.json').read_text()
json.loads(report)  # validate
template = pathlib.Path('~/.claude/skills/triage-board/templates/viewer.template.html').expanduser().read_text()
out = re.sub(r'/\*REPORT_JSON_START\*/.*?/\*REPORT_JSON_END\*/',
             '/*REPORT_JSON_START*/' + report.strip() + '/*REPORT_JSON_END*/',
             template, flags=re.DOTALL)
pathlib.Path('<dest>/viewer.html').write_text(out)
PYEOF

Step 8 — Open + report

• open -a "Google Chrome" <dest>/viewer.html to launch.
• Print the folder path + summary: count by severity, count of positives/notes.
• Pipe the folder path to pbcopy so the user can cmd+v it elsewhere.

Viewer features (what's in templates/viewer.template.html)

Stateless, single-file HTML with vanilla JS (~25 KB). No localStorage, no tracker, no build step. The findings JSON is the only source of truth; the viewer just renders it.

1. Header export buttons — three ↓ MD / ↓ CSV / ↓ JSON buttons in the top-right of the header. Each generates the artifact from the in-page REPORT object and triggers a download (report-<date>.md, report-<date>.csv, report-<date>.json).
2. Stats pills — counts per severity + total.
3. Filter bar (sticky) — severity / category / search-by-id-or-title-or-details.
4. Cards — severity-tinted left border, ID chip + category chip + title. Click to expand → Where / Symptom / Impact / Repro / Triage.
5. Copy as Markdown per card — primary action inside each expanded card. Copies the finding as a GitHub/Linear/Notion-ready markdown block to the clipboard:

   ## [B8] Bulk Delete has NO confirmation modal
   
   **Severity:** `critical` · **Category:** `bug`
   
   **Where**
   
   Bulk-select header on Action Items / Decisions / Questions
   
   **Symptom**
   
   Clicking `Delete` in the bulk-action header immediately destroys all selected items…
   
   **Impact**
   
   Data loss in one click. Contradicts the pattern PR #977 just shipped…
   
   **Repro**
   
   Open any meeting → tick the header select-all checkbox → click Delete…
   
   **Triage**
   
   Wire bulk Delete into a confirmation modal using MeetingModalLayout…
   
   ---
   _From: PMI Beginner-Mind Audit · 2026-05-15 · /w/30/meetings_
   

   Button shows ✓ Copied! briefly after click. Falls back to document.execCommand("copy") if the Clipboard API is blocked.
6. Aesthetic — gradient header (blue→pink glass, matching the design system), severity-colored chips, system font stack. Minimal.

Schema (at templates/schema.json)

JSON Schema draft-07. Key constraints:

• id must match ^[A-Z]+[0-9]+$
• severity enum: critical | high | medium | low | info
• category enum: bug | ux | accessibility | content | performance | console
• meta.title, meta.date, meta.surface required
• findings[].id, findings[].severity, findings[].category, findings[].title required

No tracker state in the schema or viewer — when reviewers want to act on a finding, they click Copy as Markdown and paste into their ticket system of choice (Linear, GitHub, Notion, Slack). Triage state lives in the ticket system, not the report.

Principles

1. Stateless viewer, single-file output — must work from file:// with no network, no build, no localStorage. JSON is inlined at write time and is the only source of truth.
2. Quote the source — every finding's symptom / repro should be specific enough that a developer can reproduce without asking. Vague findings are noise.
3. Triage lives in the user's ticket system, not the viewer — the viewer's job is to make findings easy to move out (one-click Copy as Markdown, plus MD/CSV/JSON exports in the header). Status and ownership belong to Linear / GitHub / Notion, not localStorage.
4. Three formats, one shape — MD, CSV, JSON all reflect the same findings. The user picks the format for the destination (MD for tickets and Slack, CSV for spreadsheets, JSON for tools).
5. Pragmatic, not over-engineered — no tracker, no comments, no screenshots-in-viewer. If the user wants screenshots, attach them to tickets after pasting the Markdown.

Learned

Auto-managed. The skill silently adds preferences here when the user corrects a default (chose a different topic slug pattern, dropped a section, etc.). Surface once when adding: "Noted: . Saved for next time."