pr-description-writing

PR Description Drafting

Draft a PR title (conventional commit format) and description (Shopware's 5-section template) by analyzing the full branch scope, leveraging session context, and asking targeted questions for missing context.

Output scope: Presents formatted title + description text. Does not create or update PRs on GitHub. Does not write to any files.

Phase 1 — Assess Branch State

Determine what we're working with — branch, PR status, and diff.

1. Load references/branch-and-pr-detection.md and execute Steps 1-4. Route as pr-description-writing.
2. Get the diff:
   • If a PR exists: read its diff and changed files from GitHub (a GitHub MCP server, the gh CLI, or the API — whatever the session has)
   • If no PR: run git diff trunk...HEAD --stat and git log trunk..HEAD --oneline
3. Present a brief assessment to the user: branch name, PR status (exists / doesn't exist / has existing description), change magnitude (files touched, lines changed, areas affected)

Phase 2 — Analyze Changes

Understand the full story of the branch — not just individual file changes.

1. Synthesize the full branch scope from the diff, commits, and file changes. Understand the totality: features, fixes, cleanups, refactors — everything that happened on this branch.
2. Determine scope: map file paths to Shopware areas (Core, Storefront, Administration, App System, etc.). This informs the conventional commit scope for the title.
3. Identify the narrative candidates. A branch often contains multiple threads — a feature plus cleanup plus a fix discovered along the way. Present these to the user:

   "This branch contains: (a) a new endpoint for X, (b) a fix for null handling in Y, (c) cleanup of unused imports. What's the primary story?"

4. The user confirms or reframes the story. This drives the title's type/scope and which aspects get depth vs. a brief mention. If secondary threads remain (cleanup, test improvements, incidental fixes), offer them as an "Additional Changes" section: "The test cleanup / refactor / fix isn't part of the main story. Want it mentioned in an Additional Changes section at the end?" Only offer when the secondary work has educational value (practices not widely known in the project) or touches files a reviewer might otherwise question.
5. Assess description depth based on the confirmed story:
   • Bug fix → root cause analysis in Why, reproduction steps important
   • New feature → usage context in What, scope boundaries valuable
   • Breaking change → migration guidance needed
   • Performance → quantified improvement expected
6. Leverage session context: if the user has been debugging, implementing, or discussing in the current session, use that knowledge. Don't re-ask what's already known.