How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

fix:debug - Prompt - OpenSmartRoute

Name: fix:debug
Author: helalifaker

Prompt file imported from helalifaker/budfin (.codex/prompts/fix.debug.md). Copyright stays with the author.

Internal command. Called by /fix:all automatically.

Parse the argument:

symptom: description of the error or unexpected behavior in quotes Example: "enrollment POST returns 500" Example: "pnpm test fails with TypeError in enrollment.test.ts" Example: "JWT verification fails on authenticated routes"

If missing, ask the user: "Describe the symptom you're debugging (error message, failing test, unexpected behavior)."

Step 1 — Invoke Systematic Debugging Skill

Use the Skill tool to invoke: superpowers:systematic-debugging

This skill enforces a rigorous RCA process. Follow it exactly — do not skip to a fix before the root cause is confirmed.

Step 2 — BudFin-Specific Pattern Detection

While following the debugging skill, auto-check for these common BudFin failure patterns:

Pattern 1 — TC-001 Violation (Decimal.js/number confusion)

Symptom signals: TypeError: Cannot read property 'plus', NaN, floating-point result where decimal expected Root cause: Native number used where Decimal expected, or vice versa Check: grep -n "const.*= .*+" [file] — look for + operator on monetary vars Fix: Wrap in new Decimal(x).plus(y), ensure API returns .toFixed(4) string

Pattern 2 — Prisma P2025 (record not found)

Symptom signals: PrismaClientKnownRequestError, P2025, 500 on GET/PUT/DELETE Root cause: Record not found in DB — either wrong ID, wrong tenant, or missing seed data Check: Verify the record exists with prisma.model.findFirst({ where: { id } }) Fix: Add P2025 error handling with 404 response; verify tenant isolation query

Pattern 3 — JWT Auth Failure

Symptom signals: 401 Unauthorized on protected routes, JWTInvalid, JWTExpired Root cause: Wrong key, expired token, missing authenticate preHandler, wrong preHandler order Check: Verify preHandler: [fastify.authenticate, fastify.requireRole('...')] order Fix: Ensure RS256 key loaded, token not expired, preHandler registered correctly

Pattern 4 — Prisma 6 Buffer/Uint8Array Mismatch

