Folio review comments
Ingest a pull request’s tagged conversation comments (block: <label> on the first line) into review-comment/1.0.0 todos, and write them as review-comments.json. Idempotent over its previous output, whose statuses it keeps. Re-anchors every comment against the head’s blocks, following renamedFrom, and orphans a comment whose block is gone rather than dropping it.
Skills it satisfies
A skill states the capability; this Tool is one way to exercise it. Each skill’s declared input and output contract follows, where it has one.
review-comments
Reviewer comments on a folio’s edit-set, from a tagged pull-request comment to a structured todo on the review page. Covers the tag a reviewer types, how the comments are ingested into review-comment/1.0.0 todos, where the published review-comments.json comes from and when it refreshes, how a comment follows a renamed block and survives a removed one, who may change a comment’s status, and how to change this process. Use when a reviewer asks how to comment on a block, when the review page shows no comments or a wrong one, when editing the ingestion, or when a folio’s staging workflow is set up.
Source: folio-assistant-core/skills/content/content-lifecycle-ext/review-comments.md.
Also satisfied by: folio-review-comment-move, folio-review-coverage.
The skill declares no I/O contract (schemas/skills/review-comments/{input,output}.schema.json).
Inputs and outputs
Each port names a shared type by IRI, so two Tools for one skill can be checked for interchangeability.
| port | type | required | description | constraint | |
|---|---|---|---|---|---|
| in | repo | RepoFullName | yes | owner/name of the repository the pull request is in. | string · pattern ^[A-Za-z0-9][A-Za-z0-9._-]*\\/[A-Za-z0-9][A-Za-z0-9._-]*$ · A forge repository’s full name, owner/name |
| in | pr | ChangeProposalNumber | yes | The edit-set’s pull request. | integer · A change-proposal number — a pull request on GitHub, a merge request on GitLab |
| in | out | RepoPath | yes | Where to write review-comments.json. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
| in | folio | RepoPath | Read the head’s blocks from the folio’s manifests (as text; nothing is executed). Give this OR blocks. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | blocks-out | RepoPath | With folio: also write blocks.json, so a later run can anchor without checking the folio out. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | blocks | RepoPath | A published blocks.json. The comment-triggered refresh uses this, so it never checks out the pull request’s code. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | existing | RepoPath | The previous review-comments.json. Every comment in it is kept, with its status. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | commit | CommitSha | The head commit. Default GITHUB_SHA, else git rev-parse HEAD. | string · pattern ^[0-9a-f]{7,40}$ · A git commit sha, full or abbreviated (7-40 hex digits). | |
| in | todos | RepoPath | The folio’s todos graph root. Review comments committed under its todo-feedback directory, on the feature branch, win over the previously published copy. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| in | comments | RepoPath | Read comments from this JSON file instead of GitHub: offline runs and tests. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. | |
| out | review-comments | RepoPath | A folio-review-comments/v1 file whose comments are review-comment/1.0.0 todos. Its one-line summary goes to stderr. | string · pattern ^[A-Za-z0-9._][A-Za-z0-9._/-]*$ · A path relative to the repository root. No .. segments. |
Processes and tasks
Steps this Tool can carry out, because each names a skill it satisfies:
| process | step | lane | via skill |
|---|---|---|---|
| Committee review of a content change | Ingest tagged review comments | Review Coordinator | review-comments |
| Committee review of a content change | Review each slice | Review Committee | review-comments |
| Committee review of a content change | Withdraw a review comment | Review Committee | review-comments |
| Data sharing agreement document life cycle | Review the draft agreement | Reviewer (legal, policy) | review-comments |
How it is deployed and reached
- Command line. From the repository root:
bun run folio-assistant-core/scripts/review-comments.ts. - GitHub Actions. 2 workflow line(s) run its command:
| workflow | line | |
|---|---|---|
.github/workflows/folio-staging.yml | 630 | bun run "$PLATFORM_DIR/folio-assistant-core/scripts/review-comments.ts" "${TODOS_ARGS[@]}" \\ |
.github/workflows/folio-staging.yml | 1079 | bun run "$PLATFORM_DIR/folio-assistant-core/scripts/review-comments.ts" \\ |
As an API: its operation in the OpenAPI document and the MCP tool list of its layer.
| install | none |
| runtime | bun |
| network | yes |
When a host it reaches is refused:
| host / error | remedy |
|---|---|
api.github.com | none: Reviewer comments are held by GitHub; without it the review page keeps its last ingested set. |
| when to choose it | |
|---|---|
| when | A pull request that edits a folio has reviewer comments, and the review page, the heat map, or an editor needs them as structured todos anchored to blocks. |
| limits | Reads conversation comments only, not line review comments (those anchor to a file line). A reviewer’s edit to a comment after it was ingested is not re-read. Statuses are moved by review-process tasks, not by this Tool; it keeps whatever existing says. |
| cost | One paginated GitHub API call per 100 comments, plus a text walk of the manifests when folio is given. |
What it is made of
| role | file | |
|---|---|---|
| definition | folio-assistant-core/tools/folio-review-comments/folio-review-comments.ts | |
| script | folio-assistant-core/scripts/review-comments.ts |
Linked data
The Tool is published as its own JSON-LD document at its IRI, https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-comments.jsonld, partOf its layer’s document. The node below is the definition this page was drawn from, and is embedded in the page as application/ld+json.
{
"@context": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.context.jsonld",
"@id": "https://litlfred.github.io/folio-assistant/folio-assistant-core/tools/folio-review-comments.jsonld",
"@type": "https://litlfred.github.io/cat-harness/v0/ns/Tool",
"partOf": "https://litlfred.github.io/folio-assistant/folio-assistant-core/folio-assistant-core.jsonld",
"name": "folio-review-comments",
"title": "Folio review comments",
"description": "Ingest a pull request's tagged conversation comments (`block: <label>` on the first line) into `review-comment/1.0.0` todos, and write them as `review-comments.json`. Idempotent over its previous output, whose statuses it keeps. Re-anchors every comment against the head's blocks, following `renamedFrom`, and orphans a comment whose block is gone rather than dropping it.",
"install": {
"none": true
},
"invoke": {
"shell": "bun run folio-assistant-core/scripts/review-comments.ts"
},
"io": {
"inputs": [
{
"name": "repo",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoFullName",
"description": "`owner/name` of the repository the pull request is in.",
"required": true,
"arg": {
"flag": "--repo"
}
},
{
"name": "pr",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/ChangeProposalNumber",
"description": "The edit-set's pull request.",
"required": true,
"arg": {
"flag": "--pr"
}
},
{
"name": "out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Where to write `review-comments.json`.",
"required": true,
"arg": {
"flag": "--out"
}
},
{
"name": "folio",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Read the head's blocks from the folio's manifests (as text; nothing is executed). Give this OR `blocks`.",
"required": false,
"arg": {
"flag": "--folio"
}
},
{
"name": "blocks-out",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "With `folio`: also write `blocks.json`, so a later run can anchor without checking the folio out.",
"required": false,
"arg": {
"flag": "--blocks-out"
}
},
{
"name": "blocks",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "A published `blocks.json`. The comment-triggered refresh uses this, so it never checks out the pull request's code.",
"required": false,
"arg": {
"flag": "--blocks"
}
},
{
"name": "existing",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The previous `review-comments.json`. Every comment in it is kept, with its status.",
"required": false,
"arg": {
"flag": "--existing"
}
},
{
"name": "commit",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/CommitSha",
"description": "The head commit. Default `GITHUB_SHA`, else `git rev-parse HEAD`.",
"required": false,
"arg": {
"flag": "--commit"
}
},
{
"name": "todos",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "The folio's todos graph root. Review comments committed under its `todo-feedback` directory, on the feature branch, win over the previously published copy.",
"required": false,
"arg": {
"flag": "--todos"
}
},
{
"name": "comments",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "Read comments from this JSON file instead of GitHub: offline runs and tests.",
"required": false,
"arg": {
"flag": "--comments"
}
}
],
"outputs": [
{
"name": "review-comments",
"schema": "https://litlfred.github.io/folio-assistant/cat-harness/tool-types.schema.json#/$defs/RepoPath",
"description": "A `folio-review-comments/v1` file whose `comments` are `review-comment/1.0.0` todos. Its one-line summary goes to stderr."
}
]
},
"satisfies": [
"review-comments"
],
"requirements": {
"runtime": [
"bun"
],
"network": true
},
"remedies": [
{
"host": "api.github.com",
"none": "Reviewer comments are held by GitHub; without it the review page keeps its last ingested set."
}
],
"selection": {
"when": "A pull request that edits a folio has reviewer comments, and the review page, the heat map, or an editor needs them as structured todos anchored to blocks.",
"limits": "Reads conversation comments only, not line review comments (those anchor to a file line). A reviewer's edit to a comment after it was ingested is not re-read. Statuses are moved by review-process tasks, not by this Tool; it keeps whatever `existing` says.",
"cost": "One paginated GitHub API call per 100 comments, plus a text walk of the manifests when `folio` is given."
}
}