miro-code-review

What this skill does

# Visual Code Review

Generate a comprehensive visual code review on a Miro board from a pull/merge request, local changes, or a branch comparison. Includes architecture analysis, security review, and optionally enriches with enterprise documentation. After the artifacts are created, link them back from the PR/MR description so reviewers can find them without leaving their forge.

The user provides a Miro board URL plus one source: a PR/MR number, `owner/repo#number` (or `group/project!number`), a full PR/MR URL, the keyword "local changes", or a branch name to compare against the default branch. The skill is platform-agnostic: it detects the forge from the URL or the configured git remote and uses whichever CLI is available locally.

## Workflow

### 1. Identify the source from the user's request

Determine the source type and infer the platform from the URL or configured git remote:

- A bare number → PR/MR in the current repo (infer the platform from the configured git remote: `git remote get-url origin`)
- `owner/repo#number` (or `group/project!number` for GitLab-style) → PR/MR in an external repo on the same platform as the current remote, unless a host is given
- A full URL → extract host, owner/group, repo/project, and PR/MR number from the URL; the host determines the platform
- "local changes" / uncommitted work → local diff only, no PR
- A branch name → local diff against the default branch (`main` or whatever the remote shows as default)

#### Tool selection

Pick the CLI based on what's installed and what the source points at. Do not assume `gh`. Run `command -v <cli>` to check availability before invoking:

- GitHub URLs / `github.com` remote → `gh` CLI if available
- GitLab URLs / `gitlab.com` or self-hosted GitLab → `glab` CLI if available
- If no first-party CLI is available for the detected platform, fall back to authenticated REST via `curl` using whatever credentials the user already has configured (e.g. `~/.netrc`, env var tokens like `$GITHUB_TOKEN`, `$GITLAB_TOKEN`)
- For local / branch-comparison sources, plain `git` is sufficient — no platform CLI needed

State the detected platform and tool in chat output before proceeding.

### 2. Extract Changes

Fetch two things, regardless of platform:

1. **Metadata**: title, description/body, author, list of changed files with additions/deletions per file
2. **Unified diff** of the change

Use whichever CLI matches the platform detected in §1; the JSON/text shape will differ between forges — normalize fields downstream.

**GitHub example (`gh`):**
```bash
# Current repo
gh pr view $PR_NUMBER --json title,body,author,files,additions,deletions
gh pr diff $PR_NUMBER

# External repo
gh pr view $PR_NUMBER --repo $OWNER/$REPO --json title,body,author,files,additions,deletions
gh pr diff $PR_NUMBER --repo $OWNER/$REPO
```

**GitLab example (`glab`):**
```bash
# Current project
glab mr view $MR_NUMBER -F json
glab mr diff $MR_NUMBER

# External project
glab mr view $MR_NUMBER -R $GROUP/$PROJECT -F json
glab mr diff $MR_NUMBER -R $GROUP/$PROJECT
```

**REST fallback (any platform):** issue an authenticated `curl` to the platform's REST endpoint for the PR/MR and its diff. Use the user's configured token (`$GITHUB_TOKEN`, `$GITLAB_TOKEN`, etc.) and pass `Accept: application/vnd.github.v3.diff` (or platform equivalent) for the diff.

**For Local Changes:**
```bash
git status --porcelain
git diff HEAD
```

**For Branch Comparison:**
```bash
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git log $DEFAULT_BRANCH..HEAD --oneline
git diff $DEFAULT_BRANCH...HEAD
```

#### Determine the source-link base URL

Capture once and reuse for every file reference in §5 (table cells, document bullets, diagram labels). Pin links to the head SHA so they survive force-pushes. Record:

- `LINK_HOST`, `LINK_OWNER`/`LINK_REPO` (or `LINK_GROUP`/`LINK_PROJECT`) — from §1
- `LINK_SHA` — PR/MR head commit SHA (fall back to `git rev-parse HEAD` for local/branch sources)
- `LINK_BASE_SHA` — base commit SHA (PR/MR target tip, or `git merge-base` for branch comparisons); required by §5 "Showing change". If unreachable, skip "before" diagrams and announce once in chat.
- `LINK_TEMPLATE` — host-shaped blob URL with a `{path}` placeholder and optional `#L<start>-L<end>` anchor. For **no-remote sources** (`local changes` or a branch with no remote/PR) set it to `""` and render plain paths — never invent URLs.

State the chosen template in chat before creating artifacts. See `references/source-links.md` for the per-platform SHA-fetch commands, URL templates by forge, and the no-remote / unreachable-base handling.

### 3. Analyze Changes

For each changed file, determine:

**Basic Analysis:**
- **Status**: Added, Modified, or Deleted
- **Change Summary**: Brief description combining what changed and review points
- **Risk Level**: See risk assessment below

**Architecture Analysis:**
- New components or modules introduced
- Dependency changes (new imports, package updates)
- Interface/API modifications
- Pattern changes (design patterns introduced or violated)
- Breaking changes requiring consumer updates

**Security Analysis:**
- Input validation and sanitization
- Authentication/authorization changes
- Sensitive data handling (logging, storage)
- Injection vulnerabilities (SQL, XSS, command)
- Cryptography usage
- Configuration security

### 4. Risk Assessment

| Risk Level | Criteria |
|------------|----------|
| **High** | Security-sensitive, auth/authz, database migrations, core business logic, breaking API changes, cryptography |
| **Medium** | API changes, configuration, shared utilities, new dependencies, data model changes |
| **Low** | Tests, documentation, styling, localization, internal refactoring |

### 4.5 Triage: decide what (if anything) to create

Every artifact must earn its place. Before doing any creation work, decide whether the PR is worth visualizing at all and which artifact types would actually help a reviewer.

**Bail-out rule.** If **all** of the following hold, create no Miro artifacts and report only in chat:

- ≤ 2 files changed, AND
- < 20 lines changed (additions + deletions combined), AND
- No file marked **High** risk in §4, AND
- No security-sensitive paths touched (auth, crypto, config, migrations).

In that case, the entire skill output is a single chat message of the form:

> PR is trivial (N files, ±M lines, no high-risk areas). Skipping Miro visualization — a board would not add review value. PR/MR description was not modified.

Skip §5 and §6 entirely.

**Value gate (per artifact).** When the bail-out does not apply, still only create an artifact if it tells a reviewer something the diff itself does not already make obvious:

- **Table** — create when ≥ 3 files changed *or* mixed risk levels exist. For 1–2 file PRs that don't bail out, skip the table.
- **Summary doc** — create when the PR has non-trivial intent that isn't already captured in the PR title/body, OR when ≥ 2 high-risk items need callouts. Skip if it would just paraphrase the PR description.
- **Architecture doc** — create only if structural changes are detected (new modules, modified public interfaces, dependency changes, breaking changes). Skip otherwise.
- **Security doc** — create only when security-sensitive paths are touched (see §3 "Security Analysis"). Never create as a checklist-only artifact.
- **Diagram** — create only when the change involves multi-component flow, control/data path changes, or structural relationships that are hard to grasp from the diff. Render as a **side-by-side before/after pair** by default (see §5 "Showing change"); use a **single annotated "after" diagram** only when the change is purely additive and touches ≤ 3 elements. Explicitly skip diagrams that would be a single node, two nodes with one arrow, or a literal restatement of the diff.

**Announce the plan in chat** before creating anything, e.g.:

> Plan: 1 table, 1 summary doc, no diagram