Project-specific build/test/lint/typing commands for this repo. Read this skill at the start of any phase that runs validation (`stoker-work`, `stoker-fixup`, `stoker-rebase`).

2026-07-209

stoker-implement

lsst-sqre/docverse

Drive a single pre-selected task through stoker-work's TDD cycle and commit/push/PR/close it (or stuck-mark it on failure). Use when invoked from the implement-phase prompt — the host has already picked the task and checked out its branch.

2026-06-069

stoker-work

lsst-sqre/docverse

The universal red/green/refactor TDD methodology building block — drives a unit of work through plan → failing test → minimal implementation → refactor → validation against this repo's project-mechanics. Use when invoked from `stoker-implement` (always delegates here for the dev cycle), from `stoker-fixup` or `stoker-rebase` when a finding or conflict warrants the full TDD discipline rather than an in-place apply-and-validate, or any time the user wants to drive a feature/bug-fix/refactor through plan → test → implement → validate.

Create or update a pull request with a Summary / Validation steps / References body, including `Closes

2026-05-289

name	stoker-create-pr
description	Create or update a pull request with a Summary / Validation steps / References body, including `Closes

stoker-create-pr — the Rubin PR-creation primitive

Create a pull request (or update one that already exists on this branch) using a fixed body template that the AFK loop and humans both produce identically. This skill is the single source of truth for the Rubin profile's PR shape: title format, body sections, and the Closes #N / PRD: #N / Jira: <url> trailer conventions.

stoker-implement delegates here for its PR step. Humans invoke it directly for hand-driven PRs.

This is the Rubin variant of the default stoker-create-pr. It keeps the default's create-vs-update logic and multi-task Closes #N regeneration verbatim, and layers two Rubin conventions on top: a DM-XXXXX:-prefixed title for tickets/DM-XXXXX... branches, and a Jira: <url> line in References.

Workflow

1. Gather context

Collect these values. Use the first available source for each:

Task issue — the prd-task whose work this PR delivers. Sources in order: current conversation context (e.g. the implement-phase prompt) > auto-detect by branch (see below) > ask the user (optional — solo PRs without a tracked task are allowed).
Parent PRD — the task issue's ### Parent PRD field, when the task is part of a PRD breakdown. Optional.
Branch — the current branch (git branch --show-current).
Jira key — sources in order: current conversation context > the branch name when it matches tickets/<KEY>... (the <KEY> segment, e.g. tickets/DM-12345-add-foo → DM-12345) > the task issue's ### Jira Key field > none. Optional — u/<login>/<desc> branches and ticket-less PRDs have no Jira key.
Jira URL — sources in order: the task issue's ### Jira URL field > constructed as https://rubinobs.atlassian.net/browse/<key> when a Jira key is known > none.

Auto-detecting the task issue

If no task is in context, search by branch:

gh issue list --label prd-task --state open --json number,title,body --limit 50

Find the issue whose ### Branch field matches the current branch name. Extract ### Parent PRD, ### Jira Key, and ### Jira URL from that issue's body.

2. Push the branch

git status -sb

If the branch has no remote tracking branch or has unpushed commits:

git push -u origin HEAD

If the push fails (non-fast-forward, permission denied, network), do not retry or rebase from this skill. Surface the failure to the caller (stoker-implement routes to the stuck path; humans get an error message).

3. Detect existing PR

gh pr list --head <branch> --json number,title,body,state,baseRefName --limit 1

Three cases:

No existing PR → create a new one (step 4).
Existing PR, state OPEN → regenerate the body from the branch's cumulative scope (step 5).
Existing PR, state CLOSED or MERGED → skip PR handling. Log the fact and return.

4. Create a new PR

Title.

When a Jira key is known, prefix the title: DM-XXXXX: <concise description>. The description is a concise summary of what this PR accomplishes; keep the whole title under 70 characters.
With no Jira key (a u/<login>/<desc> branch or ticket-less work), use a plain concise descriptive title under 70 characters.

Body. Use the template below verbatim.

gh pr create --title "<title>" --body "$(cat <<'EOF'
<body>
EOF
)"

