| name | logseq-debug-workflow |
| description | Debug Logseq bugs with the right runtime, concrete before/after evidence, and end-to-end reproduction steps. |
Logseq Debug Workflow
Use for any Logseq bug investigation.
Core rule
Treat this as a debugging workflow, not a code-only change.
Before claiming a fix, you must:
- Choose the correct runtime repl and say why:
:app for renderer, DOM, UI, frontend state:electron for main-process, BrowserWindow, IPC, app config:db-worker-node for worker DB behavior, worker IPC, queries, transactions- CLI for
logseq command behavior
- Reproduce the bug in runtime REPL before editing code.
- Capture concrete evidence from that runtime: REPL output, CLI output, logs, or a failing test that matches the real runtime path.
- Check relevant logs early.
- Apply the smallest justified fix.
- Re-run the same reproduction flow after the fix and capture evidence again.
- Include restart/reload/reopen verification when the bug involves settings, startup, persistence, window creation, or cross-process behavior.
Do not conclude early
Do not say the bug is fixed if any of these is missing:
- pre-fix reproduction evidence
- relevant log evidence, or an explicit statement that checked logs had nothing useful
- post-fix evidence from the same runtime/path
- required end-to-end lifecycle verification
Unit tests alone are not enough when this skill applies, unless the bug is truly unit-level and you explicitly justify that.
If the environment blocks full verification, report:
- the blocker
- what you tried
- which evidence is still missing
- the strongest partial evidence you have
Debugging tools
General
- Add labeled
prn checkpoints when helpful.
- Use small REPL/eval checks.
- Use targeted tests to confirm behavior.
- Inspect only relevant inputs, branches, transformed values, outputs, and errors.
- For async flows, inspect both sides of the async boundary.
Logseq REPL
check logseq-repl skill.
When running under Codex, using the REPL is not enough for :app verification. Also use the chrome skill, open the :app target in the browser, and verify the behavior there.
Logs
Logs are evidence. Check them early for Electron, CLI, worker, IPC, async, or persistence issues.
Common locations:
tmp/desktop-app-repl/desktop-electron.log (logseq-repl skill)tmp/logseq-repl/shared-shadow-watch.log (logseq-repl skill)~/Library/Logs/Logseq/main.log~/Library/Logs/Logseq/main.old.log~/Library/Application Support/Logseq/configs.edn- graph-local
db-worker-node-<timestamp>.log
Logseq CLI
Before using logseq, load logseq-cli skill.
Required final output
The final response must include these sections or an equivalent structure:
- Runtime chosen — which runtime REPL you used and why
- Pre-fix reproduction — reproduce bug in runtime REPL, exact steps and evidence
- Root cause — concrete cause and relevant files/flow
- Fix applied — short description of the change
- Post-fix verification — same steps again with new evidence
- Additional verification — tests/checks run, and what was not verified
- Gaps or blockers — any missing evidence and why
Quick checklist
Before ending, make sure the answer is yes to all:
- Did I reproduce the bug before fixing it?
- Did I show evidence, not just claim reproduction?
- Did I inspect relevant logs?
- Did I verify in the correct runtime?
- Did I rerun the same scenario after the fix?
- Did I include both before and after evidence in the final output?
- Did I avoid claiming completion if required evidence is missing?
Verification reminders
- Never run tests, lint, build, or E2E verification in the background.
- Check logs before trusting REPL/CLI output alone.
- For performance bugs, compare
--profile before/after on the same graph and command.
- For CLI bugs, reuse the same
--graph, --data-dir, and output mode.
- For REPL debugging, verify against the intended runtime, not a stale one.
Common checks: bb dev:test -v <namespace/testcase-name>, bb dev:lint-and-test, bb dev:cli-e2e.
