werkrevisor/docs/prs/2026-10-23-PR#134-draft-review-open.md

PR#134: draft-review --open Shows the Report in the Browser, and the Report Names and Links Its PR

Version: minor

WARNING: This document describes only the change applied in this PR. It may already be outdated once the next PR is merged. Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

Related Links

• PR#132: tools/draft-review with a local config and an HTML report.

Problem

After tools/draft-review the human opens report.html by hand, with a path of six directories. The title of the report names only the commit, e.g. "AI review of 6d1842aa", neither the PR nor a link to it.

Non-Goals

• No change of the review.

Specification

Feature: the report opens in the browser and leads to its PR

Scenario#134.01: --open shows the report in the browser of the local config

… so that the human reads the draft without looking for its path.

• Given a local config with browser = "brave-browser"
• When the human runs tools/draft-review 343 --open
• Then report.html opens in Brave; a browser that does not start leaves the review done and names the path

Verified by

• test_draftreview.MainTest.test_open_shows_the_report_in_the_browser_of_the_local_config
• test_draftreview.MainTest.test_the_browser_command_defaults_to_xdg_open

Scenario#134.02: the title names and links the PR

… so that the human sees which PR the draft is about and reaches it with one click.

• Given a review of PR 343 at commit 6d1842aa
• When tools/review-report writes the draft
• Then its title is "AI review of PR#343 (6d1842aa)", PR#343 links the PR in Gitea, and --attach still finds the commit of the draft

Verified by

• test_reviewreport.TitleTest.test_the_title_links_the_pr_and_keeps_the_commit
• test_reviewreport.TitleTest.test_attach_reads_the_commit_from_the_new_and_the_old_title

Scenario#134.03: --open with --attach shows the posted comment

… so that the human checks the posted review right away.

• Given a checked draft of PR 343
• When the human runs tools/draft-review 343 --attach --open
• Then the posted comment opens in the browser; a browser that does not start leaves the comment posted

Verified by

• test_draftreview.MainTest.test_open_with_attach_shows_the_posted_comment
• test_draftreview.MainTest.test_a_browser_that_does_not_start_leaves_the_posted_comment_done

Solution

• werkrevisor/draftreview.py: --open starts the command of the optional key browser of the local config, or xdg-open, detached; after a review with report.html, after --attach with the URL of the posted comment. Reading the local config checks that browser is a command; a browser that does not start only prints a line, so the review or the posted comment stays done.
• werkrevisor/reviewreport.py: draft_title writes the PR with its link and the commit in parentheses; attach reads the commit from that title and from the title of older drafts.
• README.md: the key browser and the option --open.
• tools/draft-review: only its help text, which names --open and the key browser.