OpenParable
Skip to content
← Back to skills

Logseq Debug Workflow

Testing & Quality
logseq-debug-workflow

Logseq 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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
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:

  1. 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
  2. Reproduce the bug in runtime REPL before editing code.
  3. Capture concrete evidence from that runtime: REPL output, CLI output, logs, or a failing test that matches the real runtime path.
  4. Check relevant logs early.
  5. Apply the smallest justified fix.
  6. Re-run the same reproduction flow after the fix and capture evidence again.
  7. 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:

  1. Runtime chosen — which runtime REPL you used and why
  2. Pre-fix reproduction — reproduce bug in runtime REPL, exact steps and evidence
  3. Root cause — concrete cause and relevant files/flow
  4. Fix applied — short description of the change
  5. Post-fix verification — same steps again with new evidence
  6. Additional verification — tests/checks run, and what was not verified
  7. 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.