// Align branch name with artifact ID when they mismatch. Use when: renumbering a REQ/DR/ADR after branch creation, "branch name is wrong", "rename branch to match", or when PR review flags branch/artifact mismatch. Handles the git branch rename and remote update.
Audit documentation coverage against common user questions. Generates a Q&A matrix, searches docs/code for answers, flags gaps, and creates DRs for missing content. Use when asked to "audit docs", "check documentation coverage", "what questions can users answer", or before releases/demos.
Review and help prepare a contributor's pull request (upstream or fork). Use when the user asks to review a PR, get a contributor PR ready, update a contributor's branch, or ensure a PR meets project standards before merge. Follow this skill so contributor PRs are reviewed consistently and avoid rework (lint/test failures, outdated base, weak description).
Prepare and submit a pull request for the APME project. Syncs with upstream, creates a feature branch, runs quality gates (tox -e lint, tox -e unit), updates documentation and ADRs as needed, commits with conventional commits, then creates the PR via gh. Use when the user asks to submit, create, or open a pull request, or says "submit PR", "open PR", "create PR", "new PR".
Guide for handling pull request reviews, including automated (Copilot) and human reviewer feedback. Use when responding to PR comments, resolving review threads, or updating PRs after review.
Reference for running lint, test, build, and pod commands via tox. Agents MUST use tox for all quality gates — never invoke pytest, ruff, mypy, prek, or shell scripts directly. This skill is the canonical lookup table for which tox environment to use.
Guide for writing and modifying GitHub Actions workflows in this repository. Use when creating CI/CD pipelines, adding workflow jobs, modifying build steps, or debugging CI failures. Enforces the project's lean CI philosophy.
| name | branch-align |
| description | Align branch name with artifact ID when they mismatch. Use when: renumbering a REQ/DR/ADR after branch creation, "branch name is wrong", "rename branch to match", or when PR review flags branch/artifact mismatch. Handles the git branch rename and remote update. |
| argument-hint | [new-branch-name] |
| user-invocable | true |
| metadata | {"author":"APME Team","version":"1.0.0"} |
Rename a git branch to match its artifact ID after renumbering.
During PR review, artifact IDs sometimes get renumbered (e.g., REQ-005 → REQ-011 to avoid conflicts). The branch name then mismatches the artifact, causing confusion:
Branch: docs/req-005-aa-deprecated-reporting
Artifact: REQ-011-aa-deprecated-reporting
This skill renames the branch locally and on the remote fork.
[new-branch-name] — target branch name (e.g., docs/req-011-aa-deprecated-reporting)--dry-run — show what would happen without executingCurrent branch: docs/req-005-aa-deprecated-reporting
Tracks remote: fork/docs/req-005-aa-deprecated-reporting
Open PR: #102 (https://github.com/ansible/apme/pull/102)
PR head: ffirg:docs/req-005-aa-deprecated-reporting
If argument provided, use it. Otherwise:
New branch name? (current: docs/req-005-aa-deprecated-reporting)
> docs/req-011-aa-deprecated-reporting
Validate format:
req-011 matches REQ-011)type/id-slug)# Rename local branch
git branch -m docs/req-005-aa-deprecated-reporting docs/req-011-aa-deprecated-reporting
# Push new branch to remote
git push -u fork docs/req-011-aa-deprecated-reporting
# Delete old remote branch
git push fork --delete docs/req-005-aa-deprecated-reporting
GitHub PRs automatically track renamed branches if the new branch is pushed before deleting the old one. Verify:
PR #102 now tracks: ffirg:docs/req-011-aa-deprecated-reporting
If PR doesn't update automatically, provide manual fix:
gh pr edit 102 --head ffirg:docs/req-011-aa-deprecated-reporting
Done!
- Renamed: docs/req-005-aa-deprecated-reporting → docs/req-011-aa-deprecated-reporting
- Remote updated: fork
- PR #102: Now tracks new branch
Old branch deleted from remote.
| Situation | Handling |
|---|---|
| Uncommitted changes | Stash before rename, restore after |
| Not on the branch to rename | Prompt to checkout or specify branch |
| No open PR | Skip PR update step |
| Multiple remotes | Prompt which remote to update |
| Protected branch | Warn and abort |
main or master — abort with error/branch-align docs/req-011-aa-deprecated-reporting
Current branch: docs/req-005-aa-deprecated-reporting
Target branch: docs/req-011-aa-deprecated-reporting
This will:
1. Rename local branch
2. Push new branch to 'fork'
3. Delete old branch from 'fork'
4. PR #102 will track new branch
Proceed? (Y/N) Y
Renaming local branch... done
Pushing to fork... done
Deleting old remote branch... done
Verifying PR #102... tracks new branch ✓
Done! Branch aligned with REQ-011.
The pr-new skill should:
branch-align before pushingAdd to pr-new pre-flight checks:
Checking branch/artifact alignment...
- Branch: docs/req-005-aa-deprecated-reporting
- Artifacts: REQ-011, DR-013
⚠️ Branch name contains 'req-005' but artifacts use REQ-011
Run /branch-align to fix? (Y/N)