gentleeduck/duck-ui / .claude/skills/pr
pr
VerifiedOpen a PR in this repo, end to end - find the real base branch (never assume main), split the working tree into one commit per feature, pull the Linear tickets, write a body that shows the change rather than describing it, and confirm the base, assignee and labels landed. Use whenever asked to make, open or push a PR, or to commit a working tree "by feature" so a PR can follow.
Opening a PR in IRYSS
Every step here exists because skipping it produced a wrong PR once: the wrong base branch, a 104-file commit, a made-up label. Do all of them in order.
1. Find the real base branch, never assume main
main can be far behind the branch everything actually merges into. Check what recent PRs
really targeted before picking a base:
gh pr list --state merged --limit 5 --json number,title,baseRefName,headRefName,mergedAt
Then confirm with a commit count, not a guess:
git fetch origin <candidate-base> --quiet
git log --oneline origin/<candidate-base>..HEAD | wc -l
The right base is the one where that count matches the work actually on this branch (single
digits for a normal PR), not hundreds. main here was 150 commits behind while
feat/storefront-configuration was the branch every recent PR (#26-30) actually targeted, and
git merge-base against the wrong candidate silently includes someone else's unmerged history
in the diff.
2. Commit by feature, not by "everything at once"
A PR title makes one claim. A working tree with several unrelated fixes tangled together cannot back that claim, whatever the title says. Before touching git:
git status --porcelain=v1andgit diffto map every changed file to the feature it belongs to.- For each feature, stage only its files and diff
--statto sanity check the scope before committing. - When one file has hunks from two features genuinely interleaved (there is no
git add -phere, interactive flags are disallowed): reconstruct the file's state for feature A only, verify that state on its own with a scopedvitest run, commit, then put feature B's hunks back on top of the committed base and verify again. - Before every commit:
bun run check-types,bun run test, andbunx biome check <staged files>at the repo root, not just the touched package. A change that compiles alone can still break a sibling that imports it. - Conventional commit message, ASCII only, explains why not what, no
Co-Authored-Bytrailer. Start a body paragraph with a word rather than aword:token, or commitlint reads it as a footer and warns.
Don't wait to be asked before flagging it: if the tree turns out to hold more than the one thing you were told about, say so and propose the split rather than silently committing everything as one commit.
3. Pull in the tickets
Before writing the body, find every Linear ticket the work closes or touches:
mcp__linear__get_issue for anything already referenced in the conversation,
mcp__linear__list_issues with parentId for sub-issues of a parent ticket. Read each one;
don't just link the id. A ticket with no Linear equivalent (a fix that came from a code
review, a branch's own original scope) still gets a line in the Summary, it just has no link.
Check assignee before writing code for a ticket. One assigned to someone else is theirs to
build.
4. Body shape: simple, list-first, no ceremony
## Summary
<the one visual that makes the change legible, then one bullet per distinct piece of work>
- **Thing one** ([IRY-N](url)): what was broken, one sentence, and what the fix does.
- **Thing two** (no ticket, matches this branch's original scope): same shape.
## Changes
- [x] Short past/imperative line per commit, in commit order
## Verified
Before and after. What was actually run and passed, naming the tier.
## Merge Danger
Only when the answer is interesting. One-way or two-way door, and the blast radius.
Every top-level bullet must trace to an actual commit on the branch. If a bullet needs three sentences to justify itself, the commit it describes is not scoped tightly enough yet: go back to step 2.
Skip all preambles and keep prose brief. Domain language comes from
docs/business-architecture/ and the module's own README.md.
5. Assignee and labels come from the repo, not from memory
gh api user --jq '.login' # this session's authenticated user, for --assignee
gh label list # the actual label taxonomy - never invent one
Pick labels that match what the diff touches: a type: fix/type: feat/etc. for the dominant
kind of change, one area: * per app or package meaningfully touched, and any status label
(security, breaking change) the content actually earns. A rank or permission-check fix
earns security; a repository rename does not.
6. Push and create
git push -u origin <branch>
gh pr create --base <verified-base> --head <branch> \
--title "<type>(<scope>): <summary>" \
--body-file <path> \
--assignee <login> \
--label "type: x" --label "area: y" ...
gh pr view <number> --json title,assignees,labels,baseRefName,headRefName,url
Let pre-push run. It is lint, format, fix, check, check-types, test:coverage,
build, and it passes on a healthy tree. --no-verify is for a gate that is itself broken,
needs the user's explicit say-so, and leaves whatever it skipped still to be run. Because
format and fix write, read git status after a push that took a while.
The final gh pr view is not optional: confirm the base, assignee and labels landed as asked
before reporting the PR back as done.
Choosing the visual
Reference for the ## Summary and ## Verified sections above.
Summary
Pick the smallest view that makes the key point clear.
- Show logic or an algorithm as pseudocode:
on(save)
if content is unchanged
return cached result
write new content
return fresh result
- Show runtime control flow as a call tree:
submitForm
createSession
persistPrompt
launchAgent
navigateToSession
- Show UI structure as a component tree, including state and module boundaries that matter:
<SessionPage>(apps / example / src / routes / session.tsx);
useSessionEvents() < SessionToolbar > <RunSkillButton>(packages / ui);
- Show file responsibility or a broad refactor as a shallow file tree:
src/
├── commands/ # parses user actions
├── sessions/ # owns session state
└── transport/ # sends API requests
- Show component interaction, control flow, or data flow with Mermaid:
sequenceDiagram
participant User
participant UI
participant Daemon
User->>UI: choose command
UI->>Daemon: send expanded prompt
Daemon-->>UI: stream result
- Use
diffwhen the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
For a component change:
<SessionPage>
useSessionEvents()
<SessionToolbar>
+ <RunSkillButton />
<SessionTimeline>
+ <SkillResultCard />
For a file-layout change:
src/
├── commands/
+│ └── show-me.ts # expands the slash command
├── sessions/
-└── transport.ts
+└── transport/
+ ├── client.ts
+ └── stream.ts
For a call-tree or call-stack change:
submitForm
createSession
persistPrompt
+ expandSkillMention
launchAgent
- navigateToSession
+ navigateToSession
+ subscribeToEvents
For a state or control-flow change:
on(save)
- write content
+ if content is unchanged
+ return cached result
+ write new content
+ invalidate cache
- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
function expandSkill(command: string): string {
const skillName = command.slice(1)
return `use the ${skillName} skill`
}
Guidance
Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.
Three shapes recur in this monorepo and are worth reaching for first:
- A schema or constraint change reads as a diff of the column and the constraint that guards it, because the CHECK is the behaviour.
- A module added or reshaped reads as the shallow file tree of
modules/{module}/, which is the shapedocs/business-architecture/modules/01-commerce-api/patterns.mdsets. - A permission change reads as the scope ladder it walks, since who a route admits is the whole point and prose hides it.
Verified
Concrete evidence that the change works. Show a before and after.
Screenshots are S-tier, when the environment is set up for it and the change is visual.
Execution-based evidence is A-tier. Test results, console output. Show the exact test that now fails and passes.
Name the tier something ran at, because the three prove different things here:
bun run test is hermetic, test:integration and test:e2e need a live Postgres. "Tests
pass" without the tier is not evidence, and a claim that e2e passed is only true if the
reference data was seeded first.
Merge Danger
Add this section when the answer is interesting. Describe whether it's a one-way or two-way door. You can walk back through two-way doors, but not one-way doors. A PR that is cheap to roll back is lower risk. Changes that involve destructive actions or hard-to-reverse decisions are one-way doors.
The blast radius is the potential impact or scope of the changes introduced by this PR. Consider all possibilities. Examples are layout shift, breakages for consumers, mobile responsiveness, etc.
Four things are one-way doors in this repo and deserve saying so in the body:
- A migration, because an applied one is not un-run by reverting the PR, and an out-of-order timestamp is skipped silently while migrate prints success.
- A widened IAM grant, because every session holding it has to be re-evaluated to know what it reached in the meantime.
- A published SDK regeneration, since consumers compile against it.
- A deleted column or dropped constraint, which takes the data with it.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |
| contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies. | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |
| meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要". | Stars: 108k | Updated | Claude CodeCodex | Verified | Install |