Workflow — Debug
Step 5 of the Persimmon workflow. Systematic over ad-hoc: reproduce, isolate, form a hypothesis, test the cheapest hypothesis first, fix, then re-run workflow-verify.
Method
- Reproduce deterministically — exact steps, environment (local vs Railway), and the precise error text.
- Isolate — narrow to one layer (build, request, DB, auth, AI, upload).
- Hypothesize & test — cheapest check first. Change one thing at a time.
- Fix and verify — re-run the relevant
workflow-verify checks; confirm no regression.
Persimmon recurring gotchas (check these first)
| Symptom |
Likely cause |
Fix |
| Railway build fails on a page |
Page reads DB/auth() without force-dynamic; build container has no DB path |
Add export const dynamic = "force-dynamic" |
UntrustedHost from NextAuth |
Behind Railway edge without trust |
trustHost: true in auth.ts; middleware reads x-forwarded-host |
Upload fails, net::ERR_FAILED, no server log |
Bucket CORS missing the origin |
Add origin via PutBucketCorsCommand |
| Stale types/enums after schema change |
Running dev server holds old Prisma client |
Restart npm run dev after db push |
| Site reachable but domain wrong |
Container port mismatch |
Public domain targetPort must be 8080, not 3000 |
| Frequent 529 / overloaded |
Too few Claude retries |
Wrap calls with 3 retries, exp backoff (handled in ai-sdk-wrapper) |
| Vector search returns junk |
Querying filtered-subset HNSW index without the filter |
Always include the filter |
| Automation stopped on Railway |
Staged-config draft reverted live mutations |
Settings → Source → Disconnect → Reconnect |
Output
A root-cause note (1–3 lines) and the fix. Then return to workflow-verify.
Relationship to other skills
Pulls domain knowledge from infra, data, security, ai. For a general debugging discipline, the upstream superpowers:systematic-debugging skill is compatible.
1---2name: workflow-debug3description: Workflow — Debug4---56# Workflow — Debug78Step 5 of the Persimmon workflow. Systematic over ad-hoc: reproduce, isolate, form a hypothesis, test the cheapest hypothesis first, fix, then re-run `workflow-verify`.910## Method11121. **Reproduce** deterministically — exact steps, environment (local vs Railway), and the precise error text.132. **Isolate** — narrow to one layer (build, request, DB, auth, AI, upload).143. **Hypothesize & test** — cheapest check first. Change one thing at a time.154. **Fix and verify** — re-run the relevant `workflow-verify` checks; confirm no regression.1617## Persimmon recurring gotchas (check these first)1819| Symptom | Likely cause | Fix |20|---|---|---|21| Railway build fails on a page | Page reads DB/`auth()` without `force-dynamic`; build container has no DB path | Add `export const dynamic = "force-dynamic"` |22| `UntrustedHost` from NextAuth | Behind Railway edge without trust | `trustHost: true` in `auth.ts`; middleware reads `x-forwarded-host` |23| Upload fails, `net::ERR_FAILED`, no server log | Bucket CORS missing the origin | Add origin via `PutBucketCorsCommand` |24| Stale types/enums after schema change | Running dev server holds old Prisma client | Restart `npm run dev` after `db push` |25| Site reachable but domain wrong | Container port mismatch | Public domain `targetPort` must be `8080`, not 3000 |26| Frequent 529 / overloaded | Too few Claude retries | Wrap calls with 3 retries, exp backoff (handled in `ai-sdk-wrapper`) |27| Vector search returns junk | Querying filtered-subset HNSW index without the filter | Always include the filter |28| Automation stopped on Railway | Staged-config draft reverted live mutations | Settings → Source → Disconnect → Reconnect |2930## Output3132A root-cause note (1–3 lines) and the fix. Then return to `workflow-verify`.3334## Relationship to other skills3536Pulls domain knowledge from `infra`, `data`, `security`, `ai`. For a general debugging discipline, the upstream `superpowers:systematic-debugging` skill is compatible.
Persimmon-Automation-Labs