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=<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.
   • 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.

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

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

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

   # 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 <!-- 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.