Base directory for this skill: /Users/pfleidi/.agents/skills/pfleidi/skills/pr

Create Pull Request

1. Understand the Branch

Use origin/main as the comparison base for understanding branch scope. Do not use local main, a local PR target branch, or direct tree diffs such as git diff main or git diff origin/main for scope checks; those can include upstream-only changes and make this branch look like it reverted unrelated work.

Read the commit history to understand the full scope of changes on this branch.

Review the changed file list from the merge base to the current working tree and confirm every changed file belongs to the PR's stated goal:

If unrelated files or commits are present, STOP and report them. Do not create a PR that bundles unrelated work.

2. Sync with origin/main

Before discovering verification commands, bring the branch up to date with origin/main so verification runs against the merged state.

Check that the working tree is clean:

If there are uncommitted changes, STOP and ask the user to commit or stash them before continuing. A sync into a dirty tree creates ambiguous failure states.

Fetch and merge:

Three outcomes:

Already up to date — no commits to merge. Proceed to step 3.
Clean merge — merge commit created (or fast-forward applied). Proceed to step 3.
Conflicts — merge halts with conflicted files. STOP and report each conflicted file. Do NOT auto-resolve; the user must resolve the conflicts and complete the merge commit themselves. Re-run the PR skill after resolution.

3. Discover Project Verification Commands

Inspect the project to determine how to build, lint, and test. Collect candidate commands from these sources, then deduplicate them before running anything:

Makefile — look for build, lint, check, test, ci, verify targets. Read the target recipes to understand what they run.
mise — check for .mise.toml or .mise/*.toml. Look for [tasks] definitions covering build, lint, test. If found, use mise run <task>.
CI workflows — read .github/workflows/*.yml (or .gitlab-ci.yml, etc.) to understand required coverage. CI is the ground truth for what must pass, but CI matrix shards and CI-only wrappers are not automatically local verification commands.
README.md — look for "Development", "Contributing", "Building", or "Testing" sections that document how to run checks.
Package manager conventions — detect from project files:
- go.mod → go build ./..., go vet ./..., go test ./...; do NOT infer a lint command from Go alone
- package.json → check scripts for build, lint, test
- Cargo.toml → cargo build, cargo clippy, cargo test
- pyproject.toml / setup.py → check for configured linters, pytest

If no lint command exists after checking all sources, state that explicitly instead of assuming an unavailable linter binary.

Reuse Cached Verification Discovery

Before rediscovering commands from scratch, choose an artifact directory using the AGENTS.md temporary artifact rule with agent name pfleidi-pr:

Use ./tmp/pfleidi-pr/ only when ./tmp/ already exists and is already ignored.
If no project-local artifact directory is available, do not use a verification cache by default. Ask before using /tmp/pfleidi-pr/ or modifying ignore files.

When an artifact directory is available, check for a verification cache at <artifact-dir>/verification-<repo-name>.md. The cache is only an input-token optimization; never commit it and never trust it blindly. If no artifact directory is available, perform normal discovery and skip writing the cache.

Reuse the cache only when all of these are true:

It names the same worktree root and remote.
It lists the verification source files it was based on, such as Makefile, .mise.toml, .mise/*.toml, CI workflow files, README files, and package manifests.
Those source files still exist or are still intentionally absent.
git diff --name-only origin/main -- <source files> shows no branch changes to those source files.

If the cache is missing, stale, or incomplete, perform normal discovery. After discovery, update the cache with:

Repository root and remote.
Verification source files inspected.
Selected command plan grouped by coverage area.
Commands intentionally skipped as duplicates, aggregate/subtask overlaps, CI-only jobs, or too-slow shard matrices.
Any assumptions, such as "no documented lint task found."

Deduplicate Verification Commands

Build a command plan by coverage area, not by source. Do not run every command discovered.

Run at most one command for each coverage area: build/compile, lint/static analysis, unit/core tests, integration tests, e2e/smoke tests.
Prefer documented local developer tasks over CI-specific commands when they cover the same area.
Do not run both an aggregate task and its constituent tasks. For example, if mise run check runs lint and tests, either run mise run check alone or run the narrower lint/test tasks, not both.
Treat CI matrix shards as duplicated slices of one suite. Do not run every *:shard:* command locally when an unsharded local task covers the suite.
If CI has only sharded commands and no local equivalent, ask before running all shards. Otherwise, run the smallest representative or changed-scope test command and note that the full shard matrix remains for CI.
Do not run CI-only canary/e2e jobs locally by default. Run them only when the PR changes that surface, when the user asks, or when the project documents them as required local PR verification.

Log which sources you used, which duplicate/CI-only commands you skipped, and what commands you will run. If the deduplication rules require asking before slow CI-only coverage, STOP for confirmation; otherwise immediately proceed to step 4.

4. Run Verification and Auto-Fix

Run the deduplicated command plan in the fewest safe batches. Prefer background processing for independent validation tasks instead of running everything sequentially.

The commands should cover, at minimum:

Build — the project compiles without errors
Lint / static analysis — no lint warnings or static analysis failures
Tests — the selected local test coverage passes without duplicating CI shards or aggregate/subtask combinations

Use the exact commands, flags, and build tags found in step 3 for the commands you selected. Do not invent your own flags.

Parallel Verification Rules

Partition the selected commands into dependency-safe batches before running them:

Run mutating commands alone and before validators that depend on their output. This includes formatters, generators, codegen, migrations, package installation, or commands known to update snapshots, lockfiles, generated files, caches in the repo, or test fixtures.
Run dependent commands after their prerequisite batch passes. For example, do not start tests that require generated code until generation succeeds.
Run independent read-only validation commands concurrently in the same background batch. Build, lint/static analysis, typecheck/vet, and unit tests can usually share a batch when they do not mutate the working tree and do not require the same exclusive service, port, database, or fixture directory.
Keep integration, e2e, or service-backed commands separate unless the project documents that they are parallel-safe.
If unsure whether two commands are independent, run them sequentially. Correctness of validation beats speed.

For each background batch:

Start every command from the same working-tree state.
Run each selected validator directly, for example mise run lint, go test ..., or npm test -- .... Do not wrap validators in sh -c, shell redirection, tee, command separators, or pipelines solely to capture logs; that defeats command-prefix approvals and causes extra permission prompts.
Capture each command's stdout, stderr, exit status, and command line from the tool output separately.
While the batch is running, do not edit files, start auto-fixes, or treat partial output as a result.
Wait for every command in the batch to finish, then show verification as a compact table:

Command Exit Relevant output
go test ./pkg/foo -run TestBar -count=1 0 Short success excerpt.
For failures or short outputs, show complete output in the relevant-output column or immediately below the table. For long successful outputs, show the relevant excerpt and state that the rest was truncated.
If any command in the batch fails, treat the whole batch as failed for the fix loop. Results from other commands in that stale batch may help diagnose, but they do not count as passing verification after files change.

Command	Exit	Relevant output
`go test ./pkg/foo -run TestBar -count=1`	0	Short success excerpt.

On Failure: Fix and Re-verify

If any command fails, do NOT stop. Instead:

Read the error output and identify every failure
Fix all issues — apply the minimal changes needed to make the failing command pass
Re-run the deduplicated verification plan from the top, using the same safe batching rules (not just the previously failing command — fixes can introduce new issues)
Show the updated verification table again, including complete failure output for any command that still fails

Repeat this cycle until all commands pass. Cap at 3 fix attempts. If verification still fails after 3 rounds, STOP and present the remaining failures to the user with full failure output — do not keep looping.

5. Prompt for Commit

After all verification passes, check for uncommitted changes:

If there are uncommitted changes (from auto-fixes in step 4):

Show the diff of all uncommitted changes
Propose a semantically correct commit message using the subject-plus-context style from AGENTS.md. The message must describe the net fix (e.g., "fix lint warnings in config parser" not "fix issues found during PR prep").
If compile/build did not pass for code changes, say the work is not commit-ready and do not ask to commit until the gap is resolved or the user explicitly takes over.
STOP and wait for user approval. The user may edit the message, split the changes, or commit themselves.

If the user approves the commit, do not rerun the full verification suite before committing unless files changed after step 4. If another sanity check is needed, use the commit-time verification scope from AGENTS.md: lint tasks, a compile/build check for code changes, and tests directly related to the changed code only.

If there are no uncommitted changes, proceed directly to step 6.

6. Push the Branch

If the branch has no upstream yet, use git push -u origin HEAD.

7. Create the PR

Determine a concise PR title (under 70 characters) from the commit history and diff.

Set the target base branch from the user-provided PR base, or main when the user did not provide one. Scope checks still use origin/main; the PR target base controls only the GitHub PR destination.

If the user provided a PR target base, set PR_BASE to that branch name instead.

Determine the pushed source branch:

If HEAD_BRANCH is empty, STOP and report that PR creation needs a named local branch.

Determine the GitHub repository slug from the origin remote before writing the PR body:

Extract GITHUB_REPO as <owner>/<repo> from these origin URL forms:

git@github.com:<owner>/<repo>.git
https://github.com/<owner>/<repo>.git
ssh://git@github.com/<owner>/<repo>.git
entire://<mirror-host>/gh/<owner>/<repo>

Strip a trailing .git when present. For entire:// remotes, ignore the mirror host and use only the suffix after /gh/; do not use any checkpoint-storage repository URL as the PR target when the entire://.../gh/... origin is available.

If the origin URL does not expose a GitHub repository, try:

If that still cannot identify a repository, STOP and ask the user for the GitHub target.

Use the same branch-only comparison from step 1 ($MERGE_BASE to the current working tree) when deriving the title, PR body, changed-file list, and mostly-Markdown detection. Do not use local main or direct git diff origin/main output for PR description decisions.

Write the PR body to help a reviewer (human or bot) understand the change without re-deriving it from the diff. Include these sections; omit any that genuinely don't apply:

Why — the motivation: what problem this solves, what behavior was broken or missing, what constraint forced the change. This is the most important section. Be specific so neither a reviewer nor a bot has to infer the reason from the diff alone.
What changed — a short, factual summary of the net change. One or two sentences; the diff is the source of truth.
Usage examples — for a new or changed command, API, config option, workflow, or user-facing behavior, show a small realistic example of how to use it and what to expect. For UI work, add screenshot placeholders such as Before: <screenshot> and After: <screenshot> when actual screenshots are not available yet.
Decisions made during development — non-obvious choices from the development process: why one approach over another, why an existing abstraction wasn't reused, why a check lives where it does, what assumptions shaped the implementation, and what constraints were intentionally accepted.
Technical tradeoffs — when a real engineering tradeoff was made, name the options weighed, what the chosen approach gives up, and why that tradeoff is acceptable. Skip if the change was mechanical with no meaningful alternatives.
Reviewer notes — only for migrations, deployment ordering, backwards-incompatible behavior, or known follow-up work not in this PR. Skip otherwise.
Rendered Markdown (for mostly Markdown PRs) — links to the changed Markdown files rendered on GitHub.

Do NOT include:

A "Test plan" or "Verification" section listing the CLI commands run. Verification already happened in step 4; the transcript doesn't help the reviewer.
A list of newly added tests. The diff already shows them; the list rots when tests are renamed or moved.
A file-by-file changes summary. The diff already shows this too.

Choose the PR creation command from the origin URL.

For entire://.../gh/<owner>/<repo> origins, do not use gh pr create. It may still inspect the local git remote and fail to infer a GitHub host even when --repo "$GITHUB_REPO" is supplied. Use the GitHub API through gh api with the already-derived repository slug and pushed branch:

For normal GitHub remotes, use gh pr create:

If a non-entire:// origin hits the same host-inference failure from gh pr create, use this gh api creation path once instead of retrying gh pr create.

Create a ready-for-review PR only when the user explicitly asks for it with wording such as "non-draft", "ready for review", or "publish it as ready". In that case, omit --draft from gh pr create or omit -F draft=true from the gh api call.

Show the PR URL and STOP.

Rules

Do NOT add "Generated with Claude Code" or any AI attribution anywhere
Do NOT summarize what you just did after showing the URL
Treat a PR as "mostly Markdown" when more than half of changed files are Markdown (.md, .mdx, .markdown) or the main review target is Markdown documentation. In that case, include GitHub rendered links for the changed Markdown files using the pushed branch, e.g. https://github.com/$GITHUB_REPO/blob/<branch>/<path>.md. Link all changed Markdown files when the list is short; for large docs PRs, link the main entry points or most important changed files.
If the user provides a title or description, use it verbatim instead of generating one, but append rendered Markdown links for mostly Markdown PRs unless the user explicitly says not to modify the description.
If the PR description contains checklist items (- [ ]), check them (- [x]) if and only if the corresponding step was actually verified during this workflow (e.g., build passed, tests passed, lint passed). Do NOT check items that were not verified. Do NOT leave items unchecked if they were verified.

Fix Goconst Lint Findings for Checkpoint

What I changed