feat(skills): name branches and PR titles for the reader, not the diff - #31
Merged
Merged
Conversation
Every branch this plugin created was `feature/<slug>`, whatever the work was, and nothing said what the slug had to name. Handed a production bug and the planning skill's step 2, five fresh agents all chose `feature/` for a P1 fix, and all five slugs named the code motion rather than the problem: retry-budget-precheck, retry-budget-reorder, retry-budget-check-order. Four distinct slugs across five runs — the wording bound nothing. A human scanning the remote's branch list learns neither the kind of work nor the subject. Replace the hardcoded prefix with `<type>/<slug>`, where the type is the commit type of the headline change and the slug names the subject and what changes about it. The type comes from the change, not from the workflow that produced it: running the feature-development flow does not make a bug fix a feature. Sub-branches were worse — `-b <sub-branch>` with no guidance at all, left to whatever the orchestrator invented. They are now derived: `<sub-type>/<slug>--<sub-name>`, so one feature's branches sort together, each slice carries its own type, and the sub-name is barred from inheriting plan positions like part-2 or phase-b. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…allenges for system facts Handed the plugin's own title guidance and ready template plus a debugging-heavy change, five fresh agents produced titles naming the code motion — "evaluate the retry budget before the worker-pool lookup" and three near-identical variants. Accurate, convention-compliant, and useless to anyone deciding whether the PR concerns them, because the code motion is the one thing the diff already shows. Only one of five led with the effect. The same five all filed the change's consequence under Challenges, three of five added the history of their review rounds, and all five overran the Description's own stated sentence cap. The section heading sitting in the template was invitation enough. Title guidance now states the two shapes that work, impact-first and cause-first, with the mechanic named as the failure to check against, and a length cap so the summary survives the merge log. The Description became an ordered three-part contract instead of a sentence budget. Challenges gained an admission test — a system fact the diff hides — and names the three kinds of content that kept displacing it. Each of those three now has a destination, which is what actually moved the behavior: consequences go in the Description where a reviewer is guaranteed to read them, deferred work goes in Related whether or not an issue exists yet, and review history stays in the commits. Re-running the scenario: five of five now lead with the effect, five of five surface the consequence in the Description, four of five leave Challenges to system facts alone. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the feature-dev-workflow skills and templates so branch names and PR titles encode the change’s type and user/system effect (instead of generic feature/<slug> and mechanic-first titles), and tightens the ready PR template so “Challenges” stops becoming a catch-all section.
Changes:
- Replace the hardcoded
feature/<slug>branch convention with<type>/<slug>across skills and templates, and derive sub-branch names as<sub-type>/<slug>--<sub-name>. - Add explicit PR title guidance to prefer impact-first or cause-first summaries (avoid mechanic-first), with an approximate ~72 character cap.
- Rework the ready PR template’s Description/Challenges/Related guidance to enforce an ordered “contract” summary and an admission test for keeping “Challenges”.
Reviewed changes
Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| skills/writing-github-issues/SKILL.md | Updates multi-PR branch reference to <type>/<slug> for decision-record linking. |
| skills/reviewing-feature-progress/SKILL.md | Updates state-file integrity checks and feature-branch pull example to <type>/<slug>. |
| skills/planning-a-feature/templates/feature-state.md | Updates state template frontmatter and PR/worktree table to <type>/<slug> and <sub-type>/<slug>--…. |
| skills/planning-a-feature/SKILL.md | Defines the new branch naming scheme and slug expectations; updates feature-branch model references. |
| skills/opening-a-pull-request/templates/pull-request-ready.md | Makes Description an ordered 3-part summary and adds an admission test for including “Challenges”; expands “Related” semantics. |
| skills/opening-a-pull-request/SKILL.md | Adds title-shape guidance (impact/cause-first, avoid mechanic-first) and updates feature-branch targeting guidance to <type>/<slug>. |
| skills/fanning-out-with-worktrees/SKILL.md | Derives sub-branch naming and updates base branch references and merge/pull-back commands to <type>/<slug>. |
| skills/developing-a-feature/SKILL.md | Updates all feature-branch model instructions, examples, and red flags to use <type>/<slug>. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The good/bad table listed full branch names under a column headed "Slug", while the surrounding prose defines <slug> as the part after the type. That invites baking the type into the slug, and the slug is interpolated on its own into the worktree path and every artifact filename — so `fix/…` as a slug would nest .claude/worktrees a directory deeper and put a slash in a spec filename. Head the column "Branch name", state that the slug never contains a slash, and add the duplicated-type row the old table had no way to rule out. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…urce branch "the integration PR (feature → main)" read fine while every feature branch was literally named feature/<slug>. After the rename it invites reading "feature" as a branch name that no longer exists. Name the source branch as <type>/<slug> in the three places that describe the branch pair. Left the "Single-PR feature → main" bullet in writing-github-issues alone: "feature" there is the work, not a branch. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
A branch list and a merge log produced by this plugin told a reader almost nothing: every branch was
feature/<slug>whatever the work actually was, and given a real bug fix, four of five agents wrote a PR title naming the code motion rather than what changed for the system. This PR makes both surfaces carry the change's type and its effect, and gives the ready template'sChallengessection an admission test so it stops absorbing consequences, tradeoffs and review history. It renames the branch placeholder in 53 places, so a state file written by an older version of the plugin still readsfeature/<slug>and will look stale until its branch row is updated by hand.Changes
<type>/<slug>replaces the hardcodedfeature/prefix everywhere, withplanning-a-featurestep 2 now defining both halves: the type is the commit type of the headline change, the slug names the subject and its effect in two to four words.<sub-type>/<slug>--<sub-name>, so one feature's branches sort together, each slice carries its own type, and the sub-name cannot inherit a plan position likepart-2.Challengesbecomes optional-by-default behind a single admission test — a system fact the diff hides — and names the three kinds of content that kept displacing it, each with the section it belongs in instead.Relatedgains an explicit slot for follow-up work this PR knowingly leaves undone, whether or not an issue exists for it yet.Related
feature-branchtopology name is untouched (sub_pr_target: feature-branch, "the feature-branch model", "merged into the feature branch"), so a multi-PR feature's integration branch can now readfix/…while the model it follows is still called "feature-branch". Consistent, but worth a later pass if the wording grates.plugin.jsonversion bump here, matching the repo's habit of bumping in its own PR.Testing
Fifteen fresh-context subagent runs, five per phase, each handed the plugin's guidance verbatim plus a realistic task, with every flagged output read by hand rather than scored by pattern.
The baseline is what motivated each change. Handed a production bug and the current step 2, five of five agents chose
feature/for a P1 fix and five of five slugs named the code motion (retry-budget-precheck,retry-budget-reorder,retry-budget-check-order) — four distinct slugs across five runs, so the wording bound nothing. Handed a debugging-heavy change and the current PR guidance, four of five titles were mechanic-first, five of five filed the change's consequence underChallenges, three of five added the history of their review rounds, and five of five overran the Description's own stated sentence cap.One hypothesis did not survive its own baseline and was dropped rather than written up: on a genuinely simple change, five of five agents already omitted
Challengescorrectly and already wrote impact-first titles. The section only fails when the author has a lot of material, which is why the fix targets where each kind of content goes rather than adding a prohibition.After the rewrite, five of five titles lead with the effect or the cause, five of five surface the consequence in the Description, five of five stay inside the sentence cap, and four of five leave
Challengesto system facts alone. The first attempt only reached two of five on that last measure — naming the disqualifiers was not enough on its own, and what moved it was giving each displaced kind of content a guaranteed destination (Description part three, aRelatedfollow-up line, or the commits). Residual, unfixed on purpose: one run in five still overran the title cap and filed an open question underChallenges, and the guidance warns that appending nuance clauses to a converged recipe degrades it.Plugin JSON parses, and the changed skills grep clean for project, language and product identifiers.