Pull Request Workflow

Create effective pull requests and address review comments systematically.

When to use

Follow this workflow for the full lifecycle of a pull request, from creating a PR for review through addressing comments to verifying all feedback has been resolved before merge.

The pattern

Apply formatting before creating PR

Always apply formatting standards to all files before creating pull requests. This prevents formatting-related review comments.

Run the full test suite before creating a PR

Run the full test suite and have it pass before opening a PR, for every change, not only changes near a test:

npm test

npm test runs the whole suite across the repo, so a change far from any test can still break one (for example, moving a file the index-coverage test depends on). Some co-located suites bring their own dependencies (the code-style linter under skills/code-style/lint/); install those once so the full suite can run. For changes that touch docs or internal links, also run npm run docs:build, which fails on dead links. CI runs the same suite on every PR as a backstop, but run it locally first.

Address comments systematically

Always use the PR comments script to fetch review threads. Do not use gh api repos/OWNER/REPO/pulls/PR/comments — that REST endpoint only returns inline diff comments and misses general review comments and conversation threads.

Fetch all review threads with full context:

node skills/github/pr-comments.js <PR_NUMBER>

This script uses the GraphQL reviewThreads API to fetch every thread — both inline diff comments and general review comments — and outputs them as readable markdown with author, body, file path, line number, diff hunk, and resolved status.

Raw GraphQL query (for reference)

gh api graphql -f query='
  query {
    repository(owner: "OWNER", name: "REPO") {
      pullRequest(number: PR_NUMBER) {
        reviewThreads(first: 100) {
          edges {
            node {
              isResolved
              isOutdated
              comments(first: 100) {
                nodes {
                  id
                  databaseId
                  author { login }
                  body
                  path
                  line
                  originalLine
                  diffHunk
                  createdAt
                }
              }
            }
          }
        }
      }
    }
  }
'

For every unresolved comment thread:

1. View the code context (diff hunk) to understand what line it refers to
2. Read the full conversation thread
3. Check if outdated (may reference old file versions)
4. Fix the code
5. Reply with "Done" — this is not optional. Fixing code without replying leaves the thread unresolved and the author has no way to know it was addressed.

gh api -X POST \
  /repos/OWNER/REPO/pulls/PR/comments/ID/replies \
  -f body="Done"

Check for new comments after each push

# Count total review comments
gh api repos/OWNER/REPO/pulls/PR_NUMBER/comments \
  | jq '. | length'

# Count unresolved threads
gh api graphql -f query='...' \
  | jq '[... | select(.node.isResolved == false)]
    | length'

Hard rules — non-negotiable

Do NOT apply line length limits to GitHub markdown

Never wrap prose at 80 (or any fixed) characters in PR bodies or review comments. GitHub renders these fields as flowing markdown — hard line breaks inside a paragraph produce broken, jagged text in the rendered view.

Write each paragraph as a single unbroken line. Blank lines separate paragraphs. This rule applies to PR body, PR review comment bodies, and PR review summaries.

Trade-offs

• Don't address comments without viewing their diff hunk context
• Don't ignore parent comments in the conversation thread
• Don't assume comments refer to current file state