Iago

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= from arguments or detection above.
• REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner).

1. 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.

1. 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 |

1. 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.
• Never start an unquoted node label with @. Mermaid parses [@ as

its edge-ID/shape syntax, so N[@utils/utils -> x] fails the whole diagram. Wrap the label in double quotes: N["@utils/utils -> x"]. (@ in the middle of a label is fine.)

• 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.
• Never put ; inside a sequenceDiagram message label. GitHub's Mermaid

parser treats ; as a statement separator inside sequence diagrams, so Boot-->>User: printUsage(); exit 0 is split into two statements and the trailing half breaks the diagram. Use , or split into two messages. This is the most common rendering failure in this skill — re-read your generated block and replace any ; with , in message labels before continuing.

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

```markdown

### 🗺️ Change diagram —

Auto-generated by iago. Edit or remove this block; it will be replaced on the next run._

```mermaid

```

```

1. Append (or replace) in the /review comment.

You MUST use the helper script. Do NOT call gh pr comment, gh api -X PATCH .../comments/..., or any other direct GitHub write yourself for the diagram. The script is the only sanctioned write path: it locates the right comment, idempotently replaces any prior iago block, handles new-comment fallback, and runs a deterministic Mermaid sanitizer that catches model mistakes (e.g. stray ; in sequence message labels) before posting. Bypassing it means the diagram ships unchecked and is the #1 source of broken renders.

The helper lives at scripts/post.ts in this skill's own directory (run with bun). 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/).

Required tools: bun + gh (GitHub CLI, authenticated).

``bash # Pick the env var your runtime sets, or substitute the absolute path: SKILL_DIR="${CLAUDE_SKILL_DIR:-${OPENCODE_SKILL_DIR:-$(dirname "$0")}}" bun run "$SKILL_DIR/scripts/post.ts" \ --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 `, 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.

1. 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.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: drakulavich
• Source: drakulavich/iago
• License: MIT
• Homepage: https://drakulavich.github.io/iago/

Install and usage instructions live in the source repository linked above.