git-workflow

Use before ticking any "architecture updated" / "diagram updated" checkbox on a PR, and whenever a change alters a cadence, a pipeline stage, a guarantee, a count, or introduces a subsystem. Also fire when the user asks "did you check the diagram", "is the diagram stale", "isn't there a diagram change here", or points out a diagram was skipped. Do NOT fire for changes with no behavioural surface — typo fixes, test-only diffs, dependency bumps, formatting.

Use when waiting on a pull request's CI before acting — "merge when green", "wait for the checks", "watch the run", "is CI green?" — and before REPORTING a PR's check state after any push, including one this session made. Also fire when a wait loop is about to be written with `gh pr view`/`gh run list` in it. Goal — a terminal verdict per named check, never a report that mistook silence, an empty field, or the previous run for an answer.

Use when a PR has just merged on `origin/develop` or `origin/main`, when multiple open PRs share an ancestor that has now landed, when the user says "rebase the open PRs" / "manage open PRs" / "PR X merged, clean up" / "fix conflicts" / "deal with conflicting PRs", **before merging a PR that another open PR is based on**, or after running `gh pr merge`. Goal — drop duplicate commits introduced by the merge, force-push the open PRs onto the new base, prune dead worktrees and branches, and close the issues the merged PR's keywords could not.

Use when moving a pinned vendored dependency to a new upstream commit — a git submodule gitlink, a GitHub Action's pinned ref, a SHA recorded in a config file. Fires on "bump the pin", "update the submodule", after an upstream merge lands, and after an upstream history rewrite orphans the old SHA. Do NOT fire for floating refs (a branch name or `@main` is not a pin), or when the vendored copy is being edited in place — that is a different mistake, and the fix is upstreaming the edit, not bumping.

Use when opening or updating a PR that changes a UI route file (`page.tsx`, `+page.svelte`, a `routes/` entry) without adding a matching screenshot. Also fire when the user says "missing screenshot" / "no screenshot for the UI" / "capture the screenshot" / "screenshot for this PR" / "you forgot the screenshot". Skip on a backend-only PR, or one that already includes screenshots for the surfaces it changes. Where the repo documents its own capture command, run that instead — this skill is the fallback for repos that document nothing.

Use when reporting code coverage on a pull request, or fixing a report that is not landing. Fire when the user says "post coverage on the PR", "show the coverage delta against the base branch", "the coverage bot adds a new comment every push", "add a threshold / red-amber-green band to coverage", "coverage dropped and nobody noticed", or when a PR carries a bare coverage percentage that no reviewer acts on. Stack-agnostic — JaCoCo, lcov, Istanbul, coverage.py, go cover, SimpleCov, coverlet. Skip for GitLab MRs, whose discussion API needs its own upsert; when Codecov or Coveralls already comments, stop and ask before adding a second (see When to STOP).

Use when embedding a screenshot or image in a GitHub PR description or comment, especially for a PRIVATE repo. Fire when the user says "the screenshot is a broken image in the PR", "embed this in the PR", "the image doesn't render for reviewers", "add a before/after image to the PR", or when a raw.githubusercontent.com link shows as a broken image. Skip for GitLab MRs — GitLab rewrites uploaded paths differently and needs its own upload step.

Use when a batch of 3+ independent changes should land as SEPARATE pull requests built by parallel agents — "address all of these", "fix everything on the list", "make as much parallel work as possible", a review or audit producing many unrelated fixes. Goal — reviewable, file-disjoint PRs that merge in any order. NOT for coupled changes (one PR), sequential work (a stack), or generic non-PR parallelism (that is plain agent dispatch).

Use when an active branch has open PRs that may have received new comments since the last check. Auto-trigger after any `git push` to a feature branch, after merging a PR (its siblings' review threads may have moved), and any time the user asks "is PR N ready?" / "what's the status of PRs?" / "manage the open PRs" / "anything to address in PR N?" / "review the PR comments". Skip if no PRs are open or if the user explicitly says "ignore the comments".

Use when deliberately editing the history of an open PR's branch — dropping, reordering, splitting or rewording commits, or squashing before review. Fire on "remove the X commit from PR N", "reorder the commits", "drop the last commit", "clean up the history before review". For the routine post-merge rebase of open PRs (duplicate commits after a parent landed), use branch-hygiene instead — that is mechanical cleanup, this is surgery.

Use when adding, renaming or debugging a GitHub Actions workflow that carries a `schedule:` or `workflow_dispatch:` trigger — especially in a gitflow repo where workflows land on `develop` first. Fire on "the cron never fired", "the workflow doesn't show up", "dispatch says workflow not found on the default branch", HTTP 404 from `gh workflow run`, or a review of a diff that adds either trigger. Skip for workflows with only `push` / `pull_request` triggers — those run from the pushed ref and have no registration step.

Use immediately after `git worktree add` or `git gtr new` creates a fresh worktree for any repo (a web/Next app, a Node/TypeScript backend, a Python data/ETL project, an Android/Gradle app, or anything else) and it won't run or build because .gitignored env files and installed dependencies weren't carried over. Fire when the user says "set up the worktree", "the new worktree won't build/run", "missing .env in the worktree", "node_modules is missing", "gradle can't find the SDK / local.properties", or a dev server errors on missing env vars right after a worktree is created. Skip when the repo ships its own bootstrap skill — that one knows its extra credential files and hooks. Skip if the worktree has already run once.