RonanCodes/skills/completion-report

Completion Report

End-of-run artifact that answers four questions in one browser tab:

1. What ran? Branch, base, duration, PR/story count, pass/fail mix.
2. What changed? Per-PR cards with file stats, summary, CI status, mergeability.
3. What's the actual diff? Per-file unified diff, syntax-highlighted, collapsible.
4. How do I undo any piece of it? Per-file rollback command, per-PR revert command, copy-button on each.

It's a single self-contained HTML file. No backend, no build step. Open it with open and read it in the browser. The HTML is also valid for emailing or sharing.

The shape is lifted from ruizrica/agent-pi's completion-report extension (see [ai-research:agent-pi]). The novelty for our flow is making it the tail call of every autonomous coding run, so the Pushover ping carries the report path as a deep link.

When to fire

Automatic (the load-bearing case):

• End of any /ro:ralph run against a real backlog (NOT --plan-only, NOT one-shot --mode single exploration). Fires BEFORE /ro:pushover so the ping message can include the report path.
• End of any /ro:planner-worker run against a real backlog (NOT --plan-only). Same Pushover-precedes ordering.
• End of any /agentic-e2e-flow run that reached the ralph-or-planner-worker phase.

The autonomous skills call this skill explicitly. Don't invoke it from inside an autonomous-loop body — only at the tail.

Manual:

• User says "completion report", "show me what changed", "build the diff report", "what did the swarm ship", or invokes /ro:completion-report.
• After a heavy hand-rolled session when you want a single shareable artifact (commit a range, copy the report path into Slack / a PR description / a daily log).

Do NOT fire:

