| # Command-line reference | |
| Every flag both scripts accept, for the agent driving the phases or a person | |
| doing it by hand. Each tool's `SKILL.md` under `.agents/skills/` maps plain | |
| English to the common ones; this lists every flag the scripts accept and what it | |
| means, grouped by the command that takes it. | |
| ## Every command | |
| - `--version` - print the tool version and exit. | |
| - `--checkout PATH` - the clone to read from when one is used. Defaults to the | |
| current directory; when that is not a clone of the repository, the API is | |
| used instead. | |
| - `--repo owner/name` - the repository. A github.com URL is accepted too and | |
| reduced to `owner/name`. Inferred from the clone's remotes when omitted, so | |
| it is needed only where there is no clone to infer it from. | |
| ## preflight | |
| - `--remote` - force the API even when a clone is here. Without it the mode is | |
| chosen for you: a clone of the repository being triaged is used when there | |
| is one, the API otherwise. Also the way to read the branch as it is now when | |
| the clone has fallen behind and you would rather not fetch. | |
| - `--fix` - apply the items preflight marked `autofix`: fetching a base branch | |
| that has fallen behind, and restoring a shallow clone's full history. Both | |
| write to your repository, so the script does neither without this flag. The | |
| skill passes it for a stale base and reads a shallow clone through the API | |
| instead. | |
| ## select | |
| - `--older-than 18mo` - the window, as an age: `365d`, `18mo`, `2y`. Measured | |
| from last activity unless `--date-field created` is given. | |
| - `--updated-before 2025-01-01` - the window as an absolute date instead of an | |
| age, applied to whichever date field is in use. | |
| - `--date-field created` - measure the window from when a pull request was | |
| opened rather than from its last activity. Needed where a bulk update has | |
| touched every pull request; the zero-match message says so when it happens. | |
| - `--cap N` - how many to judge in one batch. Default 25, the largest size | |
| measured end to end. Gathering a pull request is expensive once; anything | |
| re-run over the same pull requests reuses the cache. | |
| - `--name X` - labels the run, so its directory and its internal per-batch | |
| report carry the name rather than only a timestamp. It does not name the | |
| window report; `--name` on `report` does that. | |
| - `--continue-from RUN_ID` or `latest` - the next batch, reusing that run's | |
| query, window, cap and scope. The pull requests that run's earlier batches | |
| judged are skipped, which is what makes batches advance. Without it a run | |
| takes every pull request in its window, earlier verdicts or not, and judges | |
| them against the base branch as it is now. | |
| - `--only-new` - skip every pull request that already has a verdict from any | |
| run. The window report then says how many others the window holds and that | |
| they were not re-checked. | |
| - `--revisit unclear` - bring back pull requests recorded with that verdict, | |
| in a continuation or an `--only-new` run. `unclear` means deferred rather | |
| than resolved, so those would otherwise never resurface. Accepts any | |
| verdict; repeatable. | |
| - `--include-triaged` - skip nothing, not even what the run's earlier batches | |
| judged. | |
| - `--base-ref REF` - the branch coverage is judged against, for a repository | |
| whose default branch cannot be detected. | |
| - `--depth quick` - record that the run is signals-only. The report renders | |
| the signals whenever no judgment has been written, so a quick run is one | |
| that stops before judging. | |
| - `--remote` - force the API; pair with `--repo`. Falling back to the API | |
| happens on its own when there is no usable clone. | |
| - Narrower selection: `--state`, `--draft`, `--label`, `--exclude-label`, | |
| `--author`, `--exclude-author`, `--review`, `--include-bots`. Note that | |
| `--label` is the GitHub label filter; the flag that names a run is `--name`. | |
| ## collect | |
| - `--run RUN_ID` - which run. | |
| - `--refetch` - throw the cached facts away and pull them again. Re-judging | |
| needs no flag: the facts are cached, so rewriting the judgment and rendering | |
| again is enough. | |
| ## signals | |
| - `--run RUN_ID` - which run. | |
| - `--remote` - read evidence through the API instead of a checkout. Blame, | |
| file contents, file existence and the tree all work, so every check works | |
| and the two modes reach the same answers. A clone is only faster and cheaper | |
| in API calls. | |
| ## report | |
| - `--run RUN_ID` - render that one batch, which is internal and stays in the | |
| cache. Omit it to render the window reports into the reports folder: one | |
| file per window per day, over every judged batch of that window, newest | |
| verdict per pull request. | |
| - `--name X` - with no `--run`, names the newest window's report | |
| `pr-triage-X-as-of-<date>.md` instead of the automatic | |
| `pr-triage-<field>-before-<cutoff>-as-of-<date>.md`. | |
| - `--out PATH` - also save a copy at that path, a file or a directory. The | |
| copy in the reports folder is kept either way. | |
| - `--no-cost` - leave out the one-line cost footer every report ends with: the | |
| tool's time and API calls over the report's batches and the size of the | |
| material the judge read. For a report handed to someone else. | |
| - `--no-strict` - render even when the judgment fails validation. Its verdicts | |
| are then left out of the state later runs read. | |
| ## cost | |
| - `--run RUN_ID` - one run; omit for everything on the repository. | |
| - `--session PATH` - a Claude Code transcript to read measured token usage | |
| from, instead of estimating it. With `--run`, the window is taken from that | |
| run. | |
| - `--since`, `--until` - the transcript window, ISO 8601 to the second, | |
| overriding the run's own. | |
| ## runs | |
| - `--limit N` - how many recent runs to list. Default 10. | |
| ## forget | |
| - `--run RUN_ID` - the run to discard, so its pull requests can be triaged | |
| again. Cached facts are kept. | |
| - `--all` - discard every run for the repository. | |
| - `--yes` - actually do it. Without it, `forget` only reports what would go. | |
| The cache is per user, not per agent. Every run under | |
| `~/.cache/matter-pr-triage/<owner>/<repo>/` belongs to whoever runs the command, | |
| including runs another agent made on the same machine, so `forget --all` removes | |
| those too. Prefer `--run` when more than one agent shares a machine. | |
| ## Environment | |
| - `MATTER_PR_TRIAGE_CACHE` - where the cache lives, instead of | |
| `~/.cache/matter-pr-triage`. Give each agent its own value to keep their | |
| runs and state apart. | |
| - `MATTER_PR_TRIAGE_REPORTS` - where reports land, instead of | |
| `~/matter-pr-triage-reports`. Both tools write there, one subfolder per | |
| repository. | |
| # matter-pr-triage-issues | |
| The sibling's flags. Its commands take `--checkout` and `--repo` exactly as | |
| above, and most take `--pr`. | |
| ## Every command | |
| - `--version` - print the tool version and exit. | |
| - `--checkout PATH` - the clone the repository is inferred from. Defaults to | |
| the current directory. | |
| - `--repo owner/name` - the repository, as `owner/name` or a github.com URL. | |
| Inferred from the clone, or from a pull request URL given to `--pr`, when | |
| omitted. | |
| - `--pr N` - the pull request: `40191`, `#40191` or its URL. One per | |
| invocation. Taken by `gather`, `report`, `cost` and `forget`. | |
| ## gather | |
| - `--candidates N` - how many inferred candidates to keep per pull request. | |
| Default 8; each one costs the judge a read. | |
| - `--refetch` - ignore the per-issue cache, which is otherwise trusted for an | |
| hour, and fetch every issue again. | |
| - `--no-search` - skip the inferred tier and the sibling matches, so only | |
| issues linked, referencing or mentioned are gathered. | |
| - `--read ISSUE` - an issue to read in full as an inferred candidate, the | |
| judge's pick from the skim list. Repeatable. | |
| ## sync | |
| - `--full` - rebuild the corpus from scratch instead of fetching what changed | |
| since the last sync. | |
| - `--closed-months N` - how far back closed issues are kept. Default 18. | |
| - `--sibling OWNER/REPO` - also keep a corpus of that repository's issues, | |
| named as `owner/name` or as the path of a clone of it, so its issues that | |
| match a pull request by content appear under Referenced elsewhere. | |
| Remembered in `siblings.json` for later syncs, and | |
| `MATTER_PR_TRIAGE_SIBLINGS`, colon-separated, names siblings the same way. | |
| Repeatable. For project-chip/connectedhomeip the natural sibling is | |
| `CHIP-Specifications/chip-test-plans`, the test plans. | |
| ## benchmark | |
| - `--sample N` - how many pull requests with formal issue links to score. | |
| Default 60. | |
| - `--seed N` - the sampling seed, so a run can be repeated or a fresh sample | |
| drawn. Default 1. | |
| - `--k N` - the read-list size recall is measured at. Default 8, the read | |
| list's default size. | |
| - `--keep-mentions` - leave the linked issue numbers in the pull request text | |
| instead of masking them, to measure the whole pipeline rather than inference | |
| alone. | |
| ## report | |
| - `--out PATH` - also save a copy at that path, a file or a directory. The | |
| copy in the reports folder is kept either way. | |
| - `--no-strict` - render even when a judgment fails validation. Its verdicts | |
| are then left out of the state later runs read. | |
| - `--no-cost` - leave out the one-line cost footer every report ends with: | |
| issues read in full, the tool's time and API calls over every gather and | |
| report for this pull request, and the size of the material the judge read. | |
| ## list | |
| - `--from-triage VERDICT` - also list the pull requests the triage report gave | |
| this verdict, `close` for the ones recommended for closing, marking which | |
| are not done yet. Repeatable. | |
| ## cost | |
| - `--pr N` - narrow the summary to one pull request's entries. Without it, | |
| every command run against the repository. | |
| ## forget | |
| - `--yes` - actually remove the pull request's dossier, judgment and report. | |
| Without it, `forget` only reports what would go. The per-issue cache is | |
| kept. |