Decision Reviewer

Decision Reviewer

Turn a pile of open decisions into a durable, agent-readable decision log, answered asynchronously in the browser. The markdown file is the single source of truth: the UI writes decisions straight into it, the server holds no state, and the answered file becomes context for later work.

Do not use this for fewer than ~6 questions — AskUserQuestion is faster for small batches. Do use it when answers need free-text nuance, out-of-order or multi-sitting review, or when the decision log itself is a deliverable.

Session workflow

1. Research before asking. Ground every question in the actual code/docs.

Each Recommendation must state its basis; mark unchecked claims unverified — . Fewer well-grounded questions beat exhaustive coverage. The UI has a one-click "Use recommendation" button — never put an ungrounded recommendation behind it. Style rules: see REFERENCE.md. When a question is hard to grasp cold, capture the plain-language unpacking in an optional - **In plain terms:** field (renders collapsed) rather than leaving the reader to click "Explain this question" — you already did the research, so bake that clarity in up front.

1. Write the questions file. Copy TEMPLATE.md (same dir as this file) and

fill it in — do not write the format from memory. One file per topic, named -questions.md, in the project's planning dir (plans/ or docs/ if they exist, else repo root). Include the > Context: preamble — it is what the per-question Discuss chat knows about the project.

1. Validate — mandatory gate. Count the questions you wrote (N), then:

`` node /scripts/review.mjs --file --selftest --expect N ``

Fix and rerun until SELFTEST OK. A count mismatch means a question silently failed to parse — never launch the server on a failing file.

1. Launch (run in background, capture the printed URL):

`` node /scripts/review.mjs --file ``

It picks a free port, prints → http://127.0.0.1:, and auto-opens the browser on macOS. Launch it with the Bash tool's run_in_background and read the URL from the background task's output (or pin --port N and build the URL yourself — a busy port exits with "Port N is busy"). Keep track of the process: it must be stopped before any later md edits. Then end your turn, telling the user:

• the URL, and that every decision saves into `` instantly;
• nothing is lost if the server dies — relaunch and it resumes;
• the 💬 Discuss button starts a per-question chat (each message is a real

Claude API call);

• to come back and say "done" (or "review my answers") when finished —

partial is fine.

1. Harvest. When the user returns:

`` node /scripts/review.mjs --file --summary ``

Read the digest, not the whole md. Confirm how to proceed with any still-open questions, then carry the decisions into the work. Once any decision is recorded, treat existing question blocks as append-only — add new questions with fresh Qn ids; never renumber, retitle, or rewrite answered ones.

Rules

• Never edit the questions md while the server is running — the server

does read-modify-write on every save and will clobber concurrent edits. Stop the server (or finish the review) first.

• Decisions belong to the user. Never write a - **Decision:** line yourself

unless the user explicitly dictated the decision to you.

• Chat threads live in .oq/ next to the questions file. Offer to gitignore

.oq/ unless the user wants chat history versioned.

• Format grammar, CLI flags, and troubleshooting: see

[REFERENCE.md](REFERENCE.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: otaviosoares
• Source: otaviosoares/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.