5. Update an existing OPEN PR

Regenerate the body from the branch's full scope so Summary, Validation steps, and References reflect every task that has landed, not just the first.

Enumerate every commit since the PR's base. Use baseRefName from the gh pr list JSON; do not hardcode origin/main:
```
git log origin/<baseRefName>..HEAD --format='%H%n%s%n%b---'
```
Take the union of Closes #N trailers from those commits, the Closes #N lines already in the existing PR body's References section, and the currently-picked task. (Refs #N trailers used by stuck WIP commits naturally don't surface here, so stuck work never leaks into References or Summary.)
For each unique N, fetch the issue:
```
gh issue view <N> --json number,title,body,state
```
Pull manual-QA bullets from the issue's ### Acceptance criteria field (if present) for the Validation steps section. Also re-read the ### Jira Key / ### Jira URL fields here so the Jira: reference stays correct after the first task.
Compose a fresh body using the template:
- Summary — 1–3 bullets (up to 5 if scope is genuinely diverse). Collapse multiple commits advancing the same slice into one bullet.
- Validation steps — union of manual-QA items from every referenced task. Drop bullets CI already covers and bullets superseded by later commits.
- References — one Closes #N per referenced task, sorted ascending; then PRD: #<parent_prd> (omit if none); then Jira: <url> (omit if no Jira key). Sorted + deduped is idempotent by construction.
Apply:
```
gh pr edit <pr_number> --body "$(cat <<'EOF'
<body>
EOF
)"
```
Leave the existing PR title unchanged on update — it already carries the DM-XXXXX: prefix from creation.

6. Report the URL

After create or edit, print the PR URL so the caller can surface it to the user (or the comment-and-close steps in stoker-implement).

PR body template

## Summary

<1–3 bullets describing what this PR does and why, in user / PRD-
level language. Draw ground truth from the commits on this branch;
draw user-facing framing from the task issue title.>

## Validation steps

<Bulleted manual-QA checklist for verifying the change. Omit anything
CI runs automatically (no linting, type-checking, or automated test
suite items). Only manual verification.>

## References

- Closes #<task_issue>
- PRD: #<parent_prd>   <!-- omit if no parent PRD -->
- Jira: <jira_url>     <!-- omit if no Jira key -->

Rules for the References section:

Use Closes #<task_issue> so the task auto-closes on merge.
Omit the PRD: line if there is no parent PRD.
Omit the Closes # line if there is no task issue (a hand-driven PR with no tracked task).
Omit the Jira: line if there is no Jira key.
For multi-task branches, include one Closes #N per referenced task, sorted ascending. There is a single Jira: line per PR (all tasks on a branch share one ticket).

Example output

For a branch tickets/DM-45678-run-harness-flag:

## Summary

- Add `--harness` flag to `stoker run` so an iteration can be locked
  to a single harness regardless of profile defaults.
- Validate the harness name against the registered-harness registry
  and fail fast on unknown values.

## Validation steps

- Run `stoker run --harness codex 1` against a fixture issue and
  confirm the implement+review phases both invoke codex.
- Run `stoker run --harness foo 1` and confirm it exits with a
  non-zero code before any container work starts.
- Run `stoker run 1` (no flag) and confirm behavior is unchanged.

## References

- Closes #45
- PRD: #41
- Jira: https://rubinobs.atlassian.net/browse/DM-45678

The PR title for that branch would be DM-45678: Add --harness flag to stoker run.

Notes

This skill is the PR-creation primitive shared by stoker-implement and direct human use. Keep the body shape stable — the AFK loop's multi-task PR-update logic depends on the exact section names and trailer format above.
This skill never calls Jira. The Jira URL comes entirely from the task issue's ### Jira URL field (written interactively by stoker-prd-to-issues) or is constructed from the key in the branch name. The sandbox AFK loop is GitHub-only — it has no Jira creds, MCP, or firewall egress to Jira.
No Co-authored-by: trailer (signing, if configured, is self-identifying).
No "Files changed" section — git show and the GitHub UI cover that.