Troubleshooting

Use this page to restore progress when something blocks the loop. Each entry follows symptom → inferred state → primary recovery.

Symptom reference

Slash command not recognized

Symptom: /lamina-init, /lamina-design, or /lamina-verify is not recognized.

Inferred state: The Lamina skill is not loaded in the current agent session.

Primary recovery:

1. Install or re-install in your shell:

2. Open the intended project root
3. Start a fresh agent session
4. Run /lamina-init directly — do not treat /lamina as a required setup step

Init gate blocked

Symptom: Lamina returns an init-blocked message and stops before design or verify.

Inferred state: Missing or invalid .lamina/business-context.md — the design/verify init gate checks this file specifically.

Primary recovery:

1. Run /lamina-init <your domain description> in agent chat
2. Confirm .lamina/business-context.md exists and is valid; successful init also produces .lamina/personas.json
3. Retry your design or verify command

Wrong project root

Symptom: Init artifacts appear in an unexpected directory, or design/verify cannot find context.

Inferred state: The agent session was not anchored to the intended project root.

Primary recovery:

1. Open the correct project root in your coding agent
2. Start a fresh session
3. Run /lamina-init there

Design scope too vague

Symptom: Design pauses repeatedly or never reaches ready_to_build.

Inferred state: The requested slice lacks a usable user, outcome, or boundary.

Primary recovery:

1. Narrow the request to one coherent flow (for example “guest checkout with payment hold”)
2. Answer blocking clarification questions
3. Re-run /lamina-design with the scoped request

Write boundary confusion

Symptom: Your agent edits application source during /lamina-init, /lamina-design, or /lamina-verify.

Inferred state: The Lamina command versus ordinary coding mode boundary was lost.

Primary recovery:

1. Stop application edits inside the Lamina command
2. Let Lamina finish its artifact (.lamina/ only)
3. Issue a separate ordinary coding prompt to implement from implement.md or apply fix.md

Verify cannot reach the app

Symptom: Connection errors during verify, or report.md shows weak grounding or coverage for the named flow.

Inferred state: The product may be unreachable at the supplied URL, the verify command omitted the bounded flow, or the audit target was too vague to ground the walk.

Primary recovery:

1. Start your dev server (npm run dev or equivalent)
2. Confirm the URL works in a browser
3. Pass the bounded flow and URL explicitly: /lamina-verify guest checkout at http://localhost:3000
4. Check for port mismatches (3000 vs 3001)

An empty or missing walkthrough/ directory alone is not a reachability failure — walkthrough evidence is optional.

For the HavenStay demo:

cd demo/hotel-booking-with-lamina
npm install && npm run db:setup && npm run dev

Shallow contract coverage

Symptom: Verify passes or reports no gap, but the live experience is clearly broken.

Inferred state: The contract or actor coverage is too shallow for the failure you see.

Primary recovery:

1. Return to /lamina-design with the missing flow, constraint, or actor
2. Implement any contract changes in ordinary coding mode
3. Re-run /lamina-verify guest checkout at http://localhost:3000

Contract vs product fixes

Symptom: Unsure whether to change app code or re-design.

Inferred state: The finding’s fix_target determines the branch.

Example contract gap: the design specified an approval gate that was never in run.json. Fix the contract, not just the app.

Example ops observation: an operational note about deployment or monitoring stays in report.md and does not require a fix loop.

See Working with findings.

Validation errors

Symptom: node .claude/skills/lamina-orchestrator/lib/validate-run.mjs reports schema errors.

Inferred state: run.json does not match the schema contract.

Primary recovery:

1. Read the error output — it lists invalid fields
2. Compare against run.json schema
3. Re-run /lamina-design to regenerate, or fix run.json manually

.gitignore guidance

Lamina artifacts are design docs. Whether to commit .lamina/ depends on your team:

Suggested .gitignore entry if excluding:

.lamina/

Next steps

• Quickstart — canonical journey back into the loop
• Installation — install and first init
• First run — completion signals and artifacts