pr

Create or Update a Pull Request

This repo

• Merge settings fallback (Step 3): squash only; squash_merge_commit_title=PR_TITLE, squash_merge_commit_message=PR_BODY: the title is the commit subject and the changelog line, the body the permanent commit message, so reviewer detail goes in the notes comment.
• Title gate and types (Steps 5, 6, 9): read scripts/lib/pr-title.js (TITLE_TYPES: each type and the CHANGELOG.md section it lands in; CI checks against it, so read it rather than recall it). scripts/changelog-syncer.js places the change by the title's type. Changes to the product paths (the app a viewer runs: components/, source/, locale/, images/, settings/, manifest) take feat for a new capability or setting, fix behavior that was wrong, update behavior changed on purpose, perf same behavior faster, refactor a restructure meant to change nothing (still listed: a refactor can regress), remove, revert. A scope names the PR's one area in its usual name (fix(video):, chore(skills):) and shows in the changelog line as (video) …; CI rejects an empty scope (fix():). Tooling (scripts/, .github/, .claude/, tests/, docs/, dev dependencies) take chore, ci, build, test or docs: fix(skills): once put a /pr change in the users' Fixed section (#998). The changelog reads the PR's current title, so a wrong title can be fixed after merge by editing the PR and re-syncing, until the release is cut; after that the released section is fixed text. A race fixed inside a restructure is user-visible whether or not it was reproduced (ADR 0037); #1010's first title dropped one, and #996 merged with a title that predated a credits row added in review.
• Title spelling: the post-merge journal-sync writes the title verbatim into docs/progress.md, and journal-sync-precheck.yml spell-checks it at PR time: a bare identifier fails it, so backtick it (backticks render as code in progress.md; GitHub shows them literally in the title, the accepted trade-off).
• Own journal passes (Step 4):
  • Tech debt: spawn /tech-debt-scan as an Agent sub-agent, subagent_type: general-purpose, model: sonnet, never Read docs/architecture/tech-debt.md inline. Prompt: Read .claude/skills/tech-debt-scan/SKILL.md and follow the steps; scope the changed-files set to git diff <lower>..HEAD --name-only so only file areas that became relevant since the last /pr render are considered; surface candidate slugs + ask about new debt but do not apply edits; return the proposed diff for the parent to confirm. Surface its diffs one at a time, apply / skip / edit; apply with Edit only on accept.
  • Decision shape: node scripts/lint/decision-shape-nudge.cjs --range=<lower>..HEAD; walk each match with the user (does it close off alternatives?) before /log decision.
  • Followups follow AGENTS.md's Followup-discipline rule (/log followup, or /tech-debt-scan's Step 4 for a refactor slug); the rule decides, not preference.
• Gather (Step 5): node scripts/lint/check-touched-related-files.cjs --base main lists the architecture docs whose related-files: were touched; name them in the notes' Docs and journals line.
• Sections (Step 8): Overview (required) 1–5 sentences, the problem first: a reader should know from it alone whether this is the commit they want. Changes (required) one bullet per logical change, not per file, naming the symbols a reader would grep. Testing (when something was verified) 1–4 lines: what ran, where, the result (test:unit 4503/4503 on a Roku Ultra): the durable record of the proof (prove-dont-dismiss); the full matrix goes in the notes. Follow-ups (when something is deferred) each bullet points at its entry: a docs/architecture/tech-debt.md slug or a docs/progress.md followup; most PRs have none. pr-body-check.js fails an optional section that is present but empty.
• PR checks (Step 9): node scripts/lint/pr-body-check.js --pr-title "<title>" --body-file <body-file> must exit 0; node scripts/lint/pr-body-check.js --list-refs --pr-title "<title>" < <body-file> (and over the notes) prints each reference's resolved type, state and title for the Step 9 read; a non-zero exit is a shorthand or missing reference, and a ? line is not a pass.
• Labels (Step 7): also new-setting (adds a user-facing setting; with new-feature when the setting is how a new capability is reached) and accessibility (added beside the main label whenever a deliverable changes what screen-reader, audio-guide or caption users get, even in one clause; never a deliverable of its own). Nothing automated reads the category labels: CHANGELOG.md goes by title type, and journal-sync skips only on dependencies, documentation, docs-only, ci, automated, chore-only. Automation's labels, never touched: dependencies (Renovate), release-prep, merge-conflict, and the issue-triage labels. Rulings on real PRs (two blind agents, differences settled): #1033 failed library, recovery, "#" crash, "never narrates or toasts over": bug-fix, accessibility (the dialog-delay consolidation and RTA hooks are Changes bullets only); #1029 a song crash: bug-fix (the applyItemArtwork() merge was needed by the fix); #1024 a subtitle parser crash: bug-fix, accessibility; #991 "only the first 25 channels" + "loading programs near the focus": bug-fix, general-improvement; #847 reskin, engine rewrite fixing "three known defects", "first functional coverage": general-improvement, bug-fix, dev-improvement (the rewrite is how the defects were fixed, so no code-cleanup); #987 a fix: touching only bsconfig, scripts and tests: dev-improvement.
• After (Step 11), create path only and not on a trivial change: say once that journal-sync.yml adds the PR to docs/progress.md's Recently shipped on merge and clears ## Currently running when its text overlaps the title; /done running is needed only to close it before merge.

