Skip to content

docs(agents): Fold pr.mdc into the create-java-pr skill - #5936

Open
runningcode wants to merge 3 commits into
mainfrom
no/dedupe-pr-workflow-docs
Open

docs(agents): Fold pr.mdc into the create-java-pr skill#5936
runningcode wants to merge 3 commits into
mainfrom
no/dedupe-pr-workflow-docs

Conversation

@runningcode

@runningcode runningcode commented Aug 11, 2026

Copy link
Copy Markdown
Contributor

📜 Description

Deletes .cursor/rules/pr.mdc (264 lines) and gives its content a single home each:

  • Conventions the skill was missingcreate-java-pr/SKILL.md: allowed commit types, PR title format, changelog rebase caveat.
  • Stacked-PR workflow (~150 lines) → create-java-pr/references/stacked-prs.md, loaded on demand. Git tracks this as a rename.
  • Everything else → already duplicated in the skill, so dropped.

The skill now reads .github/pull_request_template.md for the PR body instead of reproducing it, with an explicit instruction never to write it from memory. AGENTS.md drops the pr row 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.md named stacked-prs.md the source of truth for branch naming, which it never covered. Claim corrected to title naming.
  • Four passages referenced "the collection branch PR"; no step ever opened it. Added, with its title and merge-reminder exceptions.
  • The PR-description editing rule was stated three times and had already drifted (&& vs &&/||). Now stated once in SKILL.md, which both paths read.
  • AGENTS.md step 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.mdc and the skill described the same six-step workflow. The skill opened by declaring pr.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.md has since gained:

- [ ] Public API changes reviewed by another Mobile SDK team member or implemented
      according to the develop docs spec

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.

  • Dry-ran both PR flows with fresh agents; verified the file sets read, and that every fix above resolves a defect an agent actually hit.
  • No references to pr.mdc remain.
  • The PR template's section headers appear in exactly one file.
  • The AGENTS.md rule table matches .cursor/rules/ exactly (12 rules, 12 rows).
  • Spotless covers only Java/Kotlin, so no formatting run applies.

📝 Checklist

  • I added GH Issue ID & Linear ID
  • I added tests to verify the changes.
  • No new PII added or SDK only sends newly added PII if sendDefaultPII is enabled.
  • I updated the docs if needed.
  • I updated the wizard if needed.
  • Review from the native team if needed.
  • No breaking change or entry added to the changelog.
  • No breaking change for hybrid SDKs or communicated to hybrid SDKs.
  • Public API changes reviewed by another Mobile SDK team member or implemented according to the develop docs spec.

🔮 Next steps

Remaining duplication, in order of payoff:

  • AGENTS.md repeats ./gradlew spotlessApply apiDump across nine lines; the Makefile is the source of truth. (CONTRIBUTING.md also documents a make format target that doesn't exist — one-line fix held back for its own PR, which this one should follow.)
  • Changelog rules still live in both AGENTS.md and the skill.
  • Test invocation appears in AGENTS.md, test/SKILL.md, and e2e_tests.mdc; the skill's module→task table is the accurate one.
  • Step 0 of the skill has no branch for "this branch already has an open PR" — four dry runs produced four different plans for that case.
  • The 12 remaining .cursor/rules/ files are arguably misfiled if nobody uses Cursor, but rehoming them touches every rule reference.

#skip-changelog

@sentry

sentry Bot commented Aug 11, 2026

Copy link
Copy Markdown

📲 Install Builds

Android

🔗 App Name App ID Version Configuration
SDK Size io.sentry.tests.size 8.53.0 (1) release

⚙️ sentry-android Build Distribution Settings

Base automatically changed from no/dedupe-agent-rule-files to main August 12, 2026 08:25
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
@runningcode
runningcode force-pushed the no/dedupe-pr-workflow-docs branch from 86fbcba to 41113f9 Compare August 13, 2026 13:26
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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@runningcode
runningcode marked this pull request as ready for review August 13, 2026 15:01
```

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/):

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants