Skip to content

xiduzo/wtf / skills/wtf.create-pr

wtf.create-pr

Verified

This skill should be used when a developer wants to open a pull request for a completed trace branch — for example "create a PR", "open a pull request", "submit this for review", "make a PR for trace

---
name: wtf.create-pr
description: This skill should be used when a developer wants to open a pull request for a completed trace branch — for example "create a PR", "open a pull request", "submit this for review", "make a PR for trace #42", "push this up for review", or "create PR from current branch". Reads the Trace + Feature + Epic hierarchy to write a meaningful PR description. Handles branches with or without a linked WTF trace issue.
---

# Create PR

Open a pull request for a completed trace branch.

This skill reads the full spec hierarchy (Trace + Feature + Epic) and the branch diff.
It writes a PR description that explains why the change exists, not only what it does.

## Process

### 0. GitHub CLI setup

Run steps 1–2 of `../references/gh-setup.md` (install check and auth check).
Stop if `gh` is not installed or not authenticated.
The `gh-stack` extension is needed only for a stacked Trace PR (step 8). `wtf.setup` installs it. No other extension is required.

Skip this step if invoked from `wtf.verify-trace` or another skill that already ran gh-setup this session.

### 1. Confirm the branch

Check the current branch.
Verify it is not `main`:

```bash
git branch --show-current
```

If on `main`, call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Which branch should I open a PR from?"
- header: "Branch"
- options: from `git branch --list` (local branches)

Check whether a PR already exists for this branch:

```bash
gh pr list --head <branch_name> --state open
```

If an open PR already exists, print its URL and call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "A PR already exists for this branch. Would you like me to update its description instead?"
- header: "Existing PR"
- options:
  - **Update description** → skip to step 5, targeting the existing PR for update via `gh pr edit <pr_number>`
  - **Open a new one** → create a new PR anyway

### 2. Identify the Trace (if any)

Try to extract a trace number from the branch name (e.g. `trace/42-date-range-filter` → `#42`).
A legacy `task/42-<slug>` branch also matches — treat that issue as a legacy Trace per `../references/issue-classification.md`.

If found, call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "I found Trace #<n> linked to this branch. Is that the right trace?"
- header: "Linked trace"
- options:
  - **Yes, that's correct** → use Trace #<n>
  - **No, use a different trace** → I'll provide the correct issue number

If not found or the user says no, call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Is there a Trace issue linked to this work?"
- header: "Linked trace"
- options:
  - **No linked trace** → proceed without a trace link
  - **Yes — I'll provide the number** → enter the trace issue number

### 3. Lifecycle check (if Trace linked)

If no Trace is linked, skip this step.

Apply the **absent-label gate** from `../references/lifecycle-labels.md` for the `verified` label on the Trace — recommended skill `wtf.verify-trace`, header `Verify first?`.
On **Verify first** → follow `wtf.verify-trace` passing the Trace number as context.
On **Open PR anyway** → proceed.

### 4. Fetch the spec hierarchy

**If a Trace issue is known**, walk Trace → Feature → Epic per `../references/spec-hierarchy.md`.
Extract the story, the Scenario Claim, the Spine position, the Technical Approach, and the DoD from the Trace.
Extract ACs, the Trace Plan, any delivery override, and constraints from the Feature. Extract the Goal from the Epic.
For a legacy Task, extract the old sections instead (Functional Description, Gherkin, Contracts, DoD, Test Mapping).

Resolve the delivery mode per `../references/branch-setup.md` ("Resolve the delivery mode") — the Feature's override wins.

**If no Trace issue**, skip hierarchy fetch.
The PR will be written from diff context alone (step 5).

### 5. Inspect the diff

Determine the base branch per the Base-branch policy in `../references/branch-setup.md`, resolved with its "Resolve the stack base" procedure (same as step 8).
Then collect the branch diff against that base:

```bash
git log <base_branch>..HEAD --oneline
git diff <base_branch>...HEAD --stat
```

This avoids unrelated merged commits when the branch has a long history against main.
Use `--stat` output only unless a specific commit message is ambiguous and cannot be resolved without the diff.

### 6. Draft the PR

Apply strict STE per `../references/ste-writing.md` before writing any durable body.

**Title generation:** Spawn a subagent with `model: "haiku"` — apply `../references/subagent-protocol.md` for the spawn — to generate a PR title per `../references/commit-conventions.md`.
Pass in the trace title (if available), the commit log, and whether this is a breaking change.
If the subagent returns nothing usable, generate the title directly following the same rules.
Examples: `feat(search): add date range filter`, `fix(payments): prevent double settlement`, `refactor(orders): extract fulfilment service`.

**Body:** Load the PR template per `../references/issue-template-loading.md` (verify `.github/pull_request_template.md` exists, halt-or-setup if missing).
Complete all sections:

