review-artifact-comments v1.0.0A

Immutable. This exact content never changes and is served at /api/v1/blob/a2b14674468827a1.

---
name: review-artifact-comments
description: "Works through the review comments written into a task artifact (plan or research under .ork/tasks/TASK/): lists the open ones, asks how to proceed, then replies, resolves or hands off to iterate-plan or iterate-research, and approves the artifact once nothing is open. Use when a reviewer has commented on an artifact file or asks to address, resolve or approve its comments."
argument-hint: "[artifact file]"
user-invocable: true
allowed-tools: "Bash Read Grep Glob AskUserQuestion"
compatibility: "Claude Code 2.1.277+. Node 22+."
metadata:
  version: "1.0.0"
  author: "OrchestKit"
  complexity: "low"
  tags: "review, artifacts, comments, approval, workflow"
---

# review-artifact-comments

Comments live inside the artifact, in the block at its end (format: the create-plan skill's
`references/artifact-layout.md`). A reviewer adds one with the script or types it into the block by
hand; both are read the same way. Nothing here deletes a comment.

## Steps

1. **Pick the artifact.** Use the file given. Otherwise list the task directory and ask which one:

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" status --task-dir .ork/tasks/<task>
   ```

2. **Read the artifact in full, then its open comments:**

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" list --file <artifact> --open
   ```

3. **Ask how to proceed** unless the user already said (AskUserQuestion), for example:
   - revise the artifact from the comments (hand off to `/ork:iterate-plan` or `/ork:iterate-research`)
   - revise and resolve the comments it settles
   - investigate the comments and reply with findings, no revision
4. **Work one comment at a time.** Check the claim in the code before answering. Reply with what you
   found or changed:

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" reply   --file <artifact> --id c1 --author Claude --text "..."
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" resolve --file <artifact> --id c1 --author Claude --text "..."
   ```

   Resolve only when told to, or when the reply records a fix already made.
5. **Approve only for the reviewer, never for the author.** The approver is the reviewing seat, and
   `--ref` names the LAND message or comment id the approval rests on. The script refuses while a
   comment is open or when `--by` is the artifact's `author` (exit 1), and without `--by` or `--ref`
   (exit 2):

   ```bash
   node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" approve --file <artifact> --by <reviewer seat> --ref <LAND or comment id>
   ```

   An approved artifact with no open comment is the "phase done" signal other tools read.

## Adding a comment as a reviewer

```bash
node "${CLAUDE_SKILL_DIR}/scripts/artifact.mjs" comment --file <artifact> \
  --author "<name>" --quote "<the line it is about>" --text "<the comment>"
```

## Rules

- Never resolve or approve on your own initiative; those are the reviewer's calls.
- Never edit the comment block with Write or Edit.