Skills: Add github-pr-mockup for local GitHub-style PR previews

AGENTS.md

@@ -6,6 +6,7 @@ This repo publishes reusable Agent Skills (`SKILL.md`), not an application.
 
 - `pr-quality/` — PR preparation and review skill
 - `qa-unit-testing/` — TypeScript unit / property / mutation testing skill
+- `github-pr-mockup/` — Local GitHub-style PR HTML preview before push
 
 Each skill directory is self-contained. Prefer editing inside one skill at a time.
 

README.md

@@ -130,10 +130,11 @@ These skills are experiments in doing exactly that.
 
 # Skills
 
-| Skill                                  | What it teaches the agent                                                                                                                                                                                                  |
-| -------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [`pr-quality`](./pr-quality)           | Prepare and review pull requests using exact diff accounting, testing evidence, blast radius analysis, implementation review, and questions designed to challenge whether the proposed solution is actually the right one. |
-| [`qa-unit-testing`](./qa-unit-testing) | Build stronger TypeScript unit tests by combining example based tests, fast-check property testing, and Stryker mutation analysis to find gaps ordinary coverage metrics miss.                                             |
+| Skill                                      | What it teaches the agent                                                                                                                                                                                                  |
+| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [`pr-quality`](./pr-quality)               | Prepare and review pull requests using exact diff accounting, testing evidence, blast radius analysis, implementation review, and questions designed to challenge whether the proposed solution is actually the right one. |
+| [`qa-unit-testing`](./qa-unit-testing)     | Build stronger TypeScript unit tests by combining example based tests, fast-check property testing, and Stryker mutation analysis to find gaps ordinary coverage metrics miss.                                             |
+| [`github-pr-mockup`](./github-pr-mockup)   | Build a local GitHub-style PR HTML mockup (title, description, full diff) so you can review a contribution before it ever reaches GitHub — especially useful for open-source forks.                                        |
 
 More skills will be added as Brian continues converting useful engineering practices into repeatable agent workflows.
 
@@ -176,6 +177,19 @@ The goal is not maximum test count or maximum coverage.
 
 The goal is tests that catch real defects.
 
+## `github-pr-mockup`
+
+Open-source contributions often need a private review pass before a PR is public.
+
+This skill builds a local HTML page that looks like GitHub's pull request UI:
+
+* PR title and Open state
+* Rendered description (Conversation tab)
+* Full unified diff with file sidebar (Files changed tab)
+* Working-tree mode (including untracked) or committed range mode
+
+Use it after drafting a body with `pr-quality`, and before `gh pr create`.
+
 ---
 
 # Installation
@@ -223,6 +237,7 @@ or:
 ```bash
 gh skill install elearningplugins/brians-agent-skills pr-quality
 gh skill install elearningplugins/brians-agent-skills qa-unit-testing
+gh skill install elearningplugins/brians-agent-skills github-pr-mockup
 ```
 
 ## Manual installation
@@ -293,3 +308,12 @@ This repository is where Brian is turning the engineering practices he wants an
 ---
 
 Created by **Brian Batt**.
+
+## Preview a PR before GitHub
+
+```text
+/github-pr-mockup
+
+Draft a PR description for this branch, then build a GitHub-style HTML mockup
+so I can review the full diff locally before opening anything.
+```

github-pr-mockup/README.md

@@ -0,0 +1,58 @@
+# GitHub PR Mockup Agent Skill
+
+Local GitHub-style pull request preview: title, rendered description, and full unified diff in an HTML page — before anything reaches GitHub.
+
+Especially useful for open-source contributions where you want a private review pass first.
+
+## Contents
+
+```text
+github-pr-mockup/
+├── SKILL.md
+├── README.md
+├── references/
+│   ├── examples.md
+│   └── script.md
+└── scripts/
+    └── build_pr_mockup.py
+```
+
+## Install
+
+Copy this directory into an Agent Skills location, e.g.:
+
+```text
+~/.cursor/skills/github-pr-mockup/
+~/.claude/skills/github-pr-mockup/
+<repo>/.cursor/skills/github-pr-mockup/
+```
+
+Or install the whole repo:
+
+```bash
+npx skills add elearningplugins/brians-agent-skills
+```
+
+## Quick use
+
+From any git repository with local changes:
+
+```bash
+python3 /path/to/github-pr-mockup/scripts/build_pr_mockup.py \
+  --title "Area: Describe the change" \
+  --body-file /tmp/pr-body.md \
+  --out /tmp/pr-mockup.html \
+  --open
+```
+
+## Suggested prompts
+
+```text
+/github-pr-mockup
+```
+
+```text
+Build a GitHub-style PR mockup for my current branch so I can review it before opening a PR.
+```
+
+Pair with `pr-quality` when you need evidence-backed PR bodies, then render with this skill.

