From valur-prototype
Debug a Valur prototype by finding the root cause before applying fixes. Traces code paths, matches against common prototype bugs, and verifies the fix works. Use when something is broken or behaving unexpectedly.
How this skill is triggered — by the user, by Claude, or both
Slash command
/valur-prototype:investigateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Find the root cause of a bug, then fix it. Do not guess or apply speculative fixes.
Find the root cause of a bug, then fix it. Do not guess or apply speculative fixes.
Read the error messages, stack traces, or unexpected behavior the user described. If the description is unclear, ask ONE question to clarify.
Trace the code path from the symptom back to potential causes:
server/routes/ — API endpoint logicserver/db/schema.ts — table definitions and initializationcalcs/ — financial calculation logicsrc/pages/ — page componentssrc/stores/ — Pinia state storessrc/composables/useApi.ts — API clientCheck what changed recently:
git log --oneline -20 -- <affected-files>
Confirm the bug is real and repeatable before trying to fix anything.
For API bugs, hit the endpoint directly:
curl -s http://localhost:3000/api/<endpoint> | head -20
For calculation bugs, run the function:
bun run -e "import { fn } from './calcs/<file>'; console.log(fn({...}))"
For frontend bugs, check the browser console and network tab.
If the dev server isn't running, start it with bun run dev.
Before forming a hypothesis, check if this is a known pattern:
| Bug | What you see | Fix |
|---|---|---|
| Missing column | no such column error | Add the column to CREATE TABLE in server/db/schema.ts, delete prototype.db, restart |
| Stale schema | Table has old columns after you changed the schema | Delete prototype.db and restart — SQLite won't alter existing tables with CREATE TABLE IF NOT EXISTS |
| Route not registered | 404 on API call | Add app.route("/api", yourRoutes) in server/index.ts |
| Soft-delete leak | Deleted items still appear in lists | Add WHERE is_deleted = 0 to the query |
| Decimal misuse | Financial math is slightly off | Replace native number with new Decimal() from decimal.js |
| Vite proxy miss | Frontend can't reach API, network error in browser | Check /api proxy target in vite.config.ts points to http://localhost:3000 |
| CORS error | Fetch fails in browser with CORS message | Check CORS middleware in server/index.ts |
| Pinia not reactive | UI doesn't update after data changes | Use .value on refs, or call store actions instead of mutating directly |
| Page not found | Blank page or 404 in app | Add the route to src/router.ts |
| Type mismatch | Data looks wrong silently | Check TEXT vs INTEGER in schema, and string vs number in API responses |
| Missing .gitignore | prototype.db or node_modules committed, git is slow | Create .gitignore with: node_modules/, dist/, prototype.db, .vercel/, .env |
| Validation error | 500 error when submitting empty form | Add input validation in the route handler (check required fields, return 400) |
State your hypothesis clearly: "The bug is caused by [X] because [evidence]."
Verify it before writing any fix. Add a temporary console.log at the suspected location and check:
bun run devIf the hypothesis is wrong, go back to Step 1 with the new information. Do not guess.
If 3 hypotheses fail, stop and tell the user what you tried, what you ruled out, and ask them to describe what they see when the bug happens. Sometimes the user has context you don't.
Apply the smallest change that fixes the root cause. Do not refactor adjacent code.
Before finishing, check that Valur patterns are still intact:
Decimal, not native numberid, is_deleted, created_at, updated_atVerify the fix:
bun run build — confirm no type errors were introducedWhat was wrong: [root cause, with file:line]
What was fixed: [change summary]
Verified: [how — curl output, build result, etc.]
If the fix didn't fully resolve the issue or something else looks fragile, say so.
npx claudepluginhub valur-inc/valur-prototype --plugin valur-prototypeGuides systematic debugging for broken features, errors, failed deployments, or tests: reproduce bugs, gather git/logs diagnostics, read errors, diagnose root causes before fixes.
Applies systematic root-cause analysis to debug errors, test failures, and unexpected behavior across frontend, backend, database, network, and performance.
Triages, reproduces, and fixes full-stack bugs across frontend, API, DB, queues, and infra using multi-agent orchestration and git/docker checks. For runtime errors, failed flows, or Sentry/PostHog issues.