docs(agents): Fold pr.mdc into the create-java-pr skill - #5936
docs(agents): Fold pr.mdc into the create-java-pr skill#5936runningcode wants to merge 3 commits into
Conversation
📲 Install BuildsAndroid
|
The pr.mdc rule file and the create-java-pr skill described the same six-step PR workflow, and both inlined a copy of the PR template and the changelog subsection table. Nobody on the team uses Cursor, so the rule/skill split earned nothing and the two copies had already drifted: both inlined templates were missing the "Public API changes reviewed by another Mobile SDK team member" checklist item that .github/pull_request_template.md has gained since. Delete pr.mdc and give its content one home each. The conventions the skill was missing (allowed commit types, PR title format, changelog rebase caveat) move into the skill. The stacked-PR workflow moves to a references file the skill loads on demand, so the common standalone-PR path no longer carries 150 lines that only apply to stacks. The skill now reads .github/pull_request_template.md instead of reproducing it, leaving one copy that cannot drift. #skip-changelog
86fbcba to
41113f9
Compare
The reference file mixed two kinds of content: the standard Graphite-style stacking workflow, which any agent can reconstruct from general knowledge and `gh` usage, and the parts specific to this repo. The generic half diluted the half that matters. Drop the chain-walking recipe, the branch naming convention, the generic create/merge/sync steps, and the restatement of the stack shape. Keep what is not derivable: why the collection branch exists (`main` is squash-only, which conflicts repeatedly when syncing a stack), the title and stack list formats, and the permission-pattern constraint on editing PR bodies. Collect the four destructive-operation warnings under one heading instead of leaving them scattered across three sections, and point SKILL.md at the surviving section names. #skip-changelog
| @@ -0,0 +1,88 @@ | |||
| # Stacked PRs | |||
|
|
|||
| Stacked PRs split a large feature into small, easy-to-review PRs where each builds on the previous | |||
There was a problem hiding this comment.
This is a simplified version of .cursor/rules/pr.mdc with just the stacked PRs section. The other generic PR information is already encoded in the skill.
| Invoke the `sentry-skills:create-pr` skill to create a draft PR. When providing the PR body, use the repo's PR template structure from `.github/pull_request_template.md`: | ||
| Invoke the `sentry-skills:create-pr` skill to create a draft PR. | ||
|
|
||
| Read `.github/pull_request_template.md` and use it as the PR body structure — it is the single source |
There was a problem hiding this comment.
We have a duplicate of the PR request template and can drift apart so I suggest we have the LLM reference the pull request template.
| ``` | ||
|
|
||
| If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and commit them following Sentry conventions. | ||
| If there are uncommitted changes, invoke the `sentry-skills:commit` skill to stage and commit them following [Sentry commit message conventions](https://develop.sentry.dev/engineering-practices/commit-messages/): |
There was a problem hiding this comment.
Bug: The create-java-pr skill references non-existent skills (sentry-skills:commit and sentry-skills:create-pr), which will cause the agent's workflow to fail.
Severity: HIGH
Suggested Fix
Review the create-java-pr skill definition in SKILL.md. Replace the incorrect invocation of sentry-skills:commit with the correct command or skill for committing changes. Similarly, replace the sentry-skills:create-pr invocation with the intended gh pr create command to ensure the pull request can be created successfully.
Prompt for AI Agent
Review the code at the location below. A potential bug has been identified by an AI
agent. Verify if this is a real issue. If it is, propose a fix; if not, explain why it's
not valid.
Location: .claude/skills/create-java-pr/SKILL.md#L92
Potential issue: The `create-java-pr` skill definition in `SKILL.md` instructs an AI
agent to invoke two skills, `sentry-skills:commit` and `sentry-skills:create-pr`, which
do not exist. The pull request was intended to fix these references but failed to do so,
leaving the incorrect skill invocations in place. When an agent attempts to execute the
steps for committing code (Step 3) or creating a pull request (Step 5), it will fail
because the specified skills are not defined anywhere in the repository. This renders
the `create-java-pr` skill unusable.
Also affects:
.claude/skills/create-java-pr/SKILL.md:124
Did we get this right? 👍 / 👎 to inform future reviews.
Ran fresh agents through "create a PR" and "create a stacked PR" against the deduped docs, stopping each before the first mutating action. Both paths loaded the intended files, but four defects surfaced: - SKILL.md named stacked-prs.md the source of truth for branch naming, which that file never covered. Corrected to title naming; the branch rule stays in Step 1, where the branch is created. - Four passages referenced the collection branch PR, but no step ever opened it. Added next to the branch creation, with its title and merge-reminder exceptions. - The PR-description editing rule was stated three times and had already drifted. It now lives once in SKILL.md, which both the standalone and stacked paths read, and stacked-prs.md points back to it. - AGENTS.md rule 7 told agents to propose but not execute a commit while the create-java-pr skill commits, pushes, and opens the PR, leaving two terminal states for one request. Scoped rule 7 to implementation work. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
📜 Description
Deletes
.cursor/rules/pr.mdc(264 lines) and gives its content a single home each:create-java-pr/SKILL.md: allowed commit types, PR title format, changelog rebase caveat.create-java-pr/references/stacked-prs.md, loaded on demand. Git tracks this as a rename.The skill now reads
.github/pull_request_template.mdfor the PR body instead of reproducing it, with an explicit instruction never to write it from memory.AGENTS.mddrops theprrow from the rule table and points its Changelog section at the skill.Fixes found by dry-running the result
Agents were run against the deduped docs for "create a PR" and "create a stacked PR", stopping before the first mutating action. Both paths loaded the intended files — the standalone run never opened
stacked-prs.md— and surfaced four defects, now fixed:SKILL.mdnamedstacked-prs.mdthe source of truth for branch naming, which it never covered. Claim corrected to title naming.&&vs&&/||). Now stated once inSKILL.md, which both paths read.AGENTS.mdstep 7 ("propose but not execute a commit") contradicted the skill, which commits, pushes, and opens the PR. Scoped to implementation work.💡 Motivation and Context
pr.mdcand the skill described the same six-step workflow. The skill opened by declaringpr.mdc"required reading … the source of truth," then re-implemented every step anyway. Both inlined the PR template and the changelog subsection table.Nobody on the team uses Cursor, so the split bought nothing — it just doubled the surface that had to stay in sync. And it hadn't: both inlined templates were missing a checklist item
.github/pull_request_template.mdhas since gained:Every PR created through the skill silently dropped it. Pointing at the template file makes that class of drift impossible.
💚 How did you test it?
Docs-only — no code paths affected.
pr.mdcremain.AGENTS.mdrule table matches.cursor/rules/exactly (12 rules, 12 rows).📝 Checklist
sendDefaultPIIis enabled.🔮 Next steps
Remaining duplication, in order of payoff:
AGENTS.mdrepeats./gradlew spotlessApply apiDumpacross nine lines; theMakefileis the source of truth. (CONTRIBUTING.mdalso documents amake formattarget that doesn't exist — one-line fix held back for its own PR, which this one should follow.)AGENTS.mdand the skill.AGENTS.md,test/SKILL.md, ande2e_tests.mdc; the skill's module→task table is the accurate one..cursor/rules/files are arguably misfiled if nobody uses Cursor, but rehoming them touches every rule reference.#skip-changelog