agentleFS
GavinGreenwoodGavinGreenwood/agentic-workflow-template/.agents/skills/pr/SKILL.md

pr

Skill5 starsChanged 44 days agoMITView on GitHub

User-invoked only. The full ship workflow: verify → commit → push → PR from template → AI self-review against 8 lenses

  • Reads credentials
  • Commits and pushes

The file

Show its rules and text

We split this skill into the rules it gives an agent

24 rules. About 0 are common, 14 are distinctive, and 10 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈14

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 10

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Run the full ship workflow: verify, commit, push, and open a PR.

    line 7
  2. Very specific:

    If PROGRESS.md exists, read it back to identify any docs that need updating, then delete it.

    line 10
  3. Distinctive:

    Delete any image files sitting untracked in the repo root (screenshots from verification sessions).

    line 11
  4. Very specific:

    Run scripts/verify.sh from the repo root — always cd to the git root first (cd $(git rev-parse --show-toplevel)), then run bash …

    line 16
  5. Distinctive:

    Run git status and git diff to review all changes.

    line 17
  6. Distinctive:

    Create a commit following CONTRIBUTING.md conventions (ticket ID in message, conventional commit format).

    line 18
  7. Very specific:

    Create a PR using gh pr create following the PR template in .github/pull_request_template.md:

    line 20
  8. Distinctive:

    Keep the title short (under 70 characters).

    line 21
  9. Distinctive:

    If this branch is stacked on another branch (i.e.

    line 22
  10. Distinctive:

    Never raise stacked PRs as drafts — raise them ready for review immediately so the team can review and approve in parallel.

    line 31
  11. Distinctive:

    Read every changed file in full before forming any opinion.

    line 37
  12. Distinctive:

    Docs sync: Do any architecture docs, ADRs, or runbooks need updating to reflect this change?

    line 45
  13. Very specific:

    After reviewing, post a comment on the PR using gh pr comment with this structure:

    line 48
  14. Distinctive:

    If there are 🔴 Must fix findings: fix them before the comment is posted, include them in a follow-up commit, then note them as "Fixed …

    line 66
  15. Distinctive:

    If there are only 🟡/🔵 findings: post the comment as-is and let the human reviewer decide.

    line 67
  16. Very specific:

    If JIRA_BASE_URL, JIRA_API_TOKEN, or JIRA_EMAIL are not set, skip this step and warn the user.

    line 81
  17. Very specific:

    If any of JIRA_BASE_URL, JIRA_API_TOKEN, or JIRA_EMAIL are not set, skip this step and warn the user.

    line 85
  18. Very specific:

    Use the ticket ID extracted in Step 9 above (e.g.

    line 87
  19. Distinctive:

    Use judgment — post when a comment would genuinely help QA or the team understand what changed and what to verify.

    line 89
  20. Very specific:

    When posting, write the body to a temp file with a single-quoted heredoc, then send with --data-binary @file (avoids shell mangling of …

    line 100
  21. Very specific:

    If --watch was passed as an argument, skip the question below and proceed automatically as if the user said yes.

    line 133
  22. Very specific:

    If the user says yes (or --watch was passed), keep this workflow active.

    line 139
  23. Distinctive:

    If neither source shows activity yet: wait another 120 seconds using the same bounded method, then repeat the same checks.

    line 169
  24. Distinctive:

    If any step fails, stop and explain.

    line 171

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Run the full ship workflow: verify, commit, push, and open a PR.

  1. Clean up ephemeral session artifacts from the repo root:
    • If PROGRESS.md exists, read it back to identify any docs that need updating, then delete it. Stage the deletion with git rm PROGRESS.md (or git add PROGRESS.md if already deleted). The pre-push hook blocks when PROGRESS.md is present, so it must be gone before step 5.
    • Delete any image files sitting untracked in the repo root (screenshots from verification sessions). Run:
      find . -maxdepth 1 -type f \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.webp" \) -delete
      These are never committed — no staging needed. If no images are present, this is a no-op.
  2. Run scripts/verify.sh from the repo root — always cd to the git root first (cd $(git rev-parse --show-toplevel)), then run bash scripts/verify.sh. If it fails, fix the issues and re-run. Do not skip.
  3. Run git status and git diff to review all changes.
  4. Create a commit following CONTRIBUTING.md conventions (ticket ID in message, conventional commit format).
  5. Push the branch to origin with -u flag.
  6. Create a PR using gh pr create following the PR template in .github/pull_request_template.md:
    • Keep the title short (under 70 characters).
    • If this branch is stacked on another branch (i.e. the PR base is not main), prepend the following block to the very top of the PR body — before any other content — and fill in the parent PR number, ticket ID, and short title:

      ⚠️ Stacked PR — depends on #<parent-pr-number> (<TICKET-ID>: <short title of parent>). The diff shown is only this PR's changes — you can review and approve now. **Do not merge** until #<parent-pr-number> merges first, then retarget this PR's base to `main` before merging.
      
      ---
    • Fill in the ticket link, summary, test evidence, review checklist, and risk/rollback sections.
    • Never raise stacked PRs as drafts — raise them ready for review immediately so the team can review and approve in parallel.
  7. Output the PR URL. Then:
    • Open the PR in the browser with gh pr view <number> --web.
  8. Perform a thorough self-review of the PR diff:
    • Fetch the full diff: gh pr diff
    • Read every changed file in full before forming any opinion.
    • Review against each of these lenses — note findings under each:
      • Correctness: Logic errors, off-by-ones, edge cases not handled, wrong assumptions.
      • TypeScript: Any any types, missing generics, unsafe casts, type narrowing gaps.
      • Security (OWASP): Injection, XSS, broken auth, exposed secrets, insecure defaults.
      • Accessibility (WCAG AA): Missing ARIA, keyboard nav gaps, contrast issues, focus management.
      • Test coverage: Untested paths, missing edge cases, assertions that don't actually verify behaviour.
      • Conventions: Naming, file structure, import order, i18n keys — alignment with docs/development/conventions.md.
      • Docs sync: Do any architecture docs, ADRs, or runbooks need updating to reflect this change?
      • Performance: Unnecessary re-renders, N+1 queries, unindexed lookups, large bundle additions.
    • For each finding, classify it as: 🔴 Must fix (bug, security, accessibility) | 🟡 Should fix (quality, coverage) | 🔵 Consider (nit, optional improvement).
    • After reviewing, post a comment on the PR using gh pr comment with this structure:

      ## AI Pre-Review
      
      Self-review completed against correctness, TypeScript strictness, OWASP, WCAG AA, test coverage, conventions, docs sync, and performance.
      
      ### Findings
      
      <list each finding with its classification emoji, file:line reference, and a one-sentence description>
      
      _or_ ✅ No findings — all lenses clear.
      
      ### Summary
      
      <1–2 sentence overall assessment — is this ready for human review, or are there blockers?>
    • If there are 🔴 Must fix findings: fix them before the comment is posted, include them in a follow-up commit, then note them as "Fixed prior to this comment" in the findings list.
    • If there are only 🟡/🔵 findings: post the comment as-is and let the human reviewer decide.
  9. Move the Jira ticket to Review:
    • Extract the ticket ID from the branch name (e.g. proj-123-... → PROJ-123).
    • Source .env and fetch available transitions: GET $JIRA_BASE_URL/rest/api/3/issue/<ticket>/transitions
    • Find the transition whose name matches "Review" (case-insensitive) and apply it:

      source .env && curl -s -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
        -X POST "$JIRA_BASE_URL/rest/api/3/issue/<ticket>/transitions" \
        -H "Content-Type: application/json" \
        -d '{"transition": {"id": "<transition-id>"}}'
    • If JIRA_BASE_URL, JIRA_API_TOKEN, or JIRA_EMAIL are not set, skip this step and warn the user.
  10. Post a Jira comment if it adds value:

    If any of JIRA_BASE_URL, JIRA_API_TOKEN, or JIRA_EMAIL are not set, skip this step and warn the user.

    Use the ticket ID extracted in Step 9 above (e.g. PROJ-123) wherever <ticket> appears below.

    Use judgment — post when a comment would genuinely help QA or the team understand what changed and what to verify. Skip when there's nothing meaningful to add beyond the PR title.

    Post a comment when the change is a bug fix, a visual/UI fix, a behaviour change, or anything where QA needs context to validate it correctly. Good content to include (pick what's relevant):

    • What the problem was (the symptom)
    • Root cause, if non-obvious
    • How it was fixed
    • What QA should check or what should now look/behave differently
    • The PR link

    Skip the comment when it's a pure refactor with no visible change, a chore (deps bump, config, docs), or the PR description already covers everything and there's nothing extra to tell QA.

    When posting, write the body to a temp file with a single-quoted heredoc, then send with --data-binary @file (avoids shell mangling of backticks and special characters in the text). Replace <your comment text here> with the generated comment text:

    COMMENT_BODY=$(mktemp)
    cat > "$COMMENT_BODY" <<'JSONEOF'
    {
      "body": {
        "type": "doc",
        "version": 1,
        "content": [{
          "type": "paragraph",
          "content": [{
            "type": "text",
            "text": "<your comment text here>"
          }]
        }]
      }
    }
    JSONEOF
    
    RESPONSE_BODY=$(mktemp)
    source .env && HTTP_CODE=$(curl -s -o "$RESPONSE_BODY" -w "%{http_code}" \
      -u "$JIRA_EMAIL:$JIRA_API_TOKEN" \
      -X POST "$JIRA_BASE_URL/rest/api/3/issue/<ticket>/comment" \
      -H "Content-Type: application/json" \
      --data-binary @"$COMMENT_BODY")
    rm -f "$COMMENT_BODY" "$RESPONSE_BODY"

    A 201 means success. On failure (HTTP_CODE not 2xx), print the contents of $RESPONSE_BODY before removing it to help diagnose the error, then continue — do not block the rest of the workflow.

  11. Offer to watch for reviews and auto-run pr-action-review:

    If --watch was passed as an argument, skip the question below and proceed automatically as if the user said yes.

    Otherwise, ask the user:

    "Would you like me to watch for reviews and run pr-action-review <number> automatically once one is posted? I'll check every 2 minutes — keep this terminal open."

    If the user says yes (or --watch was passed), keep this workflow active. Wait in no more than 60-second chunks for a total of 120 seconds, then check both sources for any review activity. Prefer the current runtime's non-blocking delayed-continuation tool when it has one:

    Source 1 — formal reviews (/pulls/{pr}/reviews):

    REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner)
    gh api "repos/$REPO/pulls/<number>/reviews" --paginate \
      --jq '[.[] | select(.user.type != "Bot") | select(.user.login | ascii_downcase | contains("copilot") | not)] | length'

    A non-zero count means at least one human has submitted a formal review.

    Also check for Copilot specifically:

    gh api "repos/$REPO/pulls/<number>/reviews" --paginate \
      --jq '[.[] | select(.user.login | ascii_downcase | contains("copilot"))] | length'

    Source 2 — issue comments (/issues/{pr}/comments):

    gh api "repos/$REPO/issues/<number>/comments" --paginate \
      --jq '[.[] | select(.user.type != "Bot") | select(.body | test("## AI (Pre-)?Review") | not)] | length'

    A non-zero count means a human has posted a substantive comment that isn't one of the agent's own AI-review replies.

    Decision:

    • If either source shows new review activity: read and follow .agents/skills/pr-action-review/SKILL.md with <number>. Do not schedule another wakeup — this watcher is one-shot per PR. Running that workflow re-requests review from all pending reviewers, which would trigger another Copilot review and loop indefinitely if the watcher kept running.
    • If neither source shows activity yet: wait another 120 seconds using the same bounded method, then repeat the same checks.

If any step fails, stop and explain. Do not force or skip gates.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.