ado-pr-generate

name	ado-pr-generate
description	Create or update an Azure DevOps Pull Request from the current branch — auto-detect project/repo from the git remote, generate a title and description from commits/diff, link work items parsed from the branch name or commits, support draft PRs, and update an existing PR's metadata. Use when the user asks to 'open a PR' or 'update PR <id>' against an Azure DevOps repository.
author	Marc Fabian Mezger <[e-mail]>

Azure DevOps — Pull Request Generation

This skill drives a self-contained Python CLI that creates/updates Azure DevOps PRs against the REST API. The LLM is responsible for composing the title and description from the detect output; the CLI is intentionally deterministic and never invents content on its own.

Workflow

Run from the repo's root (or pass --repo-path).

Script: scripts/pr_generate.py (relative to this skill's directory).

Step 1 — Detect context

Always run detect first. Never call create without it.

uv run scripts/pr_generate.py detect [--base main] [--log-limit 20]

Returns: branch, defaultBranch, parsed org/project/repo from the remote, recent commits (sha, subject, author), diffShortstat, changedFiles, and any work item IDs parsed from commit subjects or the branch name (patterns #123 or AB#123).

If org/project/repo are null in the output, the remote is not an Azure DevOps URL — stop and tell the user.

Step 2 — Compose title + description (LLM responsibility)

Using the detect output:

• Title: Conventional Commits style <type>(<scope>): <imperative summary>, ≤ 72 chars, no trailing period.
• Description: short markdown with at least:
  • Summary — 1–3 sentence what + why.
  • Changes — bullet list of the meaningful items, grouped by area when helpful. Reference filenames sparingly.
  • Testing — what was verified, or _None yet_ if nothing was run.
  • Optional Linked work items section listing IDs.
• Never include AI attribution (no Generated by, Co-authored-by: Claude, etc.) in titles, descriptions, or comments — even if a default template adds it.

Step 3 — Create the PR

uv run scripts/pr_generate.py create \
  --title "<title>" \
  --description "<markdown>" \
  [--target-branch main] \
  [--draft] \
  [--work-item 12345 --work-item 12346] \
  [--no-push]   # only if branch is already pushed

--project, --repo, and --source-branch are auto-inferred from detect. Pass them explicitly only to override.

Output includes pullRequestId and a clickable url. Surface the URL to the user.

Step 4 — (Optional) link more work items / comment

uv run scripts/pr_generate.py link-wi --pr-id 42 --work-item 99 --work-item 100
uv run scripts/pr_generate.py comment --pr-id 42 --text "Ready for review."

Step 5 — Updating an existing PR

For "push more commits to PR 42 and refresh the description":

1. git push the branch yourself (or via the commit/github-pr workflow — the local steps are the same).
2. uv run scripts/pr_generate.py update --pr-id 42 --description "<new md>" [--title "..."] [--draft/--no-draft] [--target-branch main].

update does not push commits — it only PATCHes PR metadata. Pushing the branch is enough to update the diff itself.

Defaults & conventions

• Draft by default? No. Only pass --draft when the user asks or when the work is clearly in progress (e.g. WIP commits, failing tests documented in the description).
• Reviewers: Do not add reviewers automatically — let the user do it manually.
• Target branch: defaults to the repo's origin/HEAD (typically main). Override with --target-branch.

Guardrails

• Do not call create against a detached HEAD — detect errors out.
• If the current branch has no commits ahead of the target, stop and tell the user — there is nothing to merge.
• If detect shows uncommitted changes that would be expected in the PR, surface that to the user and confirm whether they want to commit first.
• Never overwrite an existing PR description on update without showing the user the new content first.
• Work-item linking uses an Azure-DevOps-specific artifact URI. If linking fails with a 4xx, surface the API error verbatim — usually it means the PAT lacks Work Items scope.