---
name: iago
description: Append a Mermaid diagram (sequence, flow, class, or entity-relation) to a GitHub PR's existing /review comment. Like Iago the parrot from Aladdin, this skill loudly squawks a visual summary on top of an existing review. Also triggered by /squawk. Use after the /review skill finishes, or when the user asks to add/append a diagram to a pull request review, or says "squawk". Auto-detects the most useful diagram type from the diff; accepts an explicit override.
when_to_use: Run after /review completes on a pull request, or whenever the user says "add a diagram", "append a diagram", "add mermaid", "diagram this PR", "squawk", or invokes /squawk. Also run when /review itself decides a visual would help reviewers.
argument-hint: "[pr-number] [type?] [--mode=append|comment]"
allowed-tools:
  - Bash(gh pr view *)
  - Bash(gh pr diff *)
  - Bash(gh pr list *)
  - Bash(gh api *)
  - Bash(gh auth status)
  - Bash(git diff *)
  - Bash(git log *)
  - Bash(git rev-parse *)
  - Read
  - Grep
  - Glob
---

# PR Diagrams — append Mermaid diagrams to /review output

You generate ONE Mermaid diagram that visualizes the most important change in a
pull request and append it to the existing `/review` comment on that PR (so the
diagram lives next to the rest of the review, not as a separate comment).

GitHub and GitLab natively render fenced ` ```mermaid ` code blocks, so no
external service is needed.

---

## Inputs

Parse `$ARGUMENTS` permissively:

- **PR number** — first integer-looking token. If absent, derive it:
  1. `gh pr view --json number -q .number` (current branch).
  2. If that fails, fall back to `gh pr list --head "$(git rev-parse --abbrev-ref HEAD)" --json number -q '.[0].number'`.
  3. If still unknown, ask the user.
- **Type override** — one of: `sequence`, `flow`, `class`, `er`
  (aliases: `flowchart` → `flow`, `entity-relation` / `entity` / `erd` → `er`).
  If absent, auto-detect (see below).
- **Mode** — `--mode=append` (default) or `--mode=comment`.
  `append` edits the existing /review comment; `comment` posts a new standalone comment.
  If no /review comment is found in `append` mode, fall back to `comment` and tell the user.

---

## Workflow

1. **Resolve the PR.**
   - `PR=<number>` from arguments or detection above.
   - `REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)`.

2. **Gather context.** Run in parallel where possible:
   - `gh pr view "$PR" --json title,body,files,baseRefName,headRefName,additions,deletions`
   - `gh pr diff "$PR"` (capture full diff; if it exceeds ~150 KB, fall back to `gh pr diff "$PR" --name-only` plus targeted `git diff` per file).
   - List changed files; classify each by extension and path.

3. **Pick the diagram type** (skip if user passed an override):

   Apply these rules in order — first match wins. See
   `references/diagram-selection.md` for the full rubric and tie-breakers.

   | Signal in the diff | Type |
   |---|---|
   | Migration files, schema/model changes, `*.sql`, `*.prisma`, `models/*.py`, ORM entity files | `er` |
   | New/changed classes, inheritance, interfaces, traits across ≥2 OO files | `class` |
   | Cross-service calls, new HTTP/RPC handlers, queue producers/consumers, multi-component request flow | `sequence` |
   | Control-flow / business-logic changes inside one component, new conditionals, state machines | `flow` |
   | Trivial change (docs-only, single-line fix, dependency bump, formatting) | **none — abort with a friendly note, do not post** |

4. **Build the Mermaid block.**

   Follow `references/mermaid-templates.md` for syntax patterns. Hard rules:

   - Use exactly one fenced block: ` ```mermaid ` … ` ``` `.
   - Keep it under ~40 nodes / ~60 edges. If the change is bigger, abstract — group by module/service, not by individual function.
   - Use real names from the diff (functions, classes, services, tables) — never placeholders like `ServiceA`.
   - For `sequence`: label arrows with the actual method/endpoint, mark async with `-)`, sync with `->>`.
   - For `flow`: prefer `flowchart TD`; use `{}` for decisions, `[]` for steps, `[[ ]]` for subroutines.
   - For `class`: include only classes touched by the diff plus their direct collaborators; show new members with `+` and removed with `-`.
   - For `er`: only include tables/entities touched by the migration plus their FK neighbors.
   - No HTML, no inline styles unless necessary for readability. No emoji in node labels.

5. **Wrap it.** Produce this exact block (the markers let later runs find and replace it idempotently):

   ```markdown
   <!-- iago:begin -->
   ### 🗺️ Change diagram — <type>

   _Auto-generated by [iago](https://github.com/drakulavich/iago). Edit or remove this block; it will be replaced on the next run._

   ```mermaid
   <diagram body>
   ```
   <!-- iago:end -->
   ```

6. **Append (or replace) in the /review comment.**

   Run the helper script — it handles finding the /review comment, idempotent
   replacement of any existing `iago` block, and falling back to a new
   comment if needed.

   The helper lives at `scripts/append_diagram.sh` in this skill's own
   directory. Different runtimes expose that directory differently —
   `${CLAUDE_SKILL_DIR}` in Claude Code, `${OPENCODE_SKILL_DIR}` in OpenCode,
   etc. Pick the one your runtime sets, or resolve it from the path of this
   `SKILL.md` file (typically `~/.claude/skills/iago/`,
   `~/.agents/skills/iago/`, or `~/.config/opencode/skills/iago/`).

   ```bash
   # Pick the env var your runtime sets, or substitute the absolute path:
   SKILL_DIR="${CLAUDE_SKILL_DIR:-${OPENCODE_SKILL_DIR:-$(dirname "$0")}}"
   bash "$SKILL_DIR/scripts/append_diagram.sh" \
     --repo "$REPO" \
     --pr "$PR" \
     --mode "$MODE" \
     --diagram-file "$DIAGRAM_FILE"
   ```

   Where `$DIAGRAM_FILE` is a temp file you wrote in step 5 containing the full
   wrapped block. The script:
   - Locates the most recent comment authored by the /review skill (matched via the marker `<!-- review-skill -->`, falling back to the most recent comment authored by the current user that contains the heading `## Review` or `# Review`).
   - If found and `--mode=append`: updates that comment via `gh api -X PATCH /repos/{owner}/{repo}/issues/comments/{id}`. Replaces any prior `iago:begin/end` block in place; otherwise appends the new block to the bottom.
   - If not found, or `--mode=comment`: posts a new comment via `gh pr comment`.
   - Prints the URL of the updated/created comment.

7. **Report back.** In your final message:
   - State the chosen type and why (one sentence).
   - Include the comment URL.
   - If you abstained (trivial PR), say so.

---

## Behavioral guardrails

- **Never** open a new PR, push commits, or modify code. This skill is read-only against the repo and write-only against PR comments.
- **Never** post more than one `iago` block per PR — always replace the previous one.
- If `gh` is not authenticated (`gh auth status` fails), stop and tell the user.
- If the diff is empty, stop and tell the user — there is nothing to diagram.
- If the user says "no diagram needed" or the PR is labeled `skip-diagram` / `no-diagram`, stop without posting.

---

## Examples

See `examples/` for sample outputs across all four diagram types.