Logseq Debug Workflow
Testing & Qualitylogseq-debug-workflowLogseq Debug Workflow is an Agent Skill for testing & quality published in the logseq/logseq repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Debug Logseq bugs with the right runtime, concrete before/after evidence, and end-to-end reproduction steps.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/logseq/logseq/blob/HEAD/.agents/skills/logseq-debug-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/logseq-debug-workflow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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:
:appfor renderer, DOM, UI, frontend state:electronfor main-process, BrowserWindow, IPC, app config:db-worker-nodefor worker DB behavior, worker IPC, queries, transactions- CLI for
logseqcommand 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
prncheckpoints 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
--profilebefore/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.