Github Issue Workflow

Overview

Use gh to discover and inspect issues, then follow the repository's required issue-development flow. Prefer deterministic commands and keep work aligned to branch and PR policy.

Scan And Inspect Issues

• List open issues:
  • gh issue list --state open --limit 200
• View one issue:
  • gh issue view <issue-number> --json number,title,body,state,labels,assignees,url
• View one issue with discussion:
  • gh issue view <issue-number> --comments

If gh is unavailable, ask the user to install/authenticate gh, then retry the same command.

Command Playbook

Run these in order for a new issue implementation.

1. Sync main first:
   • git checkout main
   • git pull --ff-only origin main
2. Inspect and confirm target issue:
   • gh issue view <issue-number> --json number,title,body,state,labels,assignees,url
   • gh issue view <issue-number> --comments
3. Create issue branch before edits:
   • git checkout -b issue-<issue-number>-<short-slug>
4. Implement changes and run tests:
   • uv run --extra dev pytest -q
5. Commit and push branch:
   • git add -A
   • git commit -m "<focused-change-message>"
   • git push -u origin issue-<issue-number>-<short-slug>
6. Open draft PR to main with auto-close reference:
   • gh pr create --base main --head issue-<issue-number>-<short-slug> --draft --title "<pr-title>" --body "fix #<issue-number>"

Start New Issue Checklist

1. Confirm clean context:
   • Check current branch and status with git status -sb.
2. Scan open issues:
   • Run gh issue list --state open --limit 200.
3. Load issue details:
   • Run both gh issue view <n> --json ... and gh issue view <n> --comments.
4. Update main before branch work:
   • Run git checkout main and git pull --ff-only origin main.
5. Create issue branch before any edits:
   • Use git checkout -b issue-<n>-<slug>.
6. Start implementation and open draft PR early:
   • Push and create draft PR as soon as meaningful implementation starts.

Resume Existing Issue Checklist

1. Verify issue branch exists and switch to it:
   • git checkout issue-<issue-number>-<short-slug>
2. Refresh issue/PR context:
   • gh issue view <issue-number> --comments
   • gh pr status
3. Sync from main if needed (merge/rebase per repo preference).
4. Continue implementation on issue branch only.
5. Run tests before push:
   • uv run --extra dev pytest -q
6. Push updates and keep PR draft until ready:
   • git push
   • Mark PR ready only after tests/review items are complete.

Policy Guardrails

• Do not implement issue work directly on main.
• Do not switch tools if a workflow command fails due to sandbox restrictions; rerun with proper escalation.
• Keep commits focused and descriptive.
• Avoid destructive git commands unless explicitly requested.
• Include issue-closing reference in PR description (for example fix #123).
• If sandbox/network blocks required update commands, request elevated execution and retry.

Reference

See references/agents-github-issue-workflow.md for the extracted source policy text from this repository's AGENTS.md.