Skip to content

Review a doc on GitHub

This guide shows you how to review a spec doc on GitHub from your own machine. The doc can be on a branch or in a pull request.

Speccy reads the files at the head commit, with the GitHub credential it already holds. It saves no bundle: the review is the same unsaved review that speccy review --server runs, and Speccy keeps its report for 90 days.

  • Speccy can read the repo. In local mode it uses the login of gh, or the token under Admin → GitHub. In hosted mode it uses the workspace token.
  • For a full review, the roles have models. With no model on the reviewer role, the review runs lint only.
URL Speccy reviews
A file, such as .../blob/main/docs/SDD - Pay.md That spec doc.
A folder, such as .../tree/main/docs Each spec doc under the folder.
A branch or a commit Each spec doc of the repo at that commit.
A pull request, such as .../pull/42 Each spec doc that the pull request changes.

One review takes 20 spec docs at most. For more, name a folder or a doc.

The review uses the .speccy.yaml and the sidecars of the repo at that commit, and the profiles of your Speccy. A link from a doc in the review resolves to another spec doc of the same commit, and then to the bundles that Speccy holds. Thus an SDD and its PRD in one pull request read each other.

When the repo has no .speccy.yaml at that commit, the review uses the .speccy.yaml of the folder that Speccy serves. Use this to review a repo that you cannot change: put the map entries and the other keys for its docs in your local file. The repo’s own file always wins. The answer names the file that the review used: config.source is repo, local or none, and config.path is the file.

The MCP tool review_url takes the URL:

review_url { "url": "https://github.com/acme/specs/pull/42" }

The answer names the repo and the commit. It gives each doc with its verdict and its findings. Each finding has its file, relative to the dir of the doc, and its line. Hand a spec to a coding agent shows how to add the MCP server.

A pending review shows only to you, until you submit it. Use it to check the findings before the author sees them.

  1. Go to a folder where Speccy has its state and its models, such as the folder of your docs.

  2. Print the review first. This command posts nothing:

    Terminal window
    speccy action --pr https://github.com/acme/specs/pull/42 --dry-run

    The JSON has the commit, the body of the review, each comment with its path and line, and config, the .speccy.yaml that the review used.

  3. Post the pending review:

    Terminal window
    speccy action --pr https://github.com/acme/specs/pull/42 --pending

    The last line of the output names the .speccy.yaml that the review used.

  4. Open the pull request on GitHub. Edit or delete the comments, then submit the review, or discard it.

The command takes GITHUB_TOKEN, or the login of gh. Add --stages lint for a review with no model call.

The comments follow the rules of the GitHub Action:

  • A MUST finding, or a finding with a sure fix, gets a comment when its line is in the diff.
  • Each doc gets pr.inline_limit comments at most.
  • A waived finding gets no comment.
  • A MUST finding on a line outside the diff goes into the body of the review. GitHub takes a comment only on a line of the diff.

Two flags change the review:

  • --levels must,should puts each SHOULD finding on a changed line into a comment, also when it has no fix. It wins over pr.levels in .speccy.yaml.
  • --no-attribution keeps the name of Speccy out of the review: no “Speccy reviewed” line, no check line with its catalog link, and no hidden marker. It wins over pr.attribution. Speccy keeps the ID of each comment in the local state. Thus a later speccy review-prs adds to the review and does not post a comment twice. .speccy.yaml has the details.

GitHub lets a person have one pending review on a pull request at a time. When you have one, submit or discard it, then run the command again.

An SDD and its PRD often go into review at the same time, in two pull requests. A link rule such as {dir*}/SDD{rest} implements {dir*}/PRD{rest} then names a PRD that the tree of the SDD does not hold. Speccy looks for the PRD in the open pull requests of the same repo:

  1. Speccy finds the open pull requests that add or change exactly the target path. A draft pull request counts.
  2. Speccy uses the one with the latest update, and reads the PRD at its head commit.
  3. The coherence and coverage checks run against that PRD.

The body of the review says The upstream doc docs/x/PRD.md is from pull request #12 at 1a2b3c4. It is not merged. In the JSON of --dry-run, the link has pull with the number and the commit. A run note names the other pull requests that change the same path. A Build Ready verdict that depends on the PRD gets a run note that the PRD is not merged.

Run the review again after the PRD pull request gets a new commit: each review reads the PRD again. When the PRD merges, the PRD in the tree wins, and the review names no pull request. .speccy.yaml has the rules.

To review many pull requests at once, or to add to a pending review that you already have, use speccy review-prs. Review many pull requests shows how.

  • No fix loop and no carried findings. Those need a saved bundle. Add the branch as a GitHub source in the app to get them.
  • No thread and no waiver request. The sidecars of the repo still count.