assess-pr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Assess PR and Issues

The end-of-run half of `/assess`. The report (`.assess/assess-report.md`), the complexity heatmap, and the doc graph are written. This step runs the optional end-of-run offers - in order - then closes the loop:

1. **Open a PR** with the report (Step 5).
2. **Track the Top 3 Actions** in the user's issue tracker (Step 6).
3. **Freeze the assessment into a CI gate** (Step 6.5).
4. **Tool feedback** (Step 7) - surface anomalies and offer to file feedback.
5. **Uninstall `/assess`** (Step 8) - the escape hatch: remove everything this run wrote.

Each offer is independent (uninstall excepted - it's mutually exclusive with the write-back offers): a user can accept any subset. The step references back into the written `assess-report.md` artifact (notably the Top 3 Actions table's `Issue` column), not into the scoring prose, so it stays decoupled from how the report was produced.

## Phase 2: ask once, batched (and the non-interactive contract)

These are the **write-back phase** of the consent lifecycle (Phase 2; Phase 1 was the tool installs, Phase 3 the mutation pass - see the assess SKILL.md). Do not serialise them into back-to-back modals. Present them as **one batched, multi-select AskUserQuestion**: "Now that the report is written, which of these should I do?" with the options (open a PR, track the Top 3 Actions, freeze a CI gate, file feedback, and - the mutually-exclusive escape hatch - uninstall `/assess` from this repo), pre-filtered by feasibility:

- Drop the **PR** option when the push-capability / remote check below (Step 5) shows no direct or fork PR is possible; on a read-only target, offer the fork variant instead. When the target states it takes no contributions (Step 5's no-contributions scan), offer the **no-contributions** variant instead on a read-only target (READ / TRIAGE) or in a clone of the user's own fork: a PR inside the user's fork, never one against upstream. A user who can push to the non-fork repo itself keeps the direct PR option, with the statement quoted.
- Drop the **CI gate** option when the workflow could never run (no GitHub remote).
- Keep **issue tracking** and **feedback** always (feedback needs no repo write).
- **Uninstall** (Step 8) always appears: it removes what this run wrote. It doesn't compose with the write-back offers (no point opening a PR *and* deleting the report), so treat selecting it as "skip the others and clean up".

Then execute the accepted offers **in order** (PR → issues → gate → feedback), because the later ones cross-link to the PR the first may have opened. Uninstall, if chosen, runs instead of the others. The per-step detail below is the execution recipe for each accepted offer; the *asking* happens once, here.

**Non-interactive contract (headless / CI).** When `run-context.json .interactive` is `false`, **make no AskUserQuestion call at all** - every write-back offer is already recorded as `{type, status: "skipped", reason: "non-interactive"}` in `run-context.json .offers` (`pr`, `issue_tracking`, `ci_gate`, `feedback`, `uninstall`). Write nothing back, open no PR, create no issues, emit no gate, file no feedback, uninstall nothing; the run ends with the local `.assess/` artifacts only. A headless `/assess` completes with zero prompts.

```bash
jq '{interactive, offers}' "$REPO_ROOT/.assess/run-context.json"
```

---

## Step 5: Ask Whether to Open a PR

After writing the files, first **check whether a direct PR is even possible** before offering one. A user on `READ` or `TRIAGE` access can't push a branch to the target repo, so an unconditional "open a PR?" offer is infeasible and wastes a turn.

```bash
# Detect push capability. `gh` returns viewer fields for the current user.
# Push capability is derived from `viewerPermission` (one of ADMIN |
# MAINTAIN | WRITE | TRIAGE | READ | NONE) - GitHub's GraphQL Repository
# type has no `viewerCanPush` field, so don't request it (the CLI errors
# and the whole call returns empty, silently degrading every write-
# accessible repo to the "leave local" branch).
PUSH_INFO=$(gh repo view --json viewerPermission,viewerCanAdminister,nameWithOwner,isFork,owner 2>/dev/null || true)
PERM=$(echo "$PUSH_INFO" | jq -r '.viewerPermission // empty')
case "$PERM" in
  ADMIN|MAINTAIN|WRITE) CAN_PUSH=1 ;;
  *)                    CAN_PUSH=0 ;;
esac
# A clone of the user's own fork reports ADMIN, so CAN_PUSH alone cannot tell
# the upstream's maintainer from an outsider working in their fork.
IS_FORK=$(echo "$PUSH_INFO" | jq -r '.isFork // false')
# isFork says the repo has a parent, not whose fork it is: a collaborator with
# push access to someone else's fork also sees isFork=true and WRITE. The
# current repo counts as the user's own fork only when the viewer owns it.
VIEWER_LC=$(gh api user 2>/dev/null | jq -r '.login // empty' | tr '[:upper:]' '[:lower:]')
OWNER_LC=$(echo "$PUSH_INFO" | jq -r '.owner.login // empty' | tr '[:upper:]' '[:lower:]')
if [ "$IS_FORK" = true ] && [ -n "$VIEWER_LC" ] && [ "$VIEWER_LC" = "$OWNER_LC" ]; then
  IS_OWN_FORK=true
else
  IS_OWN_FORK=false
fi
# If the command failed (no remote, no gh, not a GitHub repo, unauthenticated),
# $PUSH_INFO is empty and $PERM stays empty - fall back to the local-branch
# flow with the reason. Never silently assume push works.

# Detect remote-to-gh redirect: GitHub follows transfers/renames, so gh may
# resolve a different owner/repo than the configured remote implies.
REMOTE_URL=$(git remote get-url origin 2>/dev/null || true)
if [ -n "$REMOTE_URL" ]; then
  # Normalise SSH and HTTPS forms (and GitHub Enterprise hosts) to owner/repo.
  # SSH:   git@host:owner/repo.git   -> owner/repo
  # HTTPS: https://host/owner/repo/  -> owner/repo
  # Strip protocol, any user@, the host (not just github.com), a trailing .git,
  # and a trailing slash - so a GHE host or a trailing slash can't masquerade as
  # a redirect.
  REMOTE_SLUG=$(echo "$REMOTE_URL" \
    | sed -e 's|^[a-zA-Z]*://||' -e 's|^[^@/]*@||' -e 's|^[^/:]*[:/]||' -e 's|\.git$||' -e 's|/$||')
else
  REMOTE_SLUG=""
fi
GH_SLUG=$(echo "$PUSH_INFO" | jq -r '.nameWithOwner // empty')
# Compare case-insensitively: GitHub treats owner/repo as case-insensitive, so a
# pure case difference is not a redirect and must not emit a spurious notice.
REMOTE_SLUG_LC=$(echo "$REMOTE_SLUG" | tr '[:upper:]' '[:lower:]')
GH_SLUG_LC=$(echo "$GH_SLUG" | tr '[:upper:]' '[:lower:]')
if [ -n "$REMOTE_SLUG" ] && [ -n "$GH_SLUG" ] && [ "$REMOTE_SLUG_LC" != "$GH_SLUG_LC" ]; then
  REDIRECT_NOTICE="Note: origin (\`$REMOTE_SLUG\`) redirects to \`$GH_SLUG\`; the offers below target the redirected repo."
else
  REDIRECT_NOTICE=""
fi
```

Then check whether the target turns away outside contributions. A fork PR against a repo whose README or CONTRIBUTING says "do not send a pull request" is noise for its maintainers, so the scan runs before any upstream offer is framed:

```bash
# no-contributions scan: start
# Sets NO_CONTRIBUTIONS (1/0) plus the first matching file (relative to the
# repo root) and line, so the offer can quote the statement back to the user.
NO_CONTRIBUTIONS=0
NO_CONTRIBUTIONS_SOURCE=""
NO_CONTRIBUTIONS_STATEMENT=""
# The pattern is built from named parts so every branch shares one noun and one
# boundary. _nc_noun ends at a non-letter (_nc_end), so "prs?" cannot match the
# start of "promise", "process" or "private"; the passive branch also needs a
# non-letter before the noun. _nc_neg has no leading boundary on purpose: it
# must match the tail of "cannot".
_nc_neg="(not|n't|n’t|unable to)"
_nc_noun="(contributions|pull requests?|prs?)"
_nc_end="([^a-z]|$)"
# Three refusal phrasings:
#   accept:     "does not accept (community) contributions", "not accepting PRs"
#   imperative: "do not send a pull request" - the clause must end right after
#               the noun, so "do not open a PR for typo fixes" (a house rule
#               for contributors, not a refusal) stays out
#   passive:    "pull requests are not accepted"
_nc_accept="${_nc_neg} ([a-z-]+ )?accept(ing)? ([a-z-]+ )?${_nc_noun}${_nc_end}"
_nc_imperative="${_nc_neg} (send|open|submit) (a |any |us )?${_nc_noun}[[:space:]]*([.;!)]|$)"
_nc_passive="(^|[^a-z])${_nc_noun} (are|is|will) not (be )?accepted"
_nc_re="${_nc_accept}|${_nc_imperative}|${_nc_passive}"

From bjcoombs/ai-native-toolkit, Apache-2.0.

More from bjcoombs/ai-native-toolkit