Symptom signals: TypeError: Expected Uint8Array, Buffer is not assignable to Uint8Array Root cause: Prisma 6 Bytes fields return Uint8Array, not Buffer Check: Search for Buffer.from( in salary/encryption code Fix: Change type annotation to Uint8Array, update any Buffer-specific operations

Pattern 5 — ESM/CJS Interop Error

Symptom signals: require() of ES Module, ERR_REQUIRE_ESM, SyntaxError: Cannot use import Root cause: Module loaded with wrong system — API uses Node16 module resolution Check: Verify "module": "Node16" in apps/api/tsconfig.json Fix: Add "type": "module" to package.json or use .mjs extension; check import syntax

Pattern 6 — Workspace Module Not Found

Symptom signals: Cannot find module '@budfin/types', Module not found: @budfin/api Root cause: pnpm workspace symlinks broken or package not built Check: ls node_modules/@budfin/ and pnpm install Fix: pnpm install from repo root; verify pnpm-workspace.yaml includes the package

Pattern 7 — Vitest Mock Isolation

Symptom signals: Tests pass individually but fail in suite, state leaks between tests Root cause: Mock state not reset between tests Check: Look for missing vi.clearAllMocks() or vi.resetAllMocks() in beforeEach Fix: Add beforeEach(() => { vi.clearAllMocks() }) to the test file

Step 3 — Systematic Debugging Protocol

Following the systematic-debugging skill:

a. Reproduce — Run the exact command or test that fails. Document the full error output.

b. Isolate — Narrow to the smallest failing unit:

# For test failures: run single test file
pnpm --filter @budfin/api exec vitest run [specific-test-file]

# For route failures: test with minimal payload
curl -X POST http://localhost:3001/api/v1/[resource] -H "..." -d '{...}'

c. Hypothesize — List 3 candidate root causes ordered by likelihood (check Pattern list above).

d. Evidence — For each hypothesis, gather evidence:

# Check logs
pnpm dev 2>&1 | grep -E "error|Error|ERROR"

# Check types
pnpm typecheck 2>&1 | grep [filename]

# Check stack trace
# Read the full error output captured in step a

e. Eliminate — Cross off hypotheses that evidence disproves.

f. Root Cause — State the confirmed root cause in one sentence.

g. Fix — Apply the minimal targeted fix to the root cause only.

h. Verify — Run the exact failing command/test again and confirm it passes.

i. Regression — Run full test suite: pnpm test

Step 4 — Output Format

## Root Cause Analysis: [symptom]

### Reproduction
Command: [exact command]
Output: [error output]

### Root Cause
[One sentence: confirmed cause with file:line reference]

### Evidence
[Log excerpt, stack trace, or type error that proves the root cause]

### Fix Applied
Files changed:
  [file:line] — [description of change]

### Verification
[Command output confirming the fix]

### Regression Check
pnpm test: [N/N tests passing]

Step 5 — If Root Cause Cannot Be Confirmed

After 3 hypotheses with no confirmation:

Root cause not confirmed after 3 hypotheses.

Hypotheses tested:
  1. [Hypothesis] — ELIMINATED (evidence: ...)
  2. [Hypothesis] — ELIMINATED (evidence: ...)
  3. [Hypothesis] — INCONCLUSIVE (needs more information)

To diagnose further, run these commands and share the output:
  [specific diagnostic command 1]
  [specific diagnostic command 2]

Install fix:debug and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

> **Internal command.** Called by `/fix:all` automatically. Parse the argument: - `symptom`: description of the error or unexpected behavior in quotes Example: `"enrollment POST returns 500"` Example: `"pnpm test fails with TypeError in enrollment.test.ts"` Example: `"JWT verification fails on authenticated routes"` If missing, ask the user: "Describe the symptom you're debugging (error message, failing test, unexpected behavior)." ## Step 1 — Invoke Systematic Debugging Skill Use the Skill tool to invoke: `superpowers:systematic-debugging` This skill enforces a rigorous RCA process. Follow it exactly — do not skip to a fix before the root cause is confirmed. ## Step 2 — BudFin-Specific Pattern Detection While following the debugging skill, auto-check for these common BudFin failure patterns: ### Pattern 1 — TC-001 Violation (Decimal.js/number confusion) **Symptom signals**: `TypeError: Cannot read property 'plus'`, `NaN`, floating-point result where decimal expected **Root cause**: Native `number` used where `Decimal` expected, or vice versa **Check**: `grep -n "const.*= .*+" [file]` — look for `+` operator on monetary vars **Fix**: Wrap in `new Decimal(x).plus(y)`, ensure API returns `.toFixed(4)` string ### Pattern 2 — Prisma P2025 (record not found) **Symptom signals**: `PrismaClientKnownRequestError`, `P2025`, 500 on GET/PUT/DELETE **Root cause**: Record not found in DB — either wrong ID, wrong tenant, or missing seed data **Check**: Verify the record exists with `prisma.model.findFirst({ where: { id } })` **Fix**: Add P2025 error handling with 404 response; verify tenant isolation query ### Pattern 3 — JWT Auth Failure **Symptom signals**: `401 Unauthorized` on protected routes, `JWTInvalid`, `JWTExpired` **Root cause**: Wrong key, expired token, missing `authenticate` preHandler, wrong preHandler order **Check**: Verify `preHandler: [fastify.authenticate, fastify.requireRole('...')]` order **Fix**: Ensure RS256 key loaded, token not expired, preHandler registered correctly ### Pattern 4 — Prisma 6 Buffer/Uint8Array Mismatch **Symptom signals**: `TypeError: Expected Uint8Array`, `Buffer is not assignable to Uint8Array` **Root cause**: Prisma 6 `Bytes` fields return `Uint8Array`, not `Buffer` **Check**: Search for `Buffer.from(` in salary/encryption code **Fix**: Change type annotation to `Uint8Array`, update any Buffer-specific operations ### Pattern 5 — ESM/CJS Interop Error **Symptom signals**: `require() of ES Module`, `ERR_REQUIRE_ESM`, `SyntaxError: Cannot use import` **Root cause**: Module loaded with wrong system — API uses Node16 module resolution **Check**: Verify `"module": "Node16"` in `apps/api/tsconfig.json` **Fix**: Add `"type": "module"` to package.json or use `.mjs` extension; check import syntax ### Pattern 6 — Workspace Module Not Found **Symptom signals**: `Cannot find module '@budfin/types'`, `Module not found: @budfin/api` **Root cause**: pnpm workspace symlinks broken or package not built **Check**: `ls node_modules/@budfin/` and `pnpm install` **Fix**: `pnpm install` from repo root; verify `pnpm-workspace.yaml` includes the package ### Pattern 7 — Vitest Mock Isolation **Symptom signals**: Tests pass individually but fail in suite, state leaks between tests **Root cause**: Mock state not reset between tests **Check**: Look for missing `vi.clearAllMocks()` or `vi.resetAllMocks()` in `beforeEach` **Fix**: Add `beforeEach(() => { vi.clearAllMocks() })` to the test file ## Step 3 — Systematic Debugging Protocol Following the `systematic-debugging` skill: **a. Reproduce** — Run the exact command or test that fails. Document the full error output. **b. Isolate** — Narrow to the smallest failing unit: ```bash # For test failures: run single test file pnpm --filter @budfin/api exec vitest run [specific-test-file] # For route failures: test with minimal payload curl -X POST http://localhost:3001/api/v1/[resource] -H "..." -d '{...}' ``` **c. Hypothesize** — List 3 candidate root causes ordered by likelihood (check Pattern list above). **d. Evidence** — For each hypothesis, gather evidence: ```bash # Check logs pnpm dev 2>&1 | grep -E "error|Error|ERROR" # Check types pnpm typecheck 2>&1 | grep [filename] # Check stack trace # Read the full error output captured in step a ``` **e. Eliminate** — Cross off hypotheses that evidence disproves. **f. Root Cause** — State the confirmed root cause in one sentence. **g. Fix** — Apply the minimal targeted fix to the root cause only. **h. Verify** — Run the exact failing command/test again and confirm it passes. **i. Regression** — Run full test suite: `pnpm test` ## Step 4 — Output Format ``` ## Root Cause Analysis: [symptom] ### Reproduction Command: [exact command] Output: [error output] ### Root Cause [One sentence: confirmed cause with file:line reference] ### Evidence [Log excerpt, stack trace, or type error that proves the root cause] ### Fix Applied Files changed: [file:line] — [description of change] ### Verification [Command output confirming the fix] ### Regression Check pnpm test: [N/N tests passing] ``` ## Step 5 — If Root Cause Cannot Be Confirmed After 3 hypotheses with no confirmation: ``` Root cause not confirmed after 3 hypotheses. Hypotheses tested: 1. [Hypothesis] — ELIMINATED (evidence: ...) 2. [Hypothesis] — ELIMINATED (evidence: ...) 3. [Hypothesis] — INCONCLUSIVE (needs more information) To diagnose further, run these commands and share the output: [specific diagnostic command 1] [specific diagnostic command 2] ```

{ "prompt": "> **Internal command.** Called by `/fix:all` automatically.\n\nParse the argument:\n\n- `symptom`: description of the error or unexpected behavior in quotes\n Example: `\"enrollment POST returns 500\"`\n Example: `\"pnpm test fails with TypeError in enrollment.test.ts\"`\n Example: `\"JWT verification fails on authenticated routes\"`\n\nIf missing, ask the user: \"Describe the symptom you're debugging (error message, failing test, unexpected behavior).\"\n\n## Step 1 — Invoke Systematic Debugging Skill\n\nUse the Skill tool to invoke: `superpowers:systematic-debugging`\n\nThis skill enforces a rigorous RCA process. Follow it exactly — do not skip to a fix\nbefore the root cause is confirmed.\n\n## Step 2 — BudFin-Specific Pattern Detection\n\nWhile following the debugging skill, auto-check for these common BudFin failure patterns:\n\n### Pattern 1 — TC-001 Violation (Decimal.js/number confusion)\n\n**Symptom signals**: `TypeError: Cannot read property 'plus'`, `NaN`, floating-point result where decimal expected\n**Root cause**: Native `number` used where `Decimal` expected, or vice versa\n**Check**: `grep -n \"const.*= .*+\" [file]` — look for `+` operator on monetary vars\n**Fix**: Wrap in `new Decimal(x).plus(y)`, ensure API returns `.toFixed(4)` string\n\n### Pattern 2 — Prisma P2025 (record not found)\n\n**Symptom signals**: `PrismaClientKnownRequestError`, `P2025`, 500 on GET/PUT/DELETE\n**Root cause**: Record not found in DB — either wrong ID, wrong tenant, or missing seed data\n**Check**: Verify the record exists with `prisma.model.findFirst({ where: { id } })`\n**Fix**: Add P2025 error handling with 404 response; verify tenant isolation query\n\n### Pattern 3 — JWT Auth Failure\n\n**Symptom signals**: `401 Unauthorized` on protected routes, `JWTInvalid`, `JWTExpired`\n**Root cause**: Wrong key, expired token, missing `authenticate` preHandler, wrong preHandler order\n**Check**: Verify `preHandler: [fastify.authenticate, fastify.requireRole('...')]` order\n**Fix**: Ensure RS256 key loaded, token not expired, preHandler registered correctly\n\n### Pattern 4 — Prisma 6 Buffer/Uint8Array Mismatch\n\n**Symptom signals**: `TypeError: Expected Uint8Array`, `Buffer is not assignable to Uint8Array`\n**Root cause**: Prisma 6 `Bytes` fields return `Uint8Array`, not `Buffer`\n**Check**: Search for `Buffer.from(` in salary/encryption code\n**Fix**: Change type annotation to `Uint8Array`, update any Buffer-specific operations\n\n### Pattern 5 — ESM/CJS Interop Error\n\n**Symptom signals**: `require() of ES Module`, `ERR_REQUIRE_ESM`, `SyntaxError: Cannot use import`\n**Root cause**: Module loaded with wrong system — API uses Node16 module resolution\n**Check**: Verify `\"module\": \"Node16\"` in `apps/api/tsconfig.json`\n**Fix**: Add `\"type\": \"module\"` to package.json or use `.mjs` extension; check import syntax\n\n### Pattern 6 — Workspace Module Not Found\n\n**Symptom signals**: `Cannot find module '@budfin/types'`, `Module not found: @budfin/api`\n**Root cause**: pnpm workspace symlinks broken or package not built\n**Check**: `ls node_modules/@budfin/` and `pnpm install`\n**Fix**: `pnpm install` from repo root; verify `pnpm-workspace.yaml` includes the package\n\n### Pattern 7 — Vitest Mock Isolation\n\n**Symptom signals**: Tests pass individually but fail in suite, state leaks between tests\n**Root cause**: Mock state not reset between tests\n**Check**: Look for missing `vi.clearAllMocks()` or `vi.resetAllMocks()` in `beforeEach`\n**Fix**: Add `beforeEach(() => { vi.clearAllMocks() })` to the test file\n\n## Step 3 — Systematic Debugging Protocol\n\nFollowing the `systematic-debugging` skill:\n\n**a. Reproduce** — Run the exact command or test that fails. Document the full error output.\n\n**b. Isolate** — Narrow to the smallest failing unit:\n\n```bash\n# For test failures: run single test file\npnpm --filter @budfin/api exec vitest run [specific-test-file]\n\n# For route failures: test with minimal payload\ncurl -X POST http://localhost:3001/api/v1/[resource] -H \"...\" -d '{...}'\n```\n\n**c. Hypothesize** — List 3 candidate root causes ordered by likelihood (check Pattern list above).\n\n**d. Evidence** — For each hypothesis, gather evidence:\n\n```bash\n# Check logs\npnpm dev 2>&1 | grep -E \"error|Error|ERROR\"\n\n# Check types\npnpm typecheck 2>&1 | grep [filename]\n\n# Check stack trace\n# Read the full error output captured in step a\n```\n\n**e. Eliminate** — Cross off hypotheses that evidence disproves.\n\n**f. Root Cause** — State the confirmed root cause in one sentence.\n\n**g. Fix** — Apply the minimal targeted fix to the root cause only.\n\n**h. Verify** — Run the exact failing command/test again and confirm it passes.\n\n**i. Regression** — Run full test suite: `pnpm test`\n\n## Step 4 — Output Format\n\n```\n## Root Cause Analysis: [symptom]\n\n### Reproduction\nCommand: [exact command]\nOutput: [error output]\n\n### Root Cause\n[One sentence: confirmed cause with file:line reference]\n\n### Evidence\n[Log excerpt, stack trace, or type error that proves the root cause]\n\n### Fix Applied\nFiles changed:\n [file:line] — [description of change]\n\n### Verification\n[Command output confirming the fix]\n\n### Regression Check\npnpm test: [N/N tests passing]\n```\n\n## Step 5 — If Root Cause Cannot Be Confirmed\n\nAfter 3 hypotheses with no confirmation:\n\n```\nRoot cause not confirmed after 3 hypotheses.\n\nHypotheses tested:\n 1. [Hypothesis] — ELIMINATED (evidence: ...)\n 2. [Hypothesis] — ELIMINATED (evidence: ...)\n 3. [Hypothesis] — INCONCLUSIVE (needs more information)\n\nTo diagnose further, run these commands and share the output:\n [specific diagnostic command 1]\n [specific diagnostic command 2]\n```", "variables": [], "notes": "Root cause analysis for BudFin errors. Invokes the systematic-debugging skill: reproduce → isolate → hypothesize → confirm → fix → verify → regression check. Auto-detects common BudFin failure patterns (TC-001, P2025, JWT, ESM/CJS). Usage - /fix:debug \"[symptom]\" Tools: Bash, Read, Edit, Skill. Arguments: \"[symptom description]\".", "metadata": { "source": { "provider": "github-codex-prompts", "repository": "https://github.com/helalifaker/budfin", "path": ".codex/prompts/fix.debug.md", "ref": "0ae459d12324d9c929baa7b09f783f5bc53911c6", "url": "https://github.com/helalifaker/budfin/blob/0ae459d12324d9c929baa7b09f783f5bc53911c6/.codex/prompts/fix.debug.md", "key": "helalifaker/budfin/.codex/prompts/fix.debug.md" } } }

fix:debug

About

Step 1 — Invoke Systematic Debugging Skill

Step 2 — BudFin-Specific Pattern Detection

Pattern 1 — TC-001 Violation (Decimal.js/number confusion)

Pattern 2 — Prisma P2025 (record not found)

Pattern 3 — JWT Auth Failure

Pattern 4 — Prisma 6 Buffer/Uint8Array Mismatch

Pattern 5 — ESM/CJS Interop Error

Pattern 6 — Workspace Module Not Found

Pattern 7 — Vitest Mock Isolation

Step 3 — Systematic Debugging Protocol

Step 4 — Output Format

Step 5 — If Root Cause Cannot Be Confirmed

Install fix:debug and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews