Skip to content

Doc type

Reviews

Review findings next to the code, one decision each.

A review page shows each finding under the lines it is about, in a diff the server reads from git. Each finding offers Fix in PR, Ticket or Decline with the agent’s pick starred; you choose, and send your answers back.

InstallView on GitHub
"type": "review"

Read findings next to their code. The Merged view shows each commented range of the diff with its finding right under it, in code order. Show more lines widens the excerpt.

What it’s for

For any review that ends in decisions.

Peer reviews, an agent’s own review and open PR threads all become findings with options to pick.

  • By pull request

    One section per PR: its findings, then the diff of the files they are about.

  • By area

    Your own review grouped by area or concern, diffed from the last release you reviewed.

  • GitHub threads

    A PR’s open review threads, brought in as findings with their diff comments.

  • Agent review

    An agent’s findings, each with the evidence it read and the fix it proposes.

Features

What you can do on the page.

Switch between Merged, Checklist and Diff

A bar under each PR’s title picks how its findings show. A pick made in one view shows in the others.

Step through findings in the diff

The Diff view shows the change file by file, each finding a card under its lines. A file with several counts them and steps between them.

Open a finding’s code excerpt

In Checklist, a finding opens to its file, the lines around the comment and the card, with Open in Diff view to jump there.

Decide each finding

Each finding has a size, from blocker to nit, and its options: Fix in PR, Ticket, Decline, or the real alternatives. The card and the checklist row stay in step.

Send picks that differ from the recommendation

Accept recommended takes every starred option; change the ones you disagree with. Send answers marks each pick that differs from the agent’s.

Jump from the summary table to a finding

The summary lists every finding with its size and recommendation. Click one to scroll to it.

Bring in GitHub review threads

ghthreads.py turns a PR’s open review threads into findings, each with the reviewer’s point, the agent’s reasoning and the reply it would post.

Comment on a diff line

Point at any line of the diff. The comment’s key names the diff, the file and the line, so the agent knows exactly where.

Works on every doc

Comments, revisions and approval, the same on every type.

See every shared feature

  • Accept every recommendation at once

    Accept recommended picks every starred option in one go. Change the ones you disagree with afterwards.

  • Ask for more details

    Need more details marks a question and asks the agent what is missing before you pick.

  • Compare two revisions word by word

    New, changed and removed parts are marked in place, with words struck and added.

How the agent uses it

The agent writes JSON. The server draws the page.

The agent writes each finding as a decision item, then gitdiff.py adds a diff block of the files they are about, one comment per finding. The doc stores only the repo and the commits; the server reads the diff from git.

python3 <skill>/scripts/build.py new review docs/reviews/pr-412.bluedoc.json --title "Review: #412"
python3 <skill>/scripts/gitdiff.py --repo . --base 89efd8e --head 62ccc86 --id diff-412 --title "acme-shop #412" --paths src/pricing/tiers.ts --comments /tmp/c412.json --into docs/reviews/pr-412.bluedoc.json --section pr-412 --after-block 0
python3 <skill>/scripts/build.py docs/reviews/pr-412.bluedoc.json
python3 <skill>/scripts/serve.py open docs/reviews/pr-412.bluedoc.json
acme-review-findings.bluedoc.json · a finding
{  "id": "tier-boundary",  "text": "`tierFor` gives no tier at exactly 10 or 50 units",  "sub": "Recommend fix in PR: `>` drops both thresholds. One character.",  "state": "blocker",  "stateKind": "risk",  "choices": [    { "id": "fix", "label": "Fix in PR" },    { "id": "ticket", "label": "Ticket" },    { "id": "decline", "label": "Decline" }  ],  "recommend": "fix"}
acme-review-findings.bluedoc.json · its diff
{  "type": "diff",  "id": "diff-412",  "title": "acme-shop #412",  "repo": "acme-shop",  "base": "89efd8e",  "head": "62ccc86",  "paths": ["src/pricing/tiers.ts", "test/tiers.test.ts"],  "comments": [    { "at": "src/pricing/tiers.ts:17", "item": "t412/tier-boundary" }  ]}

ghthreads.py --repo acme/acme-shop --pr 415 --checklist t415 turns a PR’s open review threads into findings and diff comments the same way.

Install

Pick your agent.

Each one installs the same skill from the GitHub repository.

claude plugin marketplace add andreiverdes/bluedoc
claude plugin install bluedoc@bluedoc

Inside a session the same commands are /plugin marketplace add andreiverdes/bluedoc and /plugin install bluedoc@bluedoc. Start a new session to load the skill.

Needs: Python 3.9 or later on PATH · git, for code reviews · gh, only to import GitHub review threads.

View on GitHub

Other doc types

Six more kinds of page.