- **Summary**: derived from the Trace's story and its Spine position — what this pass adds to the Spine (Skeleton | Extension | Deepening, and which Traces it builds on). Explain the why. If no Trace, derive from commit messages.
- **Changes**: grouped logical summary of `git diff --stat` output — not a file list.
- **Test plan**: if a Trace exists, one checklist item per claimed scenario name from the Scenario Claim. If no Trace, derive from changed files and commit messages. At minimum one item per observable behavior changed.
- **Related**: closure keywords per `../references/commit-conventions.md`, one per line. If a Trace exists, include `Closes #<trace_number>`. In `trunk` delivery, when this Trace exhausts the Feature's Trace Plan, add `Closes #<feature_number>` on its own line. For a feature-branch PR (`staged`), include `Closes #<feature_number>` plus one `Closes #<trace_number>` line per completed Trace.

### 7. Review with user

Show the draft title and body.
Then call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Does this look right?"
- header: "Review"
- options:
  - **Looks good — create the PR** → proceed with PR creation
  - **I have changes** → adjust first

Apply edits, then proceed.

### 8. Create the PR

Determine the base branch from the current branch name and the delivery mode, per the Base-branch policy table in `../references/branch-setup.md`. For a `trace/*` branch the base is the **stack base**: the tip of the one stack of the Feature. Resolve it with the `## Resolve the stack base` procedure in `../references/branch-setup.md` — walk the open Trace PRs of the Feature from the root to the tip. Never derive it from git upstream: before the first push the branch has none, and after `git push -u` the upstream is the branch itself.

- `trace/*` branch, another Trace PR of the Feature is open → target the stack tip (a `trace/*` branch)
- `trace/*` branch, no other Trace PR of the Feature is open, `staged` delivery → target the parent feature branch (`feature/<feature-number>-<feature-slug>`)
- `trace/*` branch, no other Trace PR of the Feature is open, `trunk` delivery → target `main`
- Skeleton `trace/*` branch → the feature branch (`staged`) or `main` (`trunk`)
- `feature/*` branch → target `main`
- `hotfix/*` branch → target `main`
- `task/*` branch (legacy) → target the parent feature branch
- Other → call `AskUserQuestion` (per `../references/questioning-style.md`):
  - question: "What branch should this PR target?"
  - header: "Base branch"
  - options: from `git branch -r`

**Join the stack first.** A `trace/*` branch must contain its stack base. The tip moves when a sibling joins first. If the branch does not contain the base, rebase onto it, run the tests, and push — per "Join the stack" in `../references/branch-setup.md`. Never target a branch this one does not contain — the diff would carry the commits of another Trace. When the base is another `trace/*` branch and no native stack is used (see below), say so in the PR body: this is a stacked PR, it merges after its base, and GitHub retargets it automatically when the base merges with its head branch deleted.

Write the body to a temp file (`$BODY`) with the Write tool.
Then create the PR via the gh body helper (`../references/gh-body-helper.md`) so the description survives UTF-8 on Windows:

```bash
# $BODY is the temp file you wrote the PR body to with the Write tool.

# stacked trace branch — base is the stack tip:
python3 .wtf/gh-body.py create --pr \
  --title "<title>" \
  --body-file "$BODY" \
  --base trace/<base-trace-number>-<base-trace-slug>

# trace branch with no other open Trace PR, or a Skeleton — staged delivery:
python3 .wtf/gh-body.py create --pr \
  --title "<title>" \
  --body-file "$BODY" \
  --base feature/<feature-number>-<feature-slug>

# trace branch — trunk delivery, or feature branch:
python3 .wtf/gh-body.py create --pr \
  --title "<title>" \
  --body-file "$BODY" \
  --base main
```

Print the PR URL.

**Native stack.** When the base is a `trace/*` branch, link this PR into its native stack per `../references/branch-setup.md` "Native stacks". Run `gh stack link <bottom-pr> ... <this-pr>` with the open Trace PRs of the Feature, bottom to top, ending with this PR. The command creates the stack or updates it. GitHub then renders the stack on every PR, so do not add the "stacked PR" note to the body. `wtf.setup` installs `gh-stack`. If `gh extension list` does not show it, skip the link and keep the "stacked PR" note in the body (the fallback in "Native stacks").

### 9. Update the Trace issue (if linked)

If a Trace issue is linked, post a comment linking the PR:

```bash
# Write "PR opened: <pr_url>" to a temp file with the Write tool ($COMMENT), then:
python3 .wtf/gh-body.py comment <trace_number> --body-file "$COMMENT"
```

### 10. Offer next steps

Call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "What's next?"
- header: "Next step"
- options:
  - **Request a review** → add reviewers to this PR now (default)
  - **Done** → exit, no further action

On **Request a review** → call `AskUserQuestion` (per `../references/questioning-style.md`):
- question: "Who should review this?"
- header: "Reviewer"
- options: from team member usernames inferred from recent `git log` authors or the repository's CODEOWNERS file

Then:
  ```bash
  gh pr edit <pr_number> --add-reviewer <username>
  ```
  For multiple reviewers, pass a comma-separated list: `--add-reviewer user1,user2`.
  Print the PR URL.
- **Done** → exit.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall