Audit github-agile skills and extract all remaining mechanical sequences into Python scripts

[sebastientaggart]

Problem to Fix

PR #162 (the sync-base-branch.py tracer bullet from #159) validated a hypothesis: handing mechanical shell sequences off to small Python scripts is meaningfully better than narrating them in skill markdown. Concretely, it collapsed five permission prompts into zero (one python3 allow rule covers everything), made the operation atomic instead of agent-narrated step-by-step, and trimmed the skill prose.

That same pattern — inlined multi-step git, gh, or other tool plumbing that has no judgment calls and the same shape every invocation — repeats throughout the rest of the github-agile skills. Each unconverted instance keeps paying the cost the tracer bullet eliminated: permission prompts on compound shell, tokens spent re-narrating the steps, and surface area for the agent to drift (forgotten flag, missing temp file, wrong order).

Why it Matters

• Permission UX. Every compound shell statement (A && B || { ...; exit 1; }, multi-step gh flows, conditional fallbacks) costs the user a permission prompt or two in Claude Code. A single python3 script.py … invocation costs zero. The cumulative annoyance across a typical /start → /submit-for-review → /deploy cycle is significant.
• Reliability. Deterministic Python with explicit exit codes behaves identically every time. Agent-narrated sequences can — and do — drift across adapters and invocations.
• Token spend. Each skill markdown re-loads the full shell narration every invocation. A script invocation is one tool call.
• Maintenance leverage. Centralizing the mechanical bits in scripts means edge-case fixes happen once, not in N skill files in lockstep.

General Approach

Audit every skill in skills/github-agile/ and extract every sequence that is purely mechanical — no judgment calls, no agent-side decisions, the same shape every time — into named Python scripts under skills/github-agile/scripts/. Skills become thin orchestrators: they make the decisions (which case applies, what title to use, whether to ask the user) and delegate execution.

Candidate sequences known to fit, gathered from prior tickets and the existing skill content:

• The --body-file plumbing pattern used for gh issue create, gh issue comment, and gh pr create (write to temp file, then invoke with --body-file <path>).
• The follow-up-issue creation loop in /submit-for-review Step 9 (per-finding title trim, label resolution, gh issue create with the right flags omitted).
• The label and milestone three-tier resolution from /start's Parsing section.
• The make -n <target> "verify make target exists" guard used in /submit-for-review Step 2 and Step 8.
• The git fetch origin <base> && git merge origin/<base> sync sequence in /submit-for-review Step 4 (sibling of the just-shipped sync-base-branch.py, but a merge rather than a hard-reset).
• The CODEOWNERS detection + --reviewer handle stripping in /submit-for-review Step 6.
• Resolution-comment posting in /submit-for-review's post-merge block, and investigation-comment posting in /start Case B Step 3.
• Version-tag discovery and the bump-then-tag dance in /deploy.

The audit should also surface candidates this list doesn't anticipate. Each extraction is small and self-contained but touches multiple skill call-sites, so the work should be sliced one sequence per PR — same cadence as #159.

This ticket is the audit-and-execute parent; each extraction can either land directly under this ticket or get spun out as a child ticket if the surface area justifies it. Prefer landing small PRs against this ticket until the count gets unwieldy.

Out of scope:

• Adding override mechanisms for the scripts (users can fork a skill if they need different behavior).
• Cross-group script reuse (the rfp-tools group, when it exists, can have its own scripts/ directory; sharing is a follow-up if it's ever needed).
• Bundling Make targets or shell scripts as alternatives to Python — the tracer bullet established python3 … as the convention.
• Automated tests for the extracted scripts — deferred to Add exit-code tests for extracted github-agile scripts (deferred) #165 so the scripts can settle in production for a few weeks before their behaviour gets pinned.

Complexity

Verification / QA effort: significant

The work spans every skill in github-agile/ and must be re-validated end-to-end (/start → /submit-for-review → /deploy) per branching mode (trunk / two-branch / three-branch) after each extraction. Each individual extraction is small; the aggregate surface area is what makes this significant rather than moderate. Mitigation: one sequence per PR, gated on ./sync.py --validate plus a manual workflow run.

Acceptance Criteria

• An audit pass over all skills in skills/github-agile/ (checkpoint.md, delegate.md, deploy.md, qa.md, review.md, review-agent.md, setup.md, start.md, status.md, submit-for-review.md) identifies every mechanical sequence that fits the extraction pattern. The audit is recorded in a comment on this ticket as a checklist.
• Each identified sequence is extracted into a Python script under skills/github-agile/scripts/ and wired into its skill call-site(s). One sequence per PR, each landing under this ticket (or as a child ticket if the surface area justifies splitting).
• python3 remains the single permission-rule beneficiary — no new shell prefixes added to permissions.yaml as part of the extractions.
• After each extraction, ./sync.py --validate passes and the affected adapter outputs continue to render correctly.
• Skill markdown shrinks meaningfully across the affected files; the lines that previously enumerated mechanical steps are replaced by one-line script invocations (with {{#if}} conditionals preserved when they pick which argument to pass).
• This ticket closes when the audit checklist is fully ticked off (or when remaining items are explicitly re-classified as not-worth-extracting with a one-line rationale per item).

[sebastientaggart]

Audit Checklist — Mechanical Sequence Extractions

Confirmed from ticket body

• --body-file plumbing for gh issue create — start.md:167-186 — mkdir tmpdir + write file + invoke gh issue create --body-file; extract to create-issue-with-body.py
• --body-file plumbing for gh issue comment — start.md:227-237, submit-for-review.md:295-310, start.md:335-346 — repeated temp file + gh issue comment --body-file sequences; extract to post-issue-comment.py (subsumes the resolution-comment and investigation-comment items below)
• --body-file plumbing for gh pr create — submit-for-review.md:148-168, deploy.md:313-340, deploy.md:407-431 — mkdir tmpdir + write file + invoke gh pr create --body-file; extract to create-pr-with-body.py
• Follow-up-issue creation loop — submit-for-review.md:349-376 — loop over selected findings, build body file per iteration, create issue per item; extract to create-followup-issues.py
• Label + milestone three-tier resolution — start.md:40-84 — per-invocation flag → pool-based selection → omit; milestone: per-invocation flag → auto-detect from open milestones; extract to resolve-issue-metadata.py
• make -n <target> "verify make target exists" guard — submit-for-review.md:44-54, submit-for-review.md:210-220 — two instances of cd <repo-root> && make -n <target> for type-check and merge gates; extract to verify-make-target.py
• git fetch origin <base> && git merge origin/<base> sync — submit-for-review.md:84-101 — multi-branch conditional fetch + merge (sibling to sync-base-branch.py but merge-based instead of reset); extract to sync-base-branch-merge.py
• CODEOWNERS detection + --reviewer handle stripping — submit-for-review.md:126-175 — check for CODEOWNERS, extract reviewer handles from DEFAULT_REVIEWERS, strip leading @, apply to gh pr create --reviewer; extract to resolve-pr-reviewers.py
• Version-tag discovery + bump-then-tag dance — deploy.md:61-189 — find latest tag via git describe, run version bump command, verify tag created, create annotated fallback if needed, push commit + tags; extract to bump-and-tag-version.py

Additional candidates found

• PR body with closing-keyword reference construction — submit-for-review.md:156-162 — conditional branch logic (BRANCH_DEV vs trunk) determines Closes #N vs Issue #N format; worth consolidating given the critical note about the unqualified form; extract to build-pr-body-with-issue-ref.py (likely folded into create-pr-with-body.py)
• Git log parsing + PR fetch loop — deploy.md:75-115 — query commits since tag, parse PR numbers from merge subjects, fetch PR bodies via gh pr view, extract issue references; multi-step deterministic sequence; extract to extract-prs-and-issues-from-tag-range.py
• Milestone auto-detect from open list — start.md:76-83 — query open milestones, handle 0 / 1 / 2+ results with different user-interaction paths; orthogonal to the three-tier resolver; either subsumed by resolve-issue-metadata.py or its own helper resolve-milestone-from-open-list.py

Reviewed and rejected (not worth extracting)

• Single-line shell checks — various — git branch --show-current, git status, test -f, which gh — one-liners with no plumbing.
• Standalone gh queries with no post-processing — status.md, qa.md, review.md — gh pr list, gh issue list, gh issue view followed by display are workflow-specific, not mechanical; extraction wouldn't reduce prompts or tokens.
• Conditional branch selection based on config tokens — BRANCH_DEV vs BRANCH_PROD, BRANCH_TEST presence checks — template-time decisions handled by Handlebars expansion, not runtime mechanics.

---

Suggested ordering (cheap wins first, dependencies last):

1. post-issue-comment.py — touches 3 call-sites, smallest surface, immediate prompt savings.
2. create-issue-with-body.py — /start Step 3a/3b, well-bounded.
3. create-pr-with-body.py — /submit-for-review Step 6 and /deploy PRs; pairs naturally with the PR-body construction helper.
4. verify-make-target.py — trivial but doubles up two call-sites.
5. sync-base-branch-merge.py — sibling to existing sync-base-branch.py, near-identical shape.
6. resolve-pr-reviewers.py — CODEOWNERS + handle stripping.
7. resolve-issue-metadata.py — labels + milestone resolver; biggest surface, defer.
8. create-followup-issues.py — depends on create-issue-with-body.py.
9. bump-and-tag-version.py + extract-prs-and-issues-from-tag-range.py — /deploy cluster, ship together once the simpler extractions have validated the pattern further.

[sebastientaggart]

Resolution

First slice of this audit ticket is shipped: the repeated "write a comment body to a file, then post it via gh" sequence has been collapsed into a single one-line script invocation across three places in the workflow. Going forward, posting a comment costs one tool call instead of two, with no functional change to what gets posted.

The audit checklist (also posted above) tracks the remaining extractions; they'll land as separate PRs against this ticket.

See #166 for full technical details.