From dev-playbook
Use when the user wants an interactive step-by-step HTML walkthrough explaining a complex technical problem (DB error, race condition, design issue, conceptual blocker) using concrete data and manual navigation. Triggers on phrases like "make me a walkthrough", "explain step by step with data", "interactive explanation", "make an animation", "walk me through with real examples", "อธิบายแบบ step by step", "ทำ animation/walkthrough/visualization", "ทำเป็น diagram", "วาด diagram". Do NOT use for one-line clarifications, conceptual Q&A answerable in a paragraph, or simple "what does X mean" questions — only when an interactive HTML artifact would clearly help.
How this skill is triggered — by the user, by Claude, or both
Slash command
/dev-playbook:problem-descriptionThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Generate a self-contained HTML page that explains a technical problem using:
Generate a self-contained HTML page that explains a technical problem using:
Next →, ← Previous, ↻ Reset buttons. Reader controls pace.Core principle: The reader should be able to point to any specific element at each step and say "yes I understand why this is in this state right now."
This skill has two modes. Pick the right one for the problem.
Boxes positioned spatially with arrows showing data flow between them. At each step, certain boxes light up and certain arrows fire, with "flying" labels showing the values being passed.
Use this when the problem is about:
Canonical reference: c:/Repo/glasshull repo/glasshull/docs/2026-05-28-polaris-booking-number-diagram.html — 22-step explanation of Polaris's classic-workflow + CodeActivity + counter-entity architecture, including a 3-transaction concurrency demo.
Template: skills/problem-description/template-diagram.html
Database tables rendered as styled HTML tables. At each step, specific rows highlight, badges (DELETE / SET NULL / CONFLICT) appear, fixed rows turn green, deleted rows go gray.
Use this when the problem is about:
Canonical reference: c:/Repo2/t/cascade-paths-explained.html — 7-step SQL Server error 1785 walkthrough using "ครอบครัวสมศรี" budget data.
Template: skills/problem-description/template.html
If you're explaining "what happens to row X" → Mode B (tables). If you're explaining "what flows from A to B to C" → Mode A (diagram).
When in doubt: Mode A (diagram) is the better default — most technical problems involve component interaction, and the diagram view scales to concurrency and message-passing scenarios that tables can't show cleanly.
Don't use when:
drive-to-legacy instead)frontend-design instead)superpowers:systematic-debugging instead)Before generating ~500 lines of HTML, ask:
"อยากได้ interactive step-by-step walkthrough (HTML page เปิดในเบราว์เซอร์), หรือคำตอบสั้นๆ พอ?"
Skip Phase 0 if the user explicitly asked for "walkthrough", "animation", "visualization", "step by step", "ทำ animation", "diagram", "interactive", or similar artifact-shape language.
Articulate three things in one sentence each:
Then pick the mode using the "How to choose" rule above. Tell the user which mode you're using in your first message.
If you can't articulate (1) and (2) in one sentence each, ask the user before continuing. Vague misunderstandings produce vague walkthroughs.
Replace abstract entities with realistic, culturally appropriate data.
Data Quality Checklist:
5, 42, 80฿ — not 47,392.18฿)cargo-1/cargo-2 that the reader will confuse for those. Prefer letter IDs (cargo-A, cargo-B) or source-tagged labels (cargo (Portal)).ctg_runningnumber, BudgetTransactions — not Counter, Table1)Bad → Good examples:
| Bad | Good |
|---|---|
Entity A references Entity B | BMW Group owns cargo-A |
cargo-1, cargo-2, cargo-3 (collides with booking #1, #2, #3) | cargo-A, cargo-B, cargo-C or cargo (Portal), cargo (CIT) |
Table1, Table2 | ctg_runningnumber, ctg_cargodetail (real schema names) |
value1=100 | accountnumber="BMW" |
Build a domino chain. Each step adds one new piece of state.
Standard skeleton (diagram mode):
| Step | Purpose |
|---|---|
| 0 | Overview — show all components + arrows in idle state. No action. Reader builds mental model. |
| 1 | Trigger — what initiates the flow? (Light up the triggering component.) |
| 2..N | Single-actor flow — ONE component activates per step, ONE arrow fires per step, ONE value shown flying along it. State accumulates visibly. |
| N+1 | The key question (REQUIRED) — pose a question the reader must answer in their head before the concurrent / failure scenario reveals the answer. |
| N+2..M | Concurrent / failure scenario — show 2-3 actors racing, blocking, or conflicting. |
| M+1 | Counter-example — what would go wrong with the naive approach (e.g., "what if we used MAX()+1?"). |
| M+2 | Summary / resolution — why the architecture works AND its trade-offs / side-effects. |
Standard skeleton (tables mode):
| Step | Purpose |
|---|---|
| 0 | Setup — show all tables + all rules. No action. |
| 1 | Trigger — user action starts the chain. |
| 2..N | Domino effects — ONE rule fires per step, affecting specific named rows. |
| N+1 | Key question. |
| N+2 | Conflict / failure step. |
| N+3 | Resolution with side-effects named. |
Each step has:
Mode A (diagram): Read skills/problem-description/template-diagram.html. The template ships with a 3-step demo (Client → Server → DB) so you can verify the scaffold works in a browser before adapting it.
Adapt these insertion zones:
<g class="comp"> per component, positioned absolutely in the SVG coordinate space<path class="arrow"> between component anchor points<g class="flow-label-group"> for data flying along arrowsCOMPONENTS, ARROWS, LABELS arrays — every id used in scenes (drives clearAllStates())questionPanel, racePanel, summaryPanel (declared once, shown by scenes)Mode B (tables): Read skills/problem-description/template.html. Adapt the table grid, rules panel, ID_LIST, scenes, and keyQuestion panel.
Critical rule (both modes): every scene must fully describe DOM state from scratch. Never appendChild from a scene. All optional panels (key-question, race demo, summary) declared upfront with class="hidden", toggled per scene via show()/hide().
Default save path:
<workspace-root>/docs/YYYY-MM-DD-<topic>-walkthrough.html (diagram mode) or <workspace-root>/docs/<topic>-explained.html (tables mode)c:/Repo2/t/<topic>-walkthrough.htmlReport back:
ถัดไป → / ← ย้อนกลับ / ↻ เริ่มใหม่ ปุ่มควบคุม pace"Run the self-test checklist:
scenes.length - 1 === TOTAL in JS (step 0 is included; TOTAL is the index of the last step)getElementById(id) call has a matching id attribute in the HTMLCOMPONENTS / ARROWS / LABELS (diagram mode) or ID_LIST (tables mode) contains every id used in scenes← Previous from any step returns clean state (idempotent scene rule)↻ Reset returns to step 0 with no residual highlights, badges, or visible panelsappendChild / createElement inside any scene functioncargo-1 when booking numbers 00001 will appear)If any item fails — fix before reporting done.
The diagram template encodes proven choices:
Color tokens (don't change — proven for readability):
#5fb4ff — info / accent / active (blue)#ffd479 — firing / value-in-flight (amber)#b070ff — locked / magic / "this is the key step" (purple)#ffaa00 — blocked / warn (orange)#4ade80 — done / success (green)#ff5757 — error / conflict (red)#0a0e14 — background, #1a2330 — panel backgroundComponent states (set via setComp(id, state)):
'' — idle (default gray border, dim text)active — lit cyan, current focusfiring — pulsing amber, just got triggeredlocked — purple with glow, holds an exclusive lockblocked — orange, dimmed, blinking — waiting on someone elsedone — green, completederror — red glowdimmed — 35% opacity, fades into backgroundArrow states (set via setArrow(id, state)):
'' — idle grayactive — bright cyan with dashed flow animationmagic — purple, "the special arrow" (lock acquisition, etc.)done — green, traversederror — redFlow labels (set via setLabel(id, show, variant)) — pre-positioned along each arrow's midpoint, toggled per scene. Variant 'magic' or 'error' recolors for those states.
(Inherited from the original tables template — unchanged.)
State classes on row elements: .target-delete, .target-setnull, .target-conflict, .fixed, .deleted.
Badge classes: .badge.delete, .badge.setnull, .badge.conflict.
Single source of truth for rows:
const ID_LIST = ['F1', 'C1', 'C2', 'A1', 'T1', 'T2', 'T3'];
clearAllStates() iterates this list to reset rows + badges.
Every scene function must fully describe DOM state from scratch. Never build cumulatively.
Why: if scene 4 calls appendChild(panel) and scene 5 doesn't remove it, then ← Previous from scene 6 to scene 4 leaves the panel duplicated. Idempotent rendering eliminates this entire class of bugs.
How:
.hidden class (or with default content for live-text fields)show('panelId') / hide('panelId') to toggle visibilitysetComp(id, state) / setArrow(id, state) / setLabel(id, show) / setBadge(id, html) — these REPLACE state, never appendsetText(id, text) to update live-text fieldsclearAllStates() first, then runs ONLY the current scene functionNo scene function ever does:
document.createElement(...)el.appendChild(...)el.classList.add(...) (use the wrapper setters, which replace)el.innerHTML += ...If you need to "add" a panel mid-walkthrough, declare it once in the initial HTML with .hidden and show() it from the scene.
| Mistake | Fix |
|---|---|
| Wrong mode picked — tables for a flow problem | Use the "How to choose" rule. Flow → diagram. Row state → tables. |
| Auto-playing animation that races past the reader | Manual Next → only. Reader controls pace. |
Abstract names (A, B, Table1, Customer1) | Real, domain-flavored, culturally appropriate names. |
IDs collide with output sequence numbers (cargo-1 vs booking 00001) | Use letter IDs (cargo-A) or source-tagged labels (cargo (Portal)). |
| Each step changes too many things at once | One component activates per step. One arrow fires. One value moves. |
| Narration says WHAT, not WHY | Every narration explains the rule's reason. |
| No "key question" step | The conflict/concurrency reveal needs a thinking-pause beforehand. |
| Fix without side-effects called out | Resolution always has trade-offs — name them. |
| Cumulative-replay rendering | Idempotent scenes only — no appendChild from scenes. |
| 300+ lines of HTML for a 2-step problem | This skill is for problems with 4+ chained effects. Smaller problems → just chat or use a single mermaid diagram. |
← Previous leaves stale state | Scene functions must fully describe state, not deltas. |
| Same element never highlighted in the conflict step | Pick concrete data so at least one element is hit by every problematic path. |
| Flying-label rect too small / clipped text | Measure your label text length; widen the <rect> to fit comfortably. |
c:/Repo/glasshull repo/glasshull/docs/2026-05-28-polaris-booking-number-diagram.html — DIAGRAM MODE canonical. 22 steps explaining how a classic workflow + CodeActivity + counter entity collaborate to assign sequential booking numbers, including a 3-transaction concurrency demo and a race-condition counter-example. Mixed Thai/English narration. Use this as the structural reference for any architecture/flow walkthrough.c:/Repo2/t/cascade-paths-explained.html — TABLES MODE canonical. 7 steps explaining SQL Server error 1785 (multiple cascade paths) using "ครอบครัวสมศรี" budget transactions. Use this for any row-state walkthrough.Provides behavioral guidelines to reduce common LLM coding mistakes, focusing on simplicity, surgical changes, assumption surfacing, and verifiable success criteria.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub thodsaphonsonthiphin/dev-playbook --plugin dev-playbook