github-pr-mockup/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: github-pr-mockup
+description: >-
+  Builds a local GitHub-style pull request HTML mockup (title, rendered description,
+  Conversation/Files changed tabs, full unified diff) from the working tree or a
+  commit range before anything is pushed. Use when the user wants a PR preview,
+  GitHub mockup, pre-PR review page, local diff review UI, or to review an
+  open-source contribution without opening a real PR yet.
+---
+
+# GitHub PR Mockup
+
+Produce a **local HTML page that looks like a GitHub pull request** so the user can review title, description, and the full diff **before** the change reaches GitHub.
+
+Especially useful for open-source forks: CLA, signed commits, maintainer norms, and first impressions matter — catch description and diff issues privately.
+
+This skill renders a preview. It does **not** open a PR, push, or comment on GitHub unless the user separately asks.
+
+## When to use
+
+- User asks for a GitHub-like PR mockup / preview / review HTML
+- Pre-flight review of an OSS contribution still on a local branch
+- Validate PR title + body + full file list before `gh pr create`
+- Pair with `pr-quality` after the body is drafted
+
+## Workflow
+
+### 1. Gather context
+
+In the target git repo:
+
+1. Detect base branch (`origin/main` / `origin/master` / local fallback).
+2. Prefer **working-tree** mode when changes are uncommitted or include untracked files (typical pre-PR state).
+3. Use **range** mode (`base...HEAD`) when commits already exist and the working tree is clean.
+4. Read the repo’s PR template (`.github/PULL_REQUEST_TEMPLATE.md` etc.) and title conventions (`Area: Summary`, Conventional Commits, etc.).
+5. Draft the PR **title** and **Markdown body** honestly. Prefer the `pr-quality` skill for evidence-backed bodies when preparing a real contribution. Never invent issue numbers or test results.
+
+### 2. Write the body to a temp file
+
+```bash
+cat > /tmp/pr-body.md <<'EOF'
+**What is this feature?**
+
+…
+
+**Which issue(s) does this PR fix?**:
+
+Fixes #12345
+EOF
+```
+
+### 3. Generate the mockup
+
+Run this skill’s script (resolve the path to this skill’s `scripts/` directory):
+
+```bash
+python3 /path/to/github-pr-mockup/scripts/build_pr_mockup.py \
+  --repo /path/to/target-repo \
+  --mode working-tree \
+  --title "Area: Short accurate title" \
+  --body-file /tmp/pr-body.md \
+  --out /tmp/pr-mockup.html \
+  --issue-url "https://github.com/org/repo/issues/12345" \
+  --evidence "+N / −M across K files · only commands you actually ran" \
+  --open
+```
+
+Range mode after commits exist:
+
+```bash
+python3 /path/to/github-pr-mockup/scripts/build_pr_mockup.py \
+  --repo /path/to/target-repo \
+  --mode range \
+  --base origin/main \
+  --title "Area: Short accurate title" \
+  --body-file /tmp/pr-body.md \
+  --out /tmp/pr-mockup.html \
+  --open
+```
+
+### 4. Deliver to the user
+
+1. Open the HTML (script `--open`, or `open` / `xdg-open`).
+2. Tell them the output path.
+3. Point them at **Conversation** (description) and **Files changed** (full diff).
+4. Do **not** create the real GitHub PR unless they ask.
+
+## Output location rules
+
+- Prefer a path **outside** the target repo (parent directory, `/tmp`, or Documents) so the mockup does not dirty `git status`.
+- If writing inside the repo is unavoidable, gitignore or delete it after review — never commit the mockup unless the user explicitly wants that.
+
+## Script behavior (do not reimplement)
+
+`scripts/build_pr_mockup.py` already:
+
+- collects unified diff + numstat (working tree includes untracked via temporary `git add -N`, then resets);
+- renders GitHub-dark UI with Conversation / Commits / Files changed tabs;
+- converts a Markdown subset (headings, lists, task lists, links, inline code, hr) for the description;
+- detects `owner/repo` from `origin` when `--slug` is omitted.
+
+Do not regenerate a one-off HTML builder in chat when this script can run.
+
+## Quality bar
+
+- Full diff of every file in scope — not a summary-only page.
+- Description must match what would be pasted into GitHub (template sections filled).
+- Banner must make clear this is a **local mockup**, not a real PR.
+- Evidence footer: only commands/results actually run.
+
+## Pairing
+
+| Skill | Role |
+| --- | --- |
+| `pr-quality` | Decide readiness; exact LOC; evidence; solution review; draft the Markdown body |
+| `github-pr-mockup` | Render that body + full diff as a GitHub-like page for human review |
+
+Typical OSS sequence: implement → verify → `pr-quality` body → **this mockup** → user reviews → signed commit / CLA / `gh pr create` when they ask.
+
+## Additional resources
+
+- Script flags: [references/script.md](references/script.md)
+- Example prompts: [references/examples.md](references/examples.md)

github-pr-mockup/references/examples.md

@@ -0,0 +1,31 @@
+# Example prompts
+
+## Open-source pre-flight
+
+```text
+Use the github-pr-mockup skill. Draft a PR description for this branch against
+upstream main using the repo template, then generate a GitHub-style HTML mockup
+I can review locally before I open anything.
+```
+
+## Working tree (uncommitted)
+
+```text
+Build a GitHub PR mockup for my current uncommitted changes. Title:
+"Build: Soft-gate typecheck for e2e-playwright". Body should follow Grafana's
+PR template and mention Fixes #129355. Open the HTML when done.
+```
+
+## After commits, before push
+
+```text
+Generate a PR mockup from origin/main...HEAD with the description in /tmp/pr-body.md.
+Write the HTML next to the clone, not inside it.
+```
+
+## Pair with pr-quality
+
+```text
+Run pr-quality to draft the PR body with exact LOC and test evidence, then
+render it with github-pr-mockup so I can review the full diff like GitHub.
+```

github-pr-mockup/references/script.md

@@ -0,0 +1,51 @@
+# Script reference: `build_pr_mockup.py`
+
+```bash
+python3 scripts/build_pr_mockup.py --help
+```
+
+## Required
+
+| Flag | Meaning |
+| --- | --- |
+| `--title` | PR title string |
+| `--out` | Output `.html` path |
+
+## Description
+
+Provide exactly one of:
+
+| Flag | Meaning |
+| --- | --- |
+| `--body-file PATH` | Markdown PR description |
+| `--body "..."` | Inline Markdown (fine for short bodies) |
+
+## Diff source
+
+| Flag | Default | Meaning |
+| --- | --- | --- |
+| `--mode working-tree` | yes | Diff `HEAD` including unstaged + untracked |
+| `--mode range` | | Diff `base...HEAD` (committed only) |
+| `--base REF` | auto for range | e.g. `origin/main` |
+| `--repo PATH` | cwd | Target repository root |
+
+Working-tree mode uses temporary `git add -N` for untracked files, then `git reset` so the index is not left dirty.
+
+## Display metadata
+
+| Flag | Meaning |
+| --- | --- |
+| `--author` | Display name (default `you`) |
+| `--slug owner/repo` | Override remote detection |
+| `--base-branch` / `--head-branch` | Branch pills in the header |
+| `--pr-number` | Fake PR number (default `XXXXX`) |
+| `--issue-url` | Linked in the mockup banner |
+| `--commit-subject` | Commits tab line |
+| `--evidence` | Plain-text footer note |
+| `--open` | Open the HTML in the default browser |
+
+## Exit codes
+
+- `0` — wrote HTML
+- `1` — no changes for the chosen mode
+- `2` — not a git repo / could not detect base