Github Workflow

Tool Choice Rules

Fallback rule: if gh has a clean command for the task, prefer it. If the task is fundamentally local source control, use git.

Branch Workflow

1. Sync and inspect the default branch.
2. Create a focused branch from the default branch.
3. Keep the branch name descriptive.

Example:

git switch main
git pull --ff-only
git switch -c feat/add-github-workflow-skill

Recommended prefixes:

• feat/
• fix/
• docs/
• chore/
• refactor/
• test/

Avoid vague names like updates, stuff, or misc-fixes.

Commit Workflow

Use git for staging and committing. Keep commits small and readable.

git status
git add <paths>
git commit -m "feat: add github workflow skill"

Prefer conventional-commit-style summaries:

• feat: add github workflow skill
• fix: correct PR base branch detection
• docs: document packaged skills
• chore: clean up release notes

Before pushing, review what changed:

git diff --staged

If a commit needs cleanup, use git commit --amend or interactive rebase deliberately. Do not use gh for local history surgery.

Push and PR Workflow

Push with git, then use gh to work with the PR.

git push -u origin HEAD
gh pr create --fill --base main

Useful gh commands:

gh pr status
gh pr view --web
gh pr checks
gh pr create --fill --base <default-branch>
gh pr checkout <number>

PR hygiene:

• make sure the base branch is correct
• use a title that matches the change
• include a short summary of what changed and any risk areas
• mention tests run when relevant

If --fill produces a weak title/body, replace it instead of accepting low-quality PR text.

Review Workflow

Use gh to inspect and respond to review state.

gh pr view <number>
gh pr diff <number>
gh pr checks <number>
gh pr review <number> --comment -b "Looks good overall; left one suggestion."
gh pr review <number> --approve
gh pr review <number> --request-changes -b "Please address the failing tests and rename the branch."

When reviewing your own work, check:

• PR targets the correct base branch
• branch is up to date enough for the repo's workflow
• checks are green or known failures are explained
• description matches the actual diff

Merge Workflow

Prefer gh pr merge so the merge action is tied to GitHub PR state.

gh pr merge <number> --squash --delete-branch

Common variants:

• --squash for small or iterative branches
• --merge when the repo prefers merge commits
• --rebase when the repo explicitly prefers rebased history

Before merging, confirm:

• approvals or review requirements are satisfied
• required checks passed
• the chosen merge strategy matches repo norms

After merge, sync local state:

git switch main
git pull --ff-only

Common Mistakes

• using gh for tasks that are really local git operations
• forgetting to verify the default branch before creating the PR
• pushing a branch without -u and then losing the upstream link
• opening a PR with an unhelpful auto-filled title/body
• merging without checking CI or review status
• mixing unrelated changes into one branch or one commit

Red Flags

Stop and re-check before acting if you see any of these:

• gh auth status is not healthy
• the remote is not the repo you expected
• you do not know the correct base branch
• the branch name does not describe the change
• the PR title says one thing but the diff shows another
• checks are failing and no reason is documented

When unsure, inspect first, then act.