By name: pr-writing description: Use when the user asks to write a PR, draft a PR description, prepare a PR, or get a PR-ready writeup for the current branch. Use when a PR description needs a linked follow-up issue.
PR Writing for This User
What "Write the PR" Means
Compound task that produces two copy/paste-ready artifacts, handed back to the user. The user owns commit, push, opening the PR, and filing the issue on GitHub.
| Artifact | Purpose | Order |
|---|---|---|
| Next-step issue body | The GitHub issue describing follow-up work | First — so the PR's Next Steps section can reference a real issue number |
| PR description body | For the current branch's diff | Second — drafted after a real issue number exists |
Workflow
- Mirror intent in one sentence when ambiguous: "I read this as drafting the issue body and PR description for your review/copy-paste — confirm before I start."
- Ground in primary sources. Never draft from chat memory:
git status— working tree clean, current branch identifiedgit log <base>..HEAD— commits to summarizegit diff --stat <base>..HEAD— files to enumerate- Read
~/wiki/templates/pr-description.md(PR template) and the most recent landed PR description (style example) - Read
~/wiki/templates/issue.mdonly for the next-step issue artifact - For UI / API / feature claims: open the actual source files or mockup PNGs; do not infer from chat
- Draft the next-step issue body first using the
issue-writingprocess. The issue must use only the wiki issue template's top-level sections: Description, Motivation, Requirements. Save it as a wiki document under the relevant project folder (default:~/wiki/projects/<project-slug>/issues/issue-<name>.md). Hand back the wiki path plus content summary. - Stop at the issue-number boundary unless the user pre-authorized a
#TBDplaceholder. Hand the issue body back and ask the user to file it and report the assigned GitHub number. - Draft the PR description second, with the real issue number plugged into Next Steps. Follow the wiki PR template structure: Title (italic placeholder line), Summary (one paragraph), Description (capability-grouped file-first bullets — Added / Updated / Removed / Fixed / Refactored), Motivation and Context, Next Steps. Save it as a wiki document under the relevant project folder (default:
~/wiki/projects/<project-slug>/prs/pr-<name>.md). Hand back the wiki path plus content summary. - Verify every concrete claim in both artifacts against the diff, the source files, and the live API where applicable. Anything sourced only from chat memory or personal wiki gets cut.
Defaults for Common Ambiguities
- Base branch unnamed → confirm with user; if the branch tracks
origin/main, infermainand name the assumption in the mirror sentence. - Issue-filing authority → draft the body, stop for the user to file. Do not run
gh issue createwithout explicit authorization. - Formal template vs landed practice conflict → the formal
pr_template.mdmay list Type-of-Change checklists and How-Has-This-Been-Tested sections; the team's actual landed PRs often omit them. Default to the landed example's leaner shape unless the team's CI / required-fields workflow needs the formal sections. - File destination → wiki project docs by default:
~/wiki/projects/<project-slug>/issues/issue-*.mdand~/wiki/projects/<project-slug>/prs/pr-*.md. Derive<project-slug>from the current repo or matching wiki project folder; createissues/orprs/if missing. Never save generated PR/issue docs in the project repo unless the user explicitly asks. Template docs live in~/wiki/templates/.
What Stays OUT of the Artifacts
- Wiki paths, personal-knowledge-base references, ADR filenames, memory file names — translate into ordinary engineering language.
- Speculative claims, future-work that isn't in this diff, generic boilerplate.
- Negative imperatives ("MUST NOT", "Do NOT") — describe the change as target state in present tense.
- Workflow steps depicting commit / push / merge / deploy — those belong to the human and stay out of the artifacts and out of any workflow prose.
Common Mistakes
| Anti-pattern | Reality |
|---|---|
Ship the PR with hardcoded #TBD in Next Steps |
Real issue number comes first; #TBD is an interim marker, not a release state |
| Source Description bullets from chat memory | Drift; reviewer can't trust it. Source from git diff --stat |
| Reference the wiki / ADR / personal memory in the PR body | Private context leaks into shared artifact |
Run gh pr create or gh issue create from the skill |
Human-owned actions — hand back artifacts, user submits |
| Place generated PR/issue docs inside the project repo or workspace root | These are durable documents; save them under the wiki project folder |
Skip git log and describe what you remember |
Misses commits, mis-attributes work, drift from reality |
| Include "commit → push → open PR" as numbered workflow steps | The skill ends at artifact production; later steps are human-owned |
Stopping Point
The skill produces artifacts and stops. The human owns:
- Filing the issue on GitHub (and reporting the assigned number back if
#TBDwas used) - Reviewing both artifacts and editing them
git commit,git push,gh pr create, attaching screenshots, requesting reviewers, merging
If the user explicitly authorizes any of those steps as a separate ask, that's a different operation — not part of this skill.