Logseq Review Workflow

Logseq Review Workflow

Core principle

The main agent drives the review. It identifies scope, loads routing rules, launches independent read-only subagents for each review pass, collects candidate findings, validates the actionable ones, deduplicates overlap, and writes the final conclusion.

Each pass subagent collects review evidence. It must not edit files, stage changes, commit, push, or rewrite code. It returns candidate findings, evidence, checks already run, and unresolved questions to the main agent. The System Additions pass also assesses necessity, maintenance cost, and simpler alternatives, returning an inventory with dispositions separate from findings.

Review every pass through three layers:

1. Repository-wide rules — always apply shared review behavior from rules/common.md.
2. Library/runtime/tooling rules — apply when the diff uses or changes a specific library, language/runtime surface, or tooling dependency.
3. Logseq module rules — apply when the diff touches a specific product/runtime area.

Use the routing tables below to load the most specific matching rule files.

Prefer concrete findings backed by code paths, invariants, tests, or runtime behavior. Do not list speculative issues unless you can explain the failure mode and affected scenario.

Every actionable finding with an executable Logseq behavior path must be validated through at least one real Logseq interaction path before it is included in the final review. Use logseq-repl, logseq-cli, chrome, or computer-use depending on the touched surface. For implementation plans, docs-only changes, static configuration errors, missing migrations, schema/protocol invariant breaks, or other findings without an executable behavior path, validate through code paths, invariant evidence, tests, build/lint output, or documented contracts and state why runtime interaction does not apply.

Read these first

1. Root AGENTS.md for repository rules and test commands.
2. .agents/skills/logseq-i18n/SKILL.md when reviewing shipped user-facing UI text or translation dictionaries.
3. .agents/skills/logseq-cli/SKILL.md when review requires running or interpreting the Logseq CLI.
4. .agents/skills/logseq-repl/SKILL.md when review requires Desktop renderer, Electron main-process, or db-worker-node runtime checks.
5. Chrome skill when testing web-app behavior in Chrome.
6. computer-use skill when testing Desktop app UI interactions that require operating the local application window.
7. .agents/skills/logseq-debug-workflow/SKILL.md when review uncovers a bug that needs deeper runtime reproduction.

Workflow

1. Identify the review scope

Collect:

• changed files and touched namespaces
• target runtime: renderer, Electron main process, db-worker-node, CLI, mobile, server/worker, tests, docs
• changed public contracts: APIs, CLI output, DB schema, frontend.worker.db.migrate/schema-version->updates, migration migrate-updates, protocol messages, translations, config, or persisted data
• dependencies and libraries involved

2. Load matching rule modules

Always read:

• rules/common.md
• rules/passes/subagent-output.md

Then read every matching module below.

Library routing

Logseq module routing

3. Launch independent pass subagents

Launch read-only pass subagents with a maximum concurrency of 4. Start the first batch of up to 4 pass subagents, wait for at least one to finish, then start the next pending pass subagent until every pass has been launched. Do not exceed 4 running pass subagents at the same time. Do not run pass subagents serially unless the environment cannot support concurrent subagents. Give every read-only subagent:

• the diff, commit range, PR, patch, or changed file list under review
• the scope collected in step 1
• rules/common.md
• rules/passes/subagent-output.md
• that pass's rule file
• any matching library/module rules relevant to that pass

Passes:

Ask each subagent to inspect only its assigned pass and return candidate findings, supporting evidence, checks already run, and unresolved questions, plus the inventory and simplification assessments for System Additions. While up to 4 subagents run in parallel, the main agent may prepare aggregation and validation steps but must keep launching pending passes as slots open and must wait for every pass report before the final review. If subagents are unavailable or concurrent launch is not possible, run each pass locally with the same rule files and state that delegation or concurrency was unavailable in the verification summary.

4. Aggregate pass results

Wait for all pass subagents before writing the final review. Then:

1. Merge all candidate findings.
2. Deduplicate overlapping reports across passes.
3. Discard findings without concrete evidence or turn them into questions.
4. Preserve the originating pass name for each retained finding.
5. Validate every actionable finding before including it.
6. Preserve the System Additions inventory and its necessity assessments separately from findings. An addition alone is not an issue, but supported simplification findings must not be discarded merely because the code works or has no measured runtime regression.

For executable behavior paths, validate with an appropriate Logseq interaction path:

• logseq-repl for ClojureScript functions, DataScript state, importer/exporter behavior, renderer state, Electron, or worker runtime behavior.
• logseq-cli for CLI command behavior, db-worker-node graph interactions, command output, and graph mutations.
• chrome or computer-use for UI, keyboard, accessibility, browser-visible rendering, Electron window behavior, and user workflows. For findings without an executable behavior path, validate with code-path evidence, schema/protocol invariants, migration evidence, tests, build/lint output, or documented contracts. Record the exact command, REPL expression, UI workflow, or static evidence and the observed result. If no applicable check can be run, do not present the item as a confirmed finding; either continue investigating, downgrade it to a clearly labeled question, or explain the blocker.