• Mid-loop progress checks (use git status / gh pr list — those are cheap and don't need rendering).
• Inside an active Ralph iteration (the loop body has its own per-story progress.txt).
• Sessions with zero commits or zero PRs touched (nothing to report — the skill is a no-op and will tell the user).

Output location

Per repo, gitignored:

<repo-root>/.completion-reports/<YYYY-MM-DDTHH-MM>-<slug>.html

On first invocation in a repo, append .completion-reports/ to .gitignore (idempotent — check first). The slug comes from --title (kebab-cased) or, in autonomous mode, the PRD name (--prd <name>).

After writing, print the absolute path. If --open (default unless the parent skill passes --no-open), launch with open (macOS). The user wants open, not afplay-style direct playback, per memory feedback_open_audio_files.md — same principle applies here: GUI surface, not raw process.

Range resolution

The skill needs a commit range and a PR set. Pick whichever the caller supplied; otherwise auto-detect.

Priority order:

1. --prs n1,n2,n3 — explicit PR set. Resolves range from each PR's baseRefOid..headRefOid. Best when the caller (Ralph / planner-worker) already knows which PRs it shipped.
2. --range <a>..<b> — explicit git range. Use as-is; no PR cards (only commit cards).
3. --since <duration> (e.g. 4h, 1d) — git log --since=<duration> --pretty=%H. No PR cards unless gh pr list --state merged --search "closed:>=<computed-date>" returns matches.
4. --prd <name> — read .ralph/<name>.progress.txt, extract every PR: #<n> line, treat as --prs.
5. Default (no flag): git merge-base HEAD origin/main..HEAD, PR set = gh pr list --author @me --state merged --search "closed:>=$(date -u -v-1d +%Y-%m-%d)" if gh available, otherwise empty.

If the resolved range is empty (zero commits), exit early with a one-line summary: no commits in range, nothing to report. Do NOT write an empty HTML file.

Report structure

┌────────────────────────────────────────────────────────────────┐
│ <title>                                                        │
│ <repo> @ <branch> · started <ts> · finished <ts> · <duration>  │
│ <N> PRs · <M> commits · <added>+/<removed>- lines · <files>    │
│                                                                │
│ Risk panel — flags only show if triggered:                     │
│   ⚠ schema migration touched (drizzle/, migrations/)            │
│   ⚠ env or secret changes (.env*, wrangler.toml secrets)       │
│   ⚠ deletions > 100 lines in one PR                             │
│   ⚠ lockfile-only PRs                                           │
└────────────────────────────────────────────────────────────────┘

┌─ PR #61 · ✅ merged · ✅ CI green · planner ────────────────────┐
│ Title: "feat(onboarding): add email-verification step"          │
│ Author: claude (Ralph) · Squash: 8240af6                        │
│ Files: 6 changed · +142 / -8                                    │
│ Summary: <if available from PRD/progress.txt>                   │
│                                                                 │
│ Files (click to expand diff):                                   │
│   ▸ src/auth/verify.ts             +88 / -0   [revert this file]│
│   ▸ src/auth/verify.test.ts        +42 / -0   [revert this file]│
│   ▸ db/schema.ts                   +6  / -2   [revert this file]│
│   ...                                                           │
│                                                                 │
│ Rollback this PR: git revert -m 1 8240af6                       │
└─────────────────────────────────────────────────────────────────┘

(repeat per PR / per orphan commit)

Each [revert this file] button is a one-liner clipboard copy:

git checkout <sha-before-pr>~1 -- <file>

The HTML uses <details>/<summary> for collapsible diffs, no JS framework and no external assets. Diff colouring is pure CSS: diff-to-html.sh tags each line with a class (d-add, d-del, d-hunk, d-meta, d-ctx) and the inline <style> colours them. No highlight.js, no CDN, works fully offline.

Inputs the skill consumes

| Source | Use | |---|---| | git log <range> | commit list, commit messages, timestamps | | git diff <range> per file | unified diff bodies | | git diff --stat <range> | per-file change stats | | gh pr view <n> --json title,number,state,mergeable,statusCheckRollup,author,baseRefOid,headRefOid,mergedAt,body | PR card data | | gh pr diff <n> | optional fallback when range diff is messy | | .ralph/<prd>.progress.txt | story timestamps, duration, learnings (when --prd supplied) | | .ralph/<prd>.session.md | session-level duration |

Risk-panel triggers

Surface a top-of-page warning when ANY of these match a PR or commit in range. The risks are deterministic — no LLM judgement, just file-path and stat checks:

• Schema migration touched: any path matching **/migrations/**, **/drizzle/**.sql, **/prisma/migrations/**, or commit message starting with 🗄️/migration: per the repo's emoji map.
• Env / secrets: any path matching .env*, wrangler.toml with a [[secrets]] block change, **/secrets.toml, or commit message containing secret/token/key:.
• Large deletions: any PR with > 100 lines removed in a single file.
• Lockfile-only PR: a PR whose only changed files are package-lock.json, pnpm-lock.yaml, bun.lockb, yarn.lock, or Cargo.lock.
• No tests in a feat PR: PR title starts with ✨ feat: and no path matches **/*.test.* / **/*.spec.* / tests/**.

These are warnings, not blockers — the user reads the report after the run, the gate is the merger / reviewer.

Integration with /ro:pushover

The autonomous-skill callers (Ralph, planner-worker, agentic-e2e-flow) drive this ordering:

1. Run finishes (clean or failed).
2. Caller invokes /ro:completion-report with --prd <name> (or --prs <list>) and --no-open (we don't want to pop a browser on a remote / SSH session).
3. Skill writes the HTML, prints the absolute path.
4. Caller invokes /ro:pushover with a --url file://<absolute-path> so the ping deep-links to the report.

Pushover message anatomy stays the same (state + concrete metric + next step) — the URL is supplementary, not a replacement for the message text.

If the report isn't useful (zero commits, range empty), the caller skips both the report and the URL but STILL sends the Pushover ping with state.

Manual usage

# After a heavy hand-rolled session, no flags — defaults to "since I branched from origin/main"
/ro:completion-report

# Specific PR set (e.g. cherry-picked, or PRs you reviewed today)
/ro:completion-report --prs 61,62,64 --title "auth slice — 3 PRs"

# A named PRD, after Ralph
/ro:completion-report --prd phase-2-onboarding-2026-05-06

# Custom git range, custom title
/ro:completion-report --range origin/main..HEAD --title "feature-x review"

# Don't open the browser (useful in scripts and over SSH)
/ro:completion-report --no-open

Implementation

The scripts ship under scripts/ — invoke generate.sh, don't re-implement inline. They are pure bash (no Node), portable to macOS bash 3.2, and depend only on git (plus gh/jq for PR cards, both optional).

# from the repo you want a report for
bash <skill-dir>/scripts/generate.sh --range origin/main..HEAD --title "..." --no-open

generate.sh:

1. Parses flags (--range --since --prs --prd --title --out --open/--no-open --no-ping).
2. Resolves range + PR set per the priority order above. Exits early with no commits in range, nothing to report when the range is empty.
3. Ensures .completion-reports/ is gitignored (idempotent; skipped when --out is given).
4. Writes fixed HTML chrome via literal <<'EOF' heredocs, then appends every dynamic section through html_escape / diff-to-html.sh. No template engine.
5. Echoes the absolute report path to stdout (so callers can capture it for the Pushover --url).
6. Opens the file with open unless --no-open.

Three scripts under scripts/:

• scripts/generate.sh — main entrypoint, orchestrates the steps above.
• scripts/risk-checks.sh — runs each risk-panel trigger against the resolved range, prints triggered ones as key:value lines.
• scripts/diff-to-html.sh — wraps a unified diff (on stdin) into a class-tagged <pre> block for CSS colouring.

Safe escaping (the bug this skill exists to avoid)

Diff bodies and PR titles routinely contain HTML-special (< > & " ') and shell-special ($, backtick, \, $(...)) characters. A naive cat <<EOF heredoc that interpolates diff text will both mangle the HTML and let the shell re-parse the content. The scripts never do that:

• Fixed chrome uses <<'EOF' (single-quoted delimiter, zero expansion).
• Every dynamic string is HTML-escaped via html_escape (& first, then < > " ') before it touches the document.
• Diff bodies go through diff-to-html.sh, which escapes in a single awk pass and is fed by a pipe — the shell never re-parses the text.

This is verified by a smoke test that plants a file containing <script>, & "quotes" 'apostrophes', `whoami`, and $HOME, generates a report, and confirms the HTML-special chars are entity-escaped while the shell-special chars survive verbatim.

Notes for future iterations

• A second render mode (markdown) is tempting (per feedback_artifact_format_mix.md) but defer until a real "I want to paste this into a PR description" moment surfaces. HTML wins for diffs + collapsible sections; markdown wins for inline pasting. If both end up needed, expose a --format html|md flag and reuse the same risk + range resolution.
• Don't try to embed Mermaid diagrams of the PR DAG. The DAG is visible from git log --graph and adding Mermaid drags in a renderer dependency. The HTML report is a list of changes, not a diagram of them.
• The skill's HTML works offline by design: diff colouring is plain CSS classes, no highlight.js and no CDN. If richer per-token highlighting is ever wanted, vendor highlight.js into assets/highlight.min.js and load it locally — do NOT load from a CDN (bandwidth and offline-on-plane reasons).

Sources

• Pattern lifted from ruizrica/agent-pi's completion-report extension. See ai-research:agent-pi and the article ai-research:agent-pi-medium-ruiz.
• Sibling skills: /ro:ralph, /ro:planner-worker, /ro:pushover, /ro:close-session.