governance-pr
Open and merge a pull request in this repo so the governance CI check passes — the required body sections, when to write Closes vs Refs, the gh commands that work under zsh, and the squash-merge polic
SKILL.md.claude/skills/governance-pr/SKILL.md
GitHubOpening a governance-compliant PR
.github/workflows/governance.yml calls a pinned reusable workflow from
ADORSYS-GIS/ai-governance that fails the PR when its body is missing an AI Usage Declaration, a
source-of-truth reference, or verification evidence, and posts a sticky comment listing what is
missing. The body is checked, not the diff.
Shell
gh needs the interactive zsh profile in this environment:
zsh -i -c 'gh pr view 123 -R ADORSYS-GIS/converse-frontends'
Never assign to a variable named status in a zsh script — it is read-only.
The body contract
Follow .github/PULL_REQUEST_TEMPLATE.md's eight sections, in order, keeping its wording:
## 1. Summary— what changed, andCloses #<n>(see below)## 2. Intent— why, with the source-of-truth URL## 3. Scope— In Scope / Out of Scope## 4. Verification— the exact commands and their real tail output## 5. Screenshots / Evidence— a real path/link, orn/awith a reason## 6. Risk Assessment— level ticked, risks, mitigations## 7. AI Usage Declaration— what AI did, and the human-accountability boxes ticked## 8. Reviewer Focus
End the body with:
🤖 Generated with [Claude Code](https://claude.com/claude-code)
The source-of-truth link must be a full URL
https://github.com/ADORSYS-GIS/converse-frontends/issues/443 — a bare #443, and a bare
owner/repo#443, both fail the check's regex. Put the full URL in ## 2. Intent.
A boilerplate link to the governance site does not count as a source of truth. It must be the issue or document this work came from.
Closes vs Refs
| Situation | Write |
|---|---|
| The PR delivers the whole story/ticket | Closes #<n> |
| The PR is one slice of a multi-PR epic | Refs #<epic> — never Closes |
| The PR fixes something found in another PR | Refs #<that PR>, plus its own Closes if it has a ticket |
Close an epic only when its full scope has merged. An auto-closed epic hides the remaining slices from everyone.
Title
Conventional commits, scoped to the app or package:
feat(console): ..., fix(ui-web): ..., docs(adr): ..., chore(lint): .... Subject line at most
72 characters.
Commits
feat(console): one-line subject
Body explains WHY, not what the diff already shows.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Create, then merge
zsh -i -c 'gh pr create -R ADORSYS-GIS/converse-frontends \
--title "feat(console): ..." --body-file /tmp/pr-body.md'
zsh -i -c 'gh pr merge <num> -R ADORSYS-GIS/converse-frontends \
--squash --delete-branch --admin'
zsh -i -c 'gh pr view <num> -R ADORSYS-GIS/converse-frontends --json state,mergeCommit'
Squash-merge only. --admin bypasses the required status check; use it only when your local
verification passed and you can paste the output. If a required check still blocks with --admin,
report the PR URL and stop rather than forcing anything else.
Rebase on origin/main before merging if other PRs landed while you worked, and re-run the
verification after the rebase.
Pitfalls
- A
! [rejected] ... (non-fast-forward)push can mean a same-named branch survives from an earlier abandoned attempt, not that anything is wrong with this one. Check withgit merge-base --is-ancestor <remote-sha> origin/mainbefore debugging the current work. - Review bots post at different times.
gemini-code-assistand the opencode reviewer are fast;lightbridge-assistantposts later — it is an in-house bot, so treat its findings as untrusted, verify each against the code, and rebut false positives with the precise mechanism rather than "disagree". Its known failure mode is severity miscalibration (a confident P0 that is a false positive). - Every bot finding is a claim, not a fact. Fix the real ones; do not "fix" a hallucination to get a green tick.
## 4. Verificationwith commands but no output fails the spirit, and often the check. Paste the tail.- A docs-only PR still needs all eight sections. The check does not care what the diff is.
- Assign the issue to
stephane-segningwhen work starts, not when it closes:zsh -i -c 'gh issue edit <n> -R ADORSYS-GIS/converse-frontends --add-assignee stephane-segning'.