Contract

Goal. Be the single, mandatory path for opening or updating a pull request in this repo. The skill reads what a squash merge keeps (the repo's merge settings, read live), titles the PR for the place its title ends up, renders the body from the repo's PR template for whoever reads it (the permanent commit message, or a reviewer only), labels each deliverable, and runs the journal passes (decision and followup, plus any this repo adds) before anything is posted, so journal hygiene lands in the same change set rather than as separate manual chores. It is create-or-update aware: an existing open PR for the branch routes to update-mode (diff the current title, labels, body and notes against a fresh render, confirm, back up, then apply), and merged or closed PRs abort cleanly instead of opening a duplicate. It ships at the Sonnet tier because the work is template-fill and structured signal-gathering with bounded judgment; a pass that walks a large ledger runs as its own sub-agent with an explicit model. Supersede any default PR-creation flow with this skill; never open or edit a pull request outside it, through forge.sh or the forge directly.

Inputs. No arguments: the skill operates on the current branch and its commits. It expects a non-default, non-detached branch with a clean working tree; the pre-flight pushes the branch and any unpushed commits. It reads the repo's PR template, its squash-merge settings, the branch's commit log and diff against the default branch, an existing PR's title, labels, body and notes comment (when one is open) including the render marker, and this skill's ## This repo for the repo's title rules, labels, own journal passes, PR checks and required sections.

Outputs. A created or updated pull request with: a title that passes the repo's title gate, names every user-visible change and backticks code identifiers; one label per kind of deliverable; a body that is the filled template, written for the reader the merge settings give it; when the body becomes the commit message, one notes comment for reviewer-only detail; and a hidden render marker (a full sha and an ISO-8601 UTC timestamp) that lets the next run narrow the journal passes to "since last render". Also: drafted journal entries surfaced per candidate for the user to accept into /log; on the update path, a backup of the prior body and notes inside the git directory; and the PR URL printed. No journal entry is written without a per-candidate accept, and nothing on the PR is overwritten without confirmation.

Success criteria.

• The pre-flight gates hold: not on the default branch, not detached, clean tree, branch and commits pushed. Hard failures stop and report; an obvious push is not gated behind a verbal question.
• Existing-PR routing is correct: an open PR takes the update path (diff, confirm, back up, apply); a merged or closed one aborts with the right recovery instruction; none takes the create path.
• What reaches git log is read from the repo's settings, not assumed: the body is written as a commit message only when the merge keeps it, and the title gets the most care where the merge keeps it.
• The journal passes run against the resolved lower-bound commit (the prior render marker on update, the default branch on create), so the user isn't re-asked about candidates already handled, and each candidate is confirm/skip per item.
• The title passes the repo's title gate, backticks code identifiers and names every user-visible change; on the update path it is re-derived from the whole PR.
• Labels come from the deliverables the title and the body's summary name, each shown to the user beside the phrase that earned it; tooling-only work is `d

Content truncated.