zfinix/aster/gh-pr-workflow

GitHub PR workflow

1. Use `gh` for GitHub operations. Structured queries beat scraping:

gh pr view 12 --json title,body,files,comments, gh pr checks 12, gh issue list --limit 10.

1. Big diffs go to a file, not the conversation.

gh pr diff 12 > /tmp/pr12.diff, then search and read slices of that file. Never print a whole PR diff into the chat.

1. Draft first, post on approval. Write the review or comment body to a

scratch file, show it to the user, and only after they approve post it: gh api repos/{owner}/{repo}/pulls/12/reviews --method POST --input review.json. Never post to GitHub as a side effect of being asked to "review".

1. One PR at a time, one comment per issue found. Do not batch several

PRs' feedback into one pass, and do not stack multiple problems into one comment.

1. Auth errors are a full stop. A 401 or gh auth status failure means

tell the user to run gh auth login. Retrying, or switching to raw git pushes, will not help.

1. PR bodies: summary plus test plan. Short paragraphs over prose walls.

No attribution footers unless asked.

1. Know which subcommands write. Reads (view, list, diff, checks,

api GET, search) run freely; writes (create, edit, merge, close, comment, review, any --method POST/PATCH/PUT/DELETE, pr checkout, release create) change state and will ask the user for approval. Batch reads first, then propose the writes as one step instead of interleaving.