Borrowing it
Nothing to install: this file belongs to jerseycheese/Narraitor. Take a copy, put it at the same path in your own repository, and replace the rules that are about this project with yours.
curl -O https://raw.githubusercontent.com/jerseycheese/Narraitor/main/.claude/skills/narraitor-debugging-playbook/SKILL.mdgit clone --depth 1 https://github.com/jerseycheese/NarraitorWrote this? Show the measurements
A badge with what this costs and how it scanned, read live from this page, so it follows the numbers instead of freezing them. Markdown for a README, HTML for a documentation site or a project page.
[](https://agentmods.dev/skills/jerseycheese/narraitor/narraitor-debugging-playbook)<a href="https://agentmods.dev/skills/jerseycheese/narraitor/narraitor-debugging-playbook"><img src="https://agentmods.dev/badge/skills/jerseycheese/narraitor/narraitor-debugging-playbook.svg" alt="Measured on agentmods" height="20"></a>What it costs to keep this loaded
Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.
| Model | Per session | Once invoked |
|---|---|---|
| Fable 5.1 | $0.00092 | $0.01519 |
| Opus 5 | $0.00046 | $0.00759 |
| Sonnet 5 | $0.00018 | $0.00304 |
| Haiku 4.5 | $0.00009 | $0.00152 |
Grade B, and why
narraitor-debugging-playbook scanned grade B with 2 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured 8d ago.
A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.
Sends data to an external URLmediumData exfiltration
A POST to an outside endpoint may be telemetry or may be exfiltration; either way the mod talks to somewhere, and you should know where.
| AI route 500/4xx | `curl -s -X POST localhost:3000/api/narrative/generate -H 'Content-Type: application/json' -d '{}'` → expect 400 "prompt is required" (proves wiring, no key needed) | Body shape — `{prompt: string}` Makes network callslowCapability
Not a fault in itself. Listed so you know the mod talks to something, and to what.
| AI route 500/4xx | `curl -s -X POST localhost:3000/api/narrative/generate -H 'Content-Type: application/json' -d '{}'` → expect 400 "prompt is required" (proves wiring, no key needed) | Body shape — `{prompt: string}` How it starts
The opening of the file, as written. The whole thing — 66 lines — stays where its author put it; the contents beside it link to each section on GitHub.
Narraitor debugging playbook
1. Purpose
Route a symptom to its first discriminating check so debugging converges instead of wandering. State the root-cause hypothesis BEFORE touching code; prove it by reproducing.
2. When to use
Any live failure; any time a first fix attempt didn't work; any time you catch yourself guessing.
3. When not to use
- Command fails before your code runs (install/port/browser) →
narraitor-build-test-envfirst. - Failure is a known settled battle → check
narraitor-failure-archaeologybefore re-fighting it. - AI output is bad rather than broken →
narraitor-ai-quality-discipline.
4. Inputs required
The exact failing command or user flow, verbatim output/screenshot, and which checkout/port served it.
5. Procedure — symptom table
Run the first check before forming theories.
| Symptom | First discriminating check | Likely root causes | False friends |
|---|---|---|---|
| Blank/empty narrative in play | Browser network tab (or preview_network): did /api/narrative/generate fire? Status? |
Missing provider key (resolveApiKey → null); response parse failure (narrativeGenerator.response.parse.ts); generation error held in narrativeStore error state |
Restyling the component; blaming the prompt when the route never fired |
| AI route 500/4xx | curl -s -X POST localhost:3000/api/narrative/generate -H 'Content-Type: application/json' -d '{}' → expect 400 "prompt is required" (proves wiring, no key needed) |
Body shape — {prompt: string} applies ONLY to generate/choices; ending/summarize/checkpoint have their own contracts (read the handler); key resolution; upstream Gemini error/outage; timeout (30s server-side on generate/choices, 120s client-side aiFetch) |
"The AI is down" when it's a 400 from your own malformed body |
| Hydration mismatch warning | Does it reproduce on hard refresh with DevTools console open? Which component does React name? | Server/client boundary rendering store-dependent UI before _hasHydrated; Date serialization (narrativeStore has custom persistence); non-deterministic render (random/time) |
Suppressing the warning; memoizing without finding the divergent value |
| State not persisting across reload | Browser devtools → IndexedDB → db narraitor-state, object store narraitor-store: is the persist key's blob updated? |
Wrong/renamed persist key; shape change without migrate (loreStore is v3); action mutating outside set() |
Blaming Zustand; adding a second storage path |
| Works in Storybook, broken in app | Diff the data: story's withStores seed vs real hydrated store (inspect IndexedDB blob) |
Mock props/canned MSW responses hiding a real-shape mismatch; story seeds fields the app never populates | Tweaking CSS/props until Storybook AND app both look right-ish — fix the data contract |
| Theming drift (token resolves wrong) | Reproduce in Storybook toolbar across light + dark (one design system, ds3, since ADR-013); inspect computed style of the token (getComputedStyle(el).getPropertyValue('--color-…')) |
Token defined in one theme file only; legacy --primary HSL tokens vs --color-* drift (#1474); selector specificity vs .app-surface-* heading rules |
Hardcoding the "right" color (stylelint will block it — and it's wrong) |
| Visual spec diff/flake | Is the diff 0-pixels-but-timeout, or a real pixel region? Re-run the exact spec twice | Timeout → AI call escaping isPlaywrightEnv() gate or wrong worktree server; real diff in shared chrome → stale baseline cascade (rebase all affected at once) |
Bumping timeouts; regenerating one baseline while siblings stay stale; regenerating on Linux |
| Mystery tsc errors after touching AI SDK usage | cat src/types/@google/genai.d.ts — the ambient file SHADOWS the real SDK types |
New SDK field not declared in the ambient file | Casting to any; "upgrading" @google/genai to fix types |
| Console.log "not appearing" | Logger defaults suppress debug/info in dev | Output routed through logger.debug |
Concluding the code path never runs |
What ships with it
1 file beside SKILL.md in the same directory: the scripts, references and assets a skill reads on demand. Not counted in the per-session cost; read them before you install if any of them is executable.
What this file has done since we first saw it
Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.
- 8d ago First seen · 66 lines · 92 tokens per session scan B 9d2107c2a41a
narraitor-debugging-playbook is a skill published in the GitHub repository jerseycheese/Narraitor (30 stars, last pushed today), licensed MIT. It adds 92 tokens to every session and 1,519 once invoked, about $0.0005 per session on Opus 5. A static security scan graded it B with 2 findings (sends data to an external url, makes network calls). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.
Other skills, from other repositories
debug-optimize-lcp
Guides debugging and optimizing Largest Contentful Paint (LCP) using Chrome DevTools MCP tools. Use this skill whenever the user asks about LCP performance, slow page loads, Core Web Vitals optimization, or wants to understand why their page's main content takes too long to appear. Also use when the user mentions…
systematic-debugging
Use when debugging a failing test, build error, or runtime issue that isn't immediately obvious. Guides a 4-phase root cause analysis instead of random fix attempts.
diagnose
Trace from a reproduced symptom to the source code that causes it. Pin the specific file and approximate line, rate confidence in the cause and clarity of the fix independently, and always propose a concrete fix.
repro-admin
Reproduce an EmDash admin UI bug. Attach a container, start the demo dev server, drive the admin with agent-browser using the dev-bypass session, and capture the reproduction as screenshots plus a replayable transcript.
log-error-digest
Analyze log files to troubleshoot errors, identify peak error periods, and produce error clustering, frequency statistics, and time distribution reports. Supports JSON, syslog, and Nginx formats with automatic detection. Use when a user uploads a .log file and asks to analyze errors, find patterns, debug issues, or…
byted-util-volcengine-detect-retry
An orchestration workflow for Volcengine Cloud Detect, a service that checks websites or network endpoints from test locations.