From eea6873cb7f36342545d5410fd33766861826136 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Sat, 14 Nov 2026 21:44:18 +0200 Subject: [PATCH] share the PR skill across GitHub and GitLab with a cold read The work-grown PR skill had matured past the GitHub-only one: it checks the diff with blind reader agents before writing the description, and it handles stacked PRs by targeting the parent branch. Bring that in as one shared skill with per-platform references for GitHub and public GitLab, leaving out all employer-specific tickets, hosts, and URLs. Add the two cold-reader agents the skill relies on, for both Claude Code and OpenCode. --- .../agent-cheapest-pr-cold-reader.md.tmpl | 47 +++ .../agent-mid-tier-pr-cold-reader.md.tmpl | 47 +++ .../creating-github-pull-requests/SKILL.md | 145 --------- .../skills/creating-pull-requests/SKILL.md | 286 ++++++++++++++++++ .../assets/pr-description-template.md | 8 +- .../references/github.md | 81 +++++ .../references/gitlab.md | 109 +++++++ .../scripts/nearest-parent-branch.sh | 27 ++ .../agents/cheapest-pr-cold-reader.md.tmpl | 9 + .../agents/mid-tier-pr-cold-reader.md.tmpl | 10 + .../agents/cheapest-pr-cold-reader.md.tmpl | 17 ++ .../agents/mid-tier-pr-cold-reader.md.tmpl | 18 ++ 12 files changed, 655 insertions(+), 149 deletions(-) create mode 100644 .chezmoitemplates/agent-cheapest-pr-cold-reader.md.tmpl create mode 100644 .chezmoitemplates/agent-mid-tier-pr-cold-reader.md.tmpl delete mode 100644 dot_agents/skills/creating-github-pull-requests/SKILL.md create mode 100644 dot_agents/skills/creating-pull-requests/SKILL.md rename dot_agents/skills/{creating-github-pull-requests => creating-pull-requests}/assets/pr-description-template.md (66%) create mode 100644 dot_agents/skills/creating-pull-requests/references/github.md create mode 100644 dot_agents/skills/creating-pull-requests/references/gitlab.md create mode 100755 dot_agents/skills/creating-pull-requests/scripts/nearest-parent-branch.sh create mode 100644 dot_claude/agents/cheapest-pr-cold-reader.md.tmpl create mode 100644 dot_claude/agents/mid-tier-pr-cold-reader.md.tmpl create mode 100644 private_dot_config/opencode/agents/cheapest-pr-cold-reader.md.tmpl create mode 100644 private_dot_config/opencode/agents/mid-tier-pr-cold-reader.md.tmpl diff --git a/.chezmoitemplates/agent-cheapest-pr-cold-reader.md.tmpl b/.chezmoitemplates/agent-cheapest-pr-cold-reader.md.tmpl new file mode 100644 index 00000000..648644ab --- /dev/null +++ b/.chezmoitemplates/agent-cheapest-pr-cold-reader.md.tmpl @@ -0,0 +1,47 @@ +You simulate a **cold reader** of a pull request: someone seeing this change for the +first time, with none of the author's context. Your job is to report what such a reader +can and cannot understand from the change alone. + +## What you can see + +- The **net diff** (`base...HEAD`), in one file whose absolute path is given in your prompt. + +## What you deliberately cannot see — do not assume or ask for it + +- The drafted PR description. +- Commit messages. +- Any session or chat history, or alternatives the author considered. + +Your only tool is `Read`, and you use it on that one diff file and nothing else. Read the +file in pages (`offset` / `limit`) from the first line to the last. Do not open any other +file, even one the diff names, imports, or links to. If something isn't derivable from the +diff, that *is* your finding — mark it `unclear`, not a reason to go looking for more. + +## Produce + +1. **Coverage** — whether you read the whole file. If you could not, say at which line you + stopped and why. +2. **Significance ranking** — the changes you'd call out as *key*, most significant first. + This is a fresh reader's view of what matters and becomes the candidate list for the + PR's Key Changes. Leave out trivial or mechanical edits. +3. **Per key change**, report: + - **What** changed. + - **Why** you believe it was done — your inferred intent. + - **Confidence**: high / medium / low. + - **Clarity**: `clear` (intent is derivable from the change itself) or `unclear` + (you had to guess, or couldn't tell). +4. **Could not determine** — anything whose purpose you genuinely can't infer from the diff. + +## Rules + +- Infer intent from the code, not from imagination. Don't invent a backstory. +- Separate confident reads from guesses. A confident *wrong* read is worse than an honest + "unclear" — if you're guessing, say so. +- Judge the change as it stands. Do not speculate about implementation order, rejected + approaches, or how the author got here. +- You are not given a description and must not critique one. Produce an *independent* + impression, not a review of someone else's text. + +Return structured text the caller can parse: the coverage note, then the significance +ranking, then one block per key change with the fields above, then the "could not determine" +list. diff --git a/.chezmoitemplates/agent-mid-tier-pr-cold-reader.md.tmpl b/.chezmoitemplates/agent-mid-tier-pr-cold-reader.md.tmpl new file mode 100644 index 00000000..648644ab --- /dev/null +++ b/.chezmoitemplates/agent-mid-tier-pr-cold-reader.md.tmpl @@ -0,0 +1,47 @@ +You simulate a **cold reader** of a pull request: someone seeing this change for the +first time, with none of the author's context. Your job is to report what such a reader +can and cannot understand from the change alone. + +## What you can see + +- The **net diff** (`base...HEAD`), in one file whose absolute path is given in your prompt. + +## What you deliberately cannot see — do not assume or ask for it + +- The drafted PR description. +- Commit messages. +- Any session or chat history, or alternatives the author considered. + +Your only tool is `Read`, and you use it on that one diff file and nothing else. Read the +file in pages (`offset` / `limit`) from the first line to the last. Do not open any other +file, even one the diff names, imports, or links to. If something isn't derivable from the +diff, that *is* your finding — mark it `unclear`, not a reason to go looking for more. + +## Produce + +1. **Coverage** — whether you read the whole file. If you could not, say at which line you + stopped and why. +2. **Significance ranking** — the changes you'd call out as *key*, most significant first. + This is a fresh reader's view of what matters and becomes the candidate list for the + PR's Key Changes. Leave out trivial or mechanical edits. +3. **Per key change**, report: + - **What** changed. + - **Why** you believe it was done — your inferred intent. + - **Confidence**: high / medium / low. + - **Clarity**: `clear` (intent is derivable from the change itself) or `unclear` + (you had to guess, or couldn't tell). +4. **Could not determine** — anything whose purpose you genuinely can't infer from the diff. + +## Rules + +- Infer intent from the code, not from imagination. Don't invent a backstory. +- Separate confident reads from guesses. A confident *wrong* read is worse than an honest + "unclear" — if you're guessing, say so. +- Judge the change as it stands. Do not speculate about implementation order, rejected + approaches, or how the author got here. +- You are not given a description and must not critique one. Produce an *independent* + impression, not a review of someone else's text. + +Return structured text the caller can parse: the coverage note, then the significance +ranking, then one block per key change with the fields above, then the "could not determine" +list. diff --git a/dot_agents/skills/creating-github-pull-requests/SKILL.md b/dot_agents/skills/creating-github-pull-requests/SKILL.md deleted file mode 100644 index 3b9a5d0b..00000000 --- a/dot_agents/skills/creating-github-pull-requests/SKILL.md +++ /dev/null @@ -1,145 +0,0 @@ ---- -name: creating-github-pull-requests -description: "Create GitHub Pull Requests with consistent, high-quality titles and descriptions. Use when opening a PR on GitHub — covers title formatting, summary, decision log, and before/after comparison." ---- - -# Creating GitHub Pull Requests - -Create Pull Requests on GitHub with a consistent structure that is easy to review and understand. - -## Gathering Context - -Before writing anything, collect the raw material: - -1. **Branch name** — extract any issue number (e.g., `42` from `feature/42-local-accounts`). -2. **Commits** — `git log ..HEAD --oneline` to understand the full scope. -3. **Diff against base** — `git diff ...HEAD` (or `--stat` first for an overview). For a stacked PR, `` is the parent PR branch, not the default branch. Read enough of the diff to understand what changed and why. -4. **Related context** — conversation history, plan files, or linked issues that explain motivation. - -Do not rely solely on commit messages — they often lack the bigger picture. Read the actual changes. - -All PR content must describe the net change from the base branch to `HEAD`. Do not describe intermediate implementation steps, temporary refactors made during the session, or changes elsewhere in the worktree that are not part of the branch diff. - -## Title - -Format: `: ` - -- **Type** — one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `perf`. -- **Description** — a short sentence (lowercase, no trailing period) that captures the change from the reviewer's perspective. Aim for under 72 characters total. - -Examples: -- `feat: add support for local user accounts` -- `fix: prevent duplicate webhook deliveries on retry` -- `refactor: extract payment validation into dedicated service` - -## Description Structure - -Start from [assets/pr-description-template.md](assets/pr-description-template.md). The PR body has three sections, plus an optional issue-closing line at the end. All sections use plain, direct language — no filler, no marketing. - -In the **generated PR description**, use the fixed section headings `📝 Summary` and `🔄 Before & After`. Keep `Key Decisions` plain; its subheadings carry decision-specific emoji cues. - -### Summary (required) - -3–5 lines maximum. Answer: *what changed and why does it matter?* - -Write for a reviewer who has not seen the ticket. State the problem or goal, then the approach taken. Do not list files or repeat commit messages. - -Describe only the final reviewer-visible outcome relative to the base branch. - -### Key Decisions (required) - -Each significant component or area that was added, changed, or removed gets its own `###` sub-heading under this section. Prefix the sub-heading with an emoji that signals that decision, such as `🗄️` for storage or `🧹` for cleanup. Skip the emoji rather than using a vague or misleading one. A short paragraph describes what changed and, when the rationale is not obvious from the issue alone, why. - -If a change isn't worth more than a single bullet point, it's not worth calling out here — the diff speaks for itself. - -Do not explain the order you made changes during the session unless that order is visible in the final branch state and matters to the reviewer. - -Include rationale when: -- The PR makes internal refactors or restructuring choices that are self-contained (not driven by the ticket) -- Non-obvious trade-offs or alternative approaches were considered -- The change deviates from prior patterns or conventions -- A reviewer would question the approach without explanation - -``` -## Key Decisions - -### ✅ Validation Service -Added `validation.Service` to encapsulate all input validation rules, replacing the inline checks that lived in HTTP handlers. The inline approach had zero test coverage — extracting it makes the rules unit-testable without HTTP scaffolding. - -### 🔁 Webhook Idempotency -Introduced an idempotency key on webhook delivery to prevent duplicates on retry. Chose optimistic locking over pessimistic since contention is rare and the retry cost is low. -``` - -### Before & After (required) - -A table comparing the previous state to the new state. This helps reviewers understand the net effect without reading every line of the diff. - -Each row covers one meaningful area of change. Keep cells concise — short phrases, not sentences. - -Every row must compare the base branch state to the final branch state. Never use intermediate states from the implementation process as the `Before` or `After` values. - -``` -## 🔄 Before & After - -| Area | Before | After | -|------|--------|-------| -| User creation | Only OAuth providers supported | Local username/password accounts available | -| Validation | Inline in HTTP handler | Extracted to `validation.Service` | -| Retry behavior | Webhooks re-sent on any failure | Idempotency key prevents duplicate delivery | -``` - -### Issue Link (conditional) - -If the branch name contains a GitHub issue number, add a closing keyword as the last visible line of the PR body. Reference-style link definitions may follow it. This auto-closes the issue when the PR merges. - -Always use `Closes`: `Closes #42` - -Omit this line entirely if there is no associated issue. - -## Links - -Keep full `https://...` URLs out of prose. Use reference-style links for external resources, then collect each definition once at the very bottom of the body, after the optional `Closes #` line. This keeps the review narrative concise while preserving clickable references. - -``` -See the [migration guide][migration-guide] before reviewing this change. - -Closes #42 - -[migration-guide]: https://example.com/migration-guide -``` - -Use GitHub-native `#` references for other issues and PRs in the same repository rather than full URLs or reference-style definitions. Reference another PR only when it adds review context, especially for stack dependencies. - -## Stacked PRs - -A stacked PR branch is based on another open PR branch rather than the default branch. To describe only this PR's net change, compare it with its parent branch: `git diff ...HEAD`. Do not claim parent PR changes as this PR's own. - -Still target the repository's default branch unless instructed to target the parent branch. The parent-branch diff is for accurately describing the change, not necessarily for choosing the PR target. - -Declare stack dependencies in prose because GitHub has no stable, general PR-to-PR dependency mechanism. At the start of a dependent PR's Summary, name the parent with a native reference and state the merge order, for example: `Stacked on #123. Review and merge it first.` While the parent remains open, add a line naming its dependent follow-up PRs. - -## Creating the PR - -Use the GitHub CLI: - -```bash -gh pr create --title "" --body "$(cat <<'EOF' -<description body> -EOF -)" -``` - -- Target the repository's default branch unless instructed otherwise. -- Do not add reviewers, labels, or milestones unless asked. -- Create a draft PR only when explicitly asked. -- If the branch has not been pushed yet, push it first with `git push -u origin HEAD`. - -## Anti-Patterns - -- **Restating commits** — the commit log is one click away; the description should add context the commits lack. -- **Describing session history instead of branch diff** — PR text must reflect `base...HEAD`, not the sequence of edits made while implementing the change. -- **Claiming a stacked PR's parent changes as your own** — diff against the parent branch, not the default branch, so the description covers only this PR's net change. -- **Listing every file changed** — the diff view exists for this; focus on *what* and *why*, not *where*. -- **Vague summaries** — "various improvements" or "refactor code" tells the reviewer nothing. -- **Over-long descriptions** — if the summary exceeds 5 lines, it is doing too much. Push detail into Key Decisions or Before & After. -- **Spraying PR references** — use `#<number>` only where the related PR helps a reviewer understand the change or its dependencies. diff --git a/dot_agents/skills/creating-pull-requests/SKILL.md b/dot_agents/skills/creating-pull-requests/SKILL.md new file mode 100644 index 00000000..3d2f1ae3 --- /dev/null +++ b/dot_agents/skills/creating-pull-requests/SKILL.md @@ -0,0 +1,286 @@ +--- +name: creating-pull-requests +description: "Create Pull Requests with consistent, high-quality titles and descriptions. Use when opening a PR or merge request — covers a cold read of the diff, title formatting, summary, decision log, before/after comparison, and stacked PRs. Supports GitHub and GitLab." +--- + +# Creating Pull Requests + +Create Pull Requests with a consistent structure that is easy to review and understand. + +The workflow, title format, description sections, and linking conventions in this file +apply to every hosting platform. The parts that differ per platform — the concrete +auto-link tokens, emoji syntax, description length limits, stacked-PR targeting, and the +create command — live in a per-platform reference file. + +## Select the platform + +Read the reference file for the platform you are targeting **before assembling and +creating the PR**. It carries the platform-specific syntax the rest of this skill defers +to: + +- **GitHub** → [references/github.md](references/github.md) +- **GitLab** → [references/gitlab.md](references/gitlab.md) + +If the platform is not obvious, infer it from the remote (for example, a `github.com` +remote means GitHub and a `gitlab.com` remote means GitLab) or ask. + +## Gathering Context + +Before writing anything, collect the raw material: + +1. **Branch name** - extract the issue number if present (for example, `42` from `feature/42-local-accounts`). +2. **Commits** - `git log <base>..HEAD --oneline` to understand the full scope. +3. **Diff against base** - `git diff --no-ext-diff <base>...HEAD` (or add `--stat` first for an overview). `--no-ext-diff` keeps the output git's own raw diff regardless of any external diff tool configured on the machine. Read enough of the diff to understand what changed and why. For a stacked PR, `<base>` is the parent PR's branch, not the trunk (see [Stacked PRs](#stacked-prs)). +4. **Related context** - conversation history, plan files, or linked issues that explain motivation. + +Do not rely solely on commit messages. Read the actual changes. + +All PR content must describe the net change from the base branch to `HEAD`. Do not describe intermediate implementation steps, temporary refactors made during the session, or changes elsewhere in the worktree that are not part of the branch diff. + +## Cold-Read the Diff + +Before writing the description, get an unpoisoned read of the change. You carry the whole +session in your head, so you cannot reliably tell what a reviewer will grasp from the diff +alone and what they won't — everything looks obvious to someone who lived it. A dedicated +cold reader can tell, because it sees only the change. + +1. **Stage the diff.** Create a fresh scratch folder with + `mktemp -d "${TMPDIR:-/tmp}/<project>-<branch>.XXXXXX"` and write + `git diff --no-ext-diff <base>...HEAD` to `pr-cold-read.diff` inside it. `<project>` is the + last segment of the `origin` remote URL without any trailing `.git` — not the checkout + folder's name, which in a worktree is the worktree's name. `<branch>` is the current branch + with every `/` replaced by `-`. The random suffix keeps concurrent sessions apart, even on + the same branch. `--no-ext-diff` bypasses any external diff tool configured on the machine + so the reader always gets git's own raw diff text, identical across machines. This file is + the one source of truth for both the readers and your own later judgment — do not regenerate it. + Delete the folder once the PR description is written. +2. **Run the cheapest reader.** Spawn the `cheapest-pr-cold-reader` agent and give it **only + the absolute path** of the staged file, with the instruction to read it. Its only tool is + `Read`, and its instructions keep it on that one file, so the path is all it needs — do not + paste the diff into the prompt. It is also blind by design to author context — **NEVER** + give it the draft description, commit messages, any session context, or your own summary + of or hints about the change; those are the author's narration, and once it sees them it + can no longer tell you whether the *change itself* conveys the intent. It returns a + coverage note (whether it read the whole file), a significance ranking plus, per key + change, its inferred intent, a confidence level, and a `clear`/`unclear` verdict. +3. **Escalate the residual.** Two things send work to the `mid-tier-pr-cold-reader` agent, + run on the same staged diff and equally blind: + - **Unclear items** — any change the cheapest reader marked `unclear`. + - **Size** — if the staged file is large enough to risk overflowing the cheapest reader's + context, route it to the mid tier *from the start*. Check the file's size (`wc -l`) up + front rather than spending a cheapest-tier read that cannot finish. Short of that, trust + the cheapest reader's coverage note: if it could not read the whole file, treat that + like `unclear`. + + A change the mid tier now reads as `clear` was a *capability* gap, not a genuine one — + treat it as clear. A change it still marks `unclear` is a **real gap** — the trigger to + add rationale (below). If even the mid tier reports it could not read the whole file, the + diff is too large to cold-read holistically: say so and split the PR rather than describe + it from a partial read. Do not tell either reader about the other; each must form an independent + impression. + +Then let that read drive the description: + +- **Key Decisions come from the reader's significance ranking**, not your memory of what was + hard. A fresh reader's sense of what matters is the reviewer's sense; yours is skewed toward + whatever you wrestled with. Because the reader never saw the session, its ranking cannot + carry interim-decision noise — that noise exists only in your head. +- **Add rationale where the read is `unclear`.** A real gap is the strongest signal a reviewer + needs the why, and you — having lived the change — can supply it. A `clear` change is still + surfaced if significant, but stated lean; it already carries its own why, so do not pad it. + **NEVER FABRICATE MOTIVATION.** If you genuinely don't know why a change was made either, + surface it plainly or flag it — do NOT invent a rationale to fill the gap. A made-up "why" + is worse than none: it misleads the reviewer with false confidence and is exactly the kind + of leak this whole step exists to prevent. +- **Elevate only what is in the diff.** You may promote a change the reader underweighted when + its impact isn't visible in the diff (a one-line flag flip with outsized effect). You may + **not** introduce anything absent from the diff — an interim decision that lives only in your + memory is exactly the leak this step exists to prevent. +- **Correct a confident-but-wrong read** against what you actually know. + +## Title + +Format: `<type>: <short description>` + +- **Type** - one of: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`, `ci`, `perf`. +- **Description** - a short phrase (lowercase, no trailing period) that captures the change from the reviewer's perspective. Aim for under 72 characters total. + +Examples: +- `feat: add support for local user accounts` +- `fix: prevent duplicate webhook deliveries on retry` +- `refactor: extract payment validation into dedicated service` + +## Description Structure + +Start from [assets/pr-description-template.md](assets/pr-description-template.md) and fill in the three sections. The template carries the section order, the section headings (`📝 Summary` and `🔄 Before & After` keep a fixed emoji; `## Key Decisions` stays plain and lets each decision carry its own — see below), the table shape, and a placeholder describing *what* belongs in each section — including the whole Summary, which needs no more guidance than its placeholder gives. + +Some platforms cap the description length or write emoji differently (see the platform +reference). When there is a limit, keep the body concise enough to stay under it. + +What the placeholders can't carry is *judgment* — when something is worth calling out and how to reason about it. That is what the rest of this section adds. + +### Key Decisions + +The placeholder already asks for one `###` sub-heading per significant area, and notes that a change worth no more than a bullet doesn't belong here. + +Give each decision a *live* emoji cue. The section heading itself stays plain — `## Key Decisions`, no fixed emoji — because a stock emoji says nothing about *this* PR and can actively mislead: a 🔑 reads as *security keys*, which is noise on most PRs and destroys the signal on a PR that genuinely is about keys. The signal belongs one level down. Prefix each decision's `###` sub-heading with one or more emojis chosen for *that* decision — a globe 🌍 for timezone or locale work, a database 🗄️ for storage, a broom 🧹 for a cleanup — so a reviewer skimming the list gets the gist of each entry at a glance. One emoji is usually enough; add a second only when it genuinely sharpens the meaning. Skip the emoji rather than reach for a vague one — a generic ⚙️ on every heading is as meaningless as a stock 🔑. + +Do not explain the order you made changes during the session unless that order is visible in the final branch state and matters to the reviewer. + +The [cold read](#cold-read-the-diff) already located where rationale is needed — the changes it marked `unclear`. The cases below are the usual shapes those take: +- The PR makes internal refactors or restructuring choices that are self-contained (not driven by the issue) +- Non-obvious trade-offs or alternative approaches were considered +- The change deviates from prior patterns or conventions +- A reviewer would question the approach without explanation + +Example: + +``` +## Key Decisions + +### 🌍 Set-Timezone API +Added an endpoint so a user can set their timezone explicitly, instead of the scheduler guessing it from the browser locale. + +### 🕰️🗄️ Timezone Data from a Compiled Database +Compiled the IANA timezone database into the binary rather than reading the host's zoneinfo files, so lookups stay deterministic across deployment environments. +``` + +### Before & After + +The placeholder covers the table shape and cell style. Its purpose is to show the net effect — one row per meaningful area — so a reviewer grasps the change without reading every line of the diff. Every row compares the base branch state to the final branch state; never use intermediate states from the implementation process. Example: + +``` +## 🔄 Before & After + +| Area | Before | After | +|------|--------|-------| +| User creation | Only OAuth providers supported | Local username/password accounts available | +| Validation | Inline in HTTP handler | Extracted to `validation.Service` | +| Retry behavior | Webhooks re-sent on any failure | Idempotency key prevents duplicate delivery | +``` + +### Issue Link (conditional) + +If the branch name contains an issue number, add a closing line as the last *visible* line of the PR body: `Closes #42`. Both supported platforms recognize this keyword and close the issue when the PR merges. Reference-style link definitions may follow it (see [Referencing Issues & PRs](#referencing-issues--prs)). + +Always use `Closes`. Omit this line entirely if there is no associated issue. + +## Referencing Issues & PRs + +These conventions apply on every platform. The concrete syntax — which token auto-links +an issue versus a PR, and how it renders — is in the platform reference file. + +The principle behind all of it: **keep full `https://…` URLs out of the prose.** +Inline URLs bloat the source and hurt readability. So collect external URLs into a single +definitions block at the very bottom of the body — each spelled out once — and keep the +prose itself to short labels. Reference-style links are the mechanism for that. + +``` +See the [migration guide][migration-guide] before reviewing this change. + +Closes #42 + +[migration-guide]: https://example.com/migration-guide +``` + +### Native issue and PR tokens + +Each PR host auto-links its own issues and pull requests from a short token (see the +platform reference for the exact tokens). Use the native token for same-project issues and +PRs rather than a full URL or a reference-style definition. + +- **Reference other PRs when they add context** — most often in [stacked PRs](#stacked-prs), + where the reviewer needs to know which PR this one builds on. +- **Do not spray tokens.** Auto-linked references are convenient but easy to overuse; mention + a related issue or PR only where it helps a reviewer understand the change or its + dependencies. + +### The link-definitions block + +Collect **every** reference-style definition into a single block at the very bottom of the +body, below the `Closes` line. Link definitions render as nothing, so the last *visible* line +stays `Closes #42` while each URL is spelled out exactly once. One definition per label. + +## Stacked PRs + +A **stacked PR** is one whose branch is built directly on another PR's branch instead of on +the trunk. That creates a genuine dependency: the stacked PR builds on code that is still +under review, and it cannot merge until its parent does. + +Stacking is deliberate. A feature is split so an early, self-contained part can ship first — +for reviewer load, shippability, or risk — while the parts that depend on it follow, as one +or more further PRs stacked on top. + +**Determine the parent.** The parent is whatever branch the user names. If they don't say, +reconstruct it from git locally. Git records nothing about what a branch was forked from, so +this is a best-effort inference from commit topology — reliable for a real stack, but confirm +with the user when it's ambiguous. Run the bundled helper (path relative to this skill) from +inside the target repository so it reads that repo's branches: + +```bash +bash scripts/nearest-parent-branch.sh +``` + +It ranks local branches by how few commits `HEAD` is ahead of each one's divergence point +(merge-base) and prints the closest few as `<commits-ahead> <branch>`, nearest first. The +top line is the nearest parent. For the first PR in a stack this comes back as the trunk +(nothing sits between it and `main`) — the "not stacked" case — and that still holds before +you've committed anything, when `HEAD` is still on the trunk tip. If the top two lines share +the same count the parent is genuinely ambiguous; confirm with the user rather than pick one. + +You need two things from the parent: its **branch name** (to diff against, and on some +platforms to set the target at creation) and, to declare the dependency, its **PR number** — +look that up by the parent's source branch through the platform CLI (see the platform +reference). + +**Target the nearest parent, not the trunk.** The way to make a stacked PR *independently +reviewable* — its diff showing only what it adds, not everything its parents also change — is +to aim it at the branch directly below it in the stack. Given a stack A → B → C where each +branch builds on the one before: + +- A is first in line and targets the trunk (`main`, or whatever the repo's default is). +- B targets A's branch. +- C targets B's branch. + +Aimed this way, each PR's platform diff is exactly `<parent-branch>...HEAD` — its own net +change. Aiming a stacked PR at the trunk instead would fold every ancestor's still-unmerged +changes into its diff, which is what makes it unreviewable in isolation. The platform +reference gives the flag that sets the target. + +**Describe only your own net change.** Read the parent range +(`git diff --no-ext-diff <parent-branch>...HEAD`) and let Summary, Key Decisions, and Before +& After cover only what *this* PR adds on top of its parent — never the parent's own work. + +**Declare the dependency** so a reviewer knows the stack exists and in what order it merges: + +- In the **dependent PR**, state the dependency at the **start of the Summary**, naming the + parent with the platform's native PR token — for example, "Stacked on #123 — review and + merge that first." Be explicit about merge order. +- In the **parent PR**, name the dependents too **while it is still open**, so its reviewer + knows follow-ups build on it. Once the parent merges this note is moot. + +Some platforms also have a native dependency mechanism; see the platform reference. + +**Retargeting after a merge (out of scope).** When a PR targets its parent, whatever was +targeting a merged PR must be retargeted at *its* target. In A → B → C, once A merges into +the trunk, B must be retargeted from A to the trunk, while C still targets B. This skill +covers only *creating* stacked PRs with the correct target; performing that rotation as PRs +merge is left to you. + +## Creating the PR + +1. Assemble the body from `assets/pr-description-template.md` with the sections filled in and + the link-definitions block at the bottom. +2. Follow the **Creating the PR** section of the platform reference for the exact create + command and any platform flags. + +## Anti-Patterns + +- **Restating commits** - the commit log is one click away; the description should add context the commits lack. +- **Describing session history instead of branch diff** - PR text must reflect `base...HEAD`, not the sequence of edits made while implementing the change. +- **Claiming a stacked PR's parent changes as your own** - diff against the parent branch, not the trunk, so the description covers only this PR's net change (see [Stacked PRs](#stacked-prs)). +- **Listing every file changed** - the diff view exists for this; focus on *what* and *why*, not *where*. +- **Vague summaries** - "various improvements" or "refactor code" tells the reviewer nothing. +- **Ignoring a platform's length limit** - when the platform caps description length, trim detail before creating the PR; summarize and collapse lower-value decisions instead of overflowing. +- **Over-long descriptions** - if the summary exceeds 5 lines, it is doing too much. Push detail into Key Decisions or Before & After. +- **Spraying auto-links** - overusing native issue or PR references makes a PR unreadable for humans; follow the referencing conventions above. diff --git a/dot_agents/skills/creating-github-pull-requests/assets/pr-description-template.md b/dot_agents/skills/creating-pull-requests/assets/pr-description-template.md similarity index 66% rename from dot_agents/skills/creating-github-pull-requests/assets/pr-description-template.md rename to dot_agents/skills/creating-pull-requests/assets/pr-description-template.md index 1e0b5034..e1417143 100644 --- a/dot_agents/skills/creating-github-pull-requests/assets/pr-description-template.md +++ b/dot_agents/skills/creating-pull-requests/assets/pr-description-template.md @@ -4,11 +4,11 @@ ## Key Decisions -<One ### sub-heading per significant area added, changed, or removed. If a change is worth no more than a bullet, leave it out - the diff speaks for itself.> +<One ### sub-heading per significant area added, changed, or removed. If a change is worth no more than a bullet, leave it out — the diff speaks for itself.> -### <emoji evoking this decision> <Area> +### <emoji(s) evoking this specific decision> <Area> -<What changed, and - when the rationale is not obvious from the issue - why.> +<What changed, and — when the rationale isn't obvious from the issue — why.> ## 🔄 Before & After @@ -18,5 +18,5 @@ | ------ | ---------------- | ------------ | | <area> | <previous state> | <new state> | -<!-- Add `Closes #<issue-number>` only for an associated GitHub issue. --> +<!-- Add `Closes #<issue-number>` only for an associated issue. --> <!-- Add reference-style link definitions for external URLs after the closing line. --> diff --git a/dot_agents/skills/creating-pull-requests/references/github.md b/dot_agents/skills/creating-pull-requests/references/github.md new file mode 100644 index 00000000..daceae73 --- /dev/null +++ b/dot_agents/skills/creating-pull-requests/references/github.md @@ -0,0 +1,81 @@ +# GitHub + +Platform-specific details for creating a PR on GitHub. The workflow, title format, +description sections, and linking *conventions* live in `SKILL.md`; this file supplies the +concrete syntax that only applies to GitHub. + +## Description length limit + +GitHub caps PR bodies at **65,536 characters**. A description that follows `SKILL.md` +stays far below that, so keep the body concise for readability (the anti-patterns in +`SKILL.md` still apply), not to fit a budget. + +## Auto-link tokens + +GitHub uses one token for both issues and pull requests in the same repository: + +- `#<number>` → **issue or pull request**. GitHub renders it compactly as `#123` and shows the + title on hover, so it can be used on every mention without read fatigue. No bottom-block + definition is needed for it. + +To reference an issue or PR in a **different** repository, use the fully-qualified form +`owner/repo#123`. + +``` +This is the second PR in the stack on top of #123, which extracted the +validation service. It moves the webhook handler onto that service. + +Because the handler now delegates to the service introduced in #123, the +inline retry logic could be deleted entirely. +``` + +## Closing keyword + +`Closes #42` closes the issue when the PR merges into the repository's default branch. +GitHub does not close the issue when the PR merges into another branch, such as a stack +parent. + +## Stacked PRs + +Applying the Stacked PRs section in `SKILL.md`: + +**Target the parent branch at creation.** Pass the parent's branch to `gh pr create` with +`--base <parent-branch>` (`-B`) so the PR's diff shows only its own net change. The first PR +in the stack omits this and takes the default branch as usual. + +When the parent merges and its head branch is deleted, GitHub retargets the dependent PRs to +the parent's base automatically. If the parent's branch is kept, the dependent PR must be +retargeted by hand (out of scope, see `SKILL.md`). + +**Closing keywords wait for the default branch.** GitHub ignores `Closes #42` while the PR +targets a branch other than the default branch. Still add the line as `SKILL.md` describes, +but do not promise in the description that merging this PR closes the issue. + +**Find the parent's PR number** to reference it with `#<number>`: + +```bash +gh pr list --head <parent-branch> --state open --json number --jq '.[0].number' +``` + +**Declare the dependency in prose.** GitHub has no general PR-to-PR dependency mechanism, so +follow the dependency rules in `SKILL.md` with the `#<number>` token above, for example: +"Stacked on #123 — review and merge that first." + +## Creating the PR + +Use the GitHub CLI: + +```bash +gh pr create --title "<title>" --body "$(cat <<'EOF' +<paste the assembled body from assets/pr-description-template.md> +EOF +)" +``` + +- Target the repository's default branch unless instructed otherwise or the PR is stacked; + pass `--base <branch>` to override — a stacked PR targets its parent branch (see + [Stacked PRs](#stacked-prs)). +- Do not pass `--fill` — it replaces the title and body with commit info. +- Do not add reviewers, assignees, labels, or milestones unless asked. +- Create a draft PR (`--draft`) only when explicitly asked. +- If the branch has not been pushed yet, push it first with `git push -u origin HEAD`. diff --git a/dot_agents/skills/creating-pull-requests/references/gitlab.md b/dot_agents/skills/creating-pull-requests/references/gitlab.md new file mode 100644 index 00000000..a9f386ea --- /dev/null +++ b/dot_agents/skills/creating-pull-requests/references/gitlab.md @@ -0,0 +1,109 @@ +# GitLab + +Platform-specific details for creating a PR on GitLab (`gitlab.com`). The workflow, title +format, description sections, and linking *conventions* live in `SKILL.md`; this file +supplies the concrete syntax that only applies to GitLab. + +## Terminology + +GitLab calls a pull request a **merge request** (MR), and the CLI is `glab mr`. Wherever +`SKILL.md` says "PR" — including "Stacked PRs" — read it as "merge request". Every +convention in `SKILL.md` applies unchanged; only the name differs. + +## Emoji + +GitLab renders **emoji shortcodes** — `:memo:`, `:arrows_counterclockwise:`, +`:earth_africa:` — as native inline emoji, which display more consistently than a pasted +Unicode character. So throughout the MR body, write **every** emoji as its shortcode rather +than a literal Unicode glyph. This applies to both: + +- **The template's fixed section headings.** Use `## :memo: Summary` and + `## :arrows_counterclockwise: Before & After` in place of the literal `📝` / `🔄` that + `assets/pr-description-template.md` shows. +- **The per-decision cues in Key Decisions.** Choose the emoji exactly as `SKILL.md` + describes, then write it as its shortcode — a globe cue becomes `:earth_africa:`, a + cleanup `:broom:`, a database `:card_file_box:`, and so on. + +## Description length limit + +GitLab caps MR descriptions at roughly **1,048,576 characters (1 MiB)** — effectively no +limit for our purposes. You never need to trim for length. Keep the body concise for +readability (the anti-patterns in `SKILL.md` still apply), not to fit a budget. + +## Auto-link tokens + +GitLab auto-links two reference tokens inside an MR body. Both render compactly — the +visible text stays `#42` or `!15` and the title shows only on hover — so use the raw token on +every mention. No bottom-block definition is needed for either. + +- `#<id>` → **issue**. +- `!<id>` → **merge request**. + +``` +This is the second MR in the stack on top of !15, which extracted the +validation service. It moves the webhook handler onto that service. + +Because the handler now delegates to the service introduced in !15, the +inline retry logic could be deleted entirely. +``` + +To reference an issue or MR in a **different** project, use the fully-qualified form +`group/project#42` or `group/project!15`. + +## Closing keyword + +`Closes #42` closes the issue when the MR merges into the project's default branch. + +## Stacked PRs + +GitLab has **no diff-scoping stacked-MR support** — an MR aimed at the trunk shows every +ancestor's still-unmerged changes. Applying the Stacked PRs section in `SKILL.md`: + +**Target the parent branch at creation.** Pass the parent's branch with `-b <parent-branch>` +(`--target-branch`) so the MR's diff shows only its own net change. The first MR in the stack +omits this and takes the default branch as usual. + +**Find the parent's MR number** to reference it with `!<id>`. GitLab identifies an MR by its +project-scoped `iid`; list the parent's source branch and read it: + +```bash +glab mr list --source-branch <parent-branch> -F json --jq '.[0].iid' +``` + +GitLab *also* has a native **merge request dependencies** feature (Premium and Ultimate +tiers): an MR can be marked as depending on another, and GitLab then blocks merging until the +dependency merges. This is a merge-order block, **not** diff scoping — it complements +parent-targeting, it does not replace it. When the project's tier supports it, also set the +dependent MR's "Merge request dependencies" field to the parent; there is no `glab` flag, so +set it in the MR's UI after creation. + +Whether or not the native field is available, still **declare the dependency in prose** (see +the Stacked PRs section in `SKILL.md`), linking the parent with the `!<id>` token above, for +example: "Stacked on !15 — review and merge that first." + +## Creating the PR + +Use the GitLab CLI: + +```bash +BODY="$(cat <<'EOF' +<paste the assembled body from assets/pr-description-template.md> +EOF +)" + +glab mr create \ + --title "<title>" \ + --description "$BODY" \ + --yes +``` + +- `glab` auto-detects the project and the target branch from the git remote. It targets the + project's default branch unless instructed otherwise or the MR is stacked; pass + `-b <branch>` to override — a stacked MR targets its parent branch (see [Stacked PRs](#stacked-prs)). +- `--yes` skips the interactive confirmation. Do not pass `--fill` — it overwrites the title + and description with commit info. +- Do not add assignees, reviewers, labels, milestones, or auto-merge unless asked. +- If project detection fails, pass the project explicitly with `-R <group>/<project>`. +- If the branch has not been pushed yet, push it first with `git push -u origin HEAD` (or + add `--push` to the create command). +- Only mark the MR as a draft (`--draft`) if asked. diff --git a/dot_agents/skills/creating-pull-requests/scripts/nearest-parent-branch.sh b/dot_agents/skills/creating-pull-requests/scripts/nearest-parent-branch.sh new file mode 100755 index 00000000..d7cdc7bb --- /dev/null +++ b/dot_agents/skills/creating-pull-requests/scripts/nearest-parent-branch.sh @@ -0,0 +1,27 @@ +#!/usr/bin/env bash +# +# Print the nearest parent branch of HEAD — the local branch the current branch +# most likely built on — for inferring a stacked PR's parent when it isn't given +# explicitly. Run it from inside the target repository. +# +# Git records nothing about what a branch was forked from, so this reconstructs +# the relationship from commit topology: it ranks every local branch by how few +# commits HEAD is ahead of that branch's divergence point (merge-base) and prints +# the closest few, nearest first, as tab-separated "<commits-ahead>\t<branch>". +# The top line is the best guess; equal top counts mean it is genuinely ambiguous. + +current=$(git branch --show-current) +head_rev=$(git rev-parse HEAD) + +git for-each-ref --format='%(refname:short)' refs/heads/ | while read -r b; do + # Skip the current branch itself. + [ "$b" = "$current" ] && continue + # Skip strict descendants of HEAD (children further up the stack). A branch + # sitting exactly at HEAD is kept, so the trunk still wins before the current + # branch has any commits of its own. + if git merge-base --is-ancestor HEAD "$b" && [ "$(git rev-parse "$b")" != "$head_rev" ]; then + continue + fi + base=$(git merge-base HEAD "$b") + printf '%s\t%s\n' "$(git rev-list --count "$base..HEAD")" "$b" +done | sort -n | head -3 diff --git a/dot_claude/agents/cheapest-pr-cold-reader.md.tmpl b/dot_claude/agents/cheapest-pr-cold-reader.md.tmpl new file mode 100644 index 00000000..1b3aba21 --- /dev/null +++ b/dot_claude/agents/cheapest-pr-cold-reader.md.tmpl @@ -0,0 +1,9 @@ +--- +name: cheapest-pr-cold-reader +description: "Use this PR cold-reader for work assigned to the cheapest model tier. It is intended for an independent read of a PR diff, with no access to the author's context." +model: haiku +color: cyan +tools: Read +--- + +{{ template "agent-cheapest-pr-cold-reader.md.tmpl" . -}} diff --git a/dot_claude/agents/mid-tier-pr-cold-reader.md.tmpl b/dot_claude/agents/mid-tier-pr-cold-reader.md.tmpl new file mode 100644 index 00000000..240e4e77 --- /dev/null +++ b/dot_claude/agents/mid-tier-pr-cold-reader.md.tmpl @@ -0,0 +1,10 @@ +--- +name: mid-tier-pr-cold-reader +description: "Use this PR cold-reader for work assigned to the mid-tier model tier. It is intended for an independent read of a PR diff, with no access to the author's context." +model: sonnet +effort: high +color: blue +tools: Read +--- + +{{ template "agent-mid-tier-pr-cold-reader.md.tmpl" . -}} diff --git a/private_dot_config/opencode/agents/cheapest-pr-cold-reader.md.tmpl b/private_dot_config/opencode/agents/cheapest-pr-cold-reader.md.tmpl new file mode 100644 index 00000000..9f9f215c --- /dev/null +++ b/private_dot_config/opencode/agents/cheapest-pr-cold-reader.md.tmpl @@ -0,0 +1,17 @@ +--- +name: cheapest-pr-cold-reader +description: Use this PR cold-reader for work assigned to the cheapest model tier. It is intended for an independent read of a PR diff, with no access to the author's context. +mode: subagent +model: openai/gpt-5.6-luna +permission: + edit: deny + bash: deny + read: allow + webfetch: deny + task: + "*": deny + skill: + "*": deny +--- + +{{ template "agent-cheapest-pr-cold-reader.md.tmpl" . -}} diff --git a/private_dot_config/opencode/agents/mid-tier-pr-cold-reader.md.tmpl b/private_dot_config/opencode/agents/mid-tier-pr-cold-reader.md.tmpl new file mode 100644 index 00000000..655d28e2 --- /dev/null +++ b/private_dot_config/opencode/agents/mid-tier-pr-cold-reader.md.tmpl @@ -0,0 +1,18 @@ +--- +name: mid-tier-pr-cold-reader +description: Use this PR cold-reader for work assigned to the mid-tier model tier. It is intended for an independent read of a PR diff, with no access to the author's context. +mode: subagent +model: openai/gpt-5.6-terra +reasoningEffort: high +permission: + edit: deny + bash: deny + read: allow + webfetch: deny + task: + "*": deny + skill: + "*": deny +--- + +{{ template "agent-mid-tier-pr-cold-reader.md.tmpl" . -}}