|
| 1 | +--- |
| 2 | +name: azip-editor-review |
| 3 | +description: Review an AZIP pull request from the perspective of an AZIP editor (administrative review only — formatting, completeness, process), check the linked discussion, and surface the manual edits that PR 18 (link-azip-to-discussion workflow) will eventually automate. Use when the user asks to "do an editor review" / "review this PR as editor" / "editor pass" on a PR that touches `AZIPs/**.md`. AZIP authors can also use it as a self-check before requesting review. |
| 4 | +argument-hint: "<pr-number-or-url>" |
| 5 | +--- |
| 6 | + |
| 7 | +# AZIP Editor PR Review |
| 8 | + |
| 9 | +This skill runs the editor's review for an AZIP PR. The editor's role is **strictly administrative**: format, completeness, and process — never substantive. Editors cannot block on the merits of a proposal; that is Core Contributors' job during RFD review. |
| 10 | + |
| 11 | +The output of this skill is: |
| 12 | + |
| 13 | +1. A structured review of the PR against the editor checklist. |
| 14 | +2. A review of the linked GitHub Discussion. |
| 15 | +3. A list of manual edits to apply now that PR 18's workflow will automate once it lands. |
| 16 | +4. A draft of the editor's review comment to post on the PR. |
| 17 | + |
| 18 | +## Inputs |
| 19 | + |
| 20 | +Invoke with a PR number (e.g. `/azip-editor-review 23`) or a PR URL. If neither is given, ask for it before proceeding. The repo is always `AztecProtocol/governance`. |
| 21 | + |
| 22 | +Assume `gh` is already installed and authenticated against GitHub. |
| 23 | + |
| 24 | +## Step 1 — Read the PR |
| 25 | + |
| 26 | +Fetch the PR metadata and the changed AZIP files: |
| 27 | + |
| 28 | +```bash |
| 29 | +gh pr view <PR> --repo AztecProtocol/governance --json number,title,body,author,headRefOid,headRefName,state,files,reviews,comments |
| 30 | +gh pr diff <PR> --repo AztecProtocol/governance |
| 31 | +``` |
| 32 | + |
| 33 | +Identify the AZIP markdown file(s) changed under `AZIPs/`. Skip `AZIPs/template.md`. Read each changed file at the PR's head ref. |
| 34 | + |
| 35 | +## Step 2 — Editor checklist |
| 36 | + |
| 37 | +Run through this checklist for each changed AZIP. Report PASS / FAIL / N/A with a one-line note for each item. **Do not evaluate technical correctness or whether the proposal is a good idea — that is out of scope.** |
| 38 | + |
| 39 | +### Preamble |
| 40 | + |
| 41 | +- [ ] Preamble table is present and matches the template format (header row, separator, single data row). |
| 42 | +- [ ] `azip` number is assigned and is the next sequential number (see Step 3). |
| 43 | +- [ ] `title` is filled, ≤ 80 chars, does not include the AZIP number, does not include "standard" or variants. |
| 44 | +- [ ] `description` is filled, ≤ 140 chars, does not include the AZIP number or "standard". |
| 45 | +- [ ] `author` includes at least one entry with a GitHub username (`@handle`). |
| 46 | +- [ ] `discussions-to` is a URL of the form `https://github.com/AztecProtocol/governance/discussions/<N>`, or a link to the aztec forum. |
| 47 | +- [ ] `status` is `Draft` (PR is not yet merged). |
| 48 | +- [ ] `category` is one of `Core`, `Economics`, `Standard`, `Informational`. |
| 49 | +- [ ] `created` is a valid ISO 8601 date (yyyy-mm-dd). |
| 50 | +- [ ] `requires` (if present) lists valid AZIP numbers. |
| 51 | + |
| 52 | +### Required sections (per category) |
| 53 | + |
| 54 | +All AZIPs need: Abstract, Motivation, Rationale, Backwards Compatibility, Copyright Waiver. |
| 55 | + |
| 56 | +Additionally: |
| 57 | + |
| 58 | +- `Core` and `Standard`: Specification + Security Considerations. |
| 59 | +- `Economics`: Economics Considerations + Security Considerations. |
| 60 | +- `Informational`: only the universal sections above. |
| 61 | + |
| 62 | +For each required section: present? not a template placeholder? not a TBD? |
| 63 | + |
| 64 | +### Style and markup |
| 65 | + |
| 66 | +- [ ] No external links other than `forum.aztec.network` and `github.com/AztecProtocol/governance` (the only allowed externals per `azip-process.md`). |
| 67 | +- [ ] References to other AZIPs use the `AZIP-N` form, with a relative markdown link on first reference. |
| 68 | +- [ ] Assets, if any, live under `assets/azip-<N>/` and are referenced via relative paths. |
| 69 | +- [ ] Copyright waiver text matches exactly: `Copyright and related rights waived via [CC0](/LICENSE).` |
| 70 | +- [ ] No obvious grammar / spelling / markup errors. Note any. |
| 71 | + |
| 72 | +### Process |
| 73 | + |
| 74 | +- [ ] PR description is reasonable and a discussion link is present. |
| 75 | +- [ ] Linked discussion exists in the `azip-proposals` category (Step 4 verifies). |
| 76 | +- [ ] For Core/Standard/Economics: Security Considerations is non-trivial — the editor checks **presence and that reviewers have engaged with it**, not whether the analysis is correct. The reviewers (Core Contributors, peers) judge sufficiency. |
| 77 | +- [ ] If the PR is being readied for merge to advance Draft → RFD: there is provable peer review in the PR comments and provable engagement from impacted stakeholders. |
| 78 | + |
| 79 | +## Step 3 — AZIP number assignment |
| 80 | + |
| 81 | +If the AZIP file is named `AZIPs/azip-N.md` and the preamble's `azip` field is empty or `TBD`, assign the next sequential number: |
| 82 | + |
| 83 | +```bash |
| 84 | +ls AZIPs/ | grep -E '^azip-[0-9]+\.md$' | sed 's/[^0-9]//g' | sort -n | tail -1 |
| 85 | +``` |
| 86 | + |
| 87 | +Also check open AZIP PRs to avoid colliding with a number that's already been claimed but not yet merged: |
| 88 | + |
| 89 | +```bash |
| 90 | +gh pr list --repo AztecProtocol/governance --state open --json number,title,headRefName |
| 91 | +``` |
| 92 | + |
| 93 | +## Step 4 — Review the linked discussion |
| 94 | + |
| 95 | +Parse `discussions-to` from the preamble. Fetch the discussion: |
| 96 | + |
| 97 | +```bash |
| 98 | +gh api graphql -f query=' |
| 99 | + query($owner: String!, $name: String!, $number: Int!) { |
| 100 | + repository(owner: $owner, name: $name) { |
| 101 | + discussion(number: $number) { |
| 102 | + title body category { slug name } url |
| 103 | + labels(first: 50) { nodes { name } } |
| 104 | + comments(first: 50) { |
| 105 | + totalCount |
| 106 | + nodes { author { login } body createdAt } |
| 107 | + } |
| 108 | + } |
| 109 | + } |
| 110 | + }' -F owner=AztecProtocol -F name=governance -F number=<DISC> |
| 111 | +``` |
| 112 | + |
| 113 | +Check: |
| 114 | + |
| 115 | +- [ ] Discussion is in the `azip-proposals` category. (If not, this is a hard fail — the workflow in PR 18 will refuse to touch it. Ask the author to migrate the discussion or update `discussions-to`.) |
| 116 | +- [ ] Discussion is reachable and not locked. |
| 117 | +- [ ] Comments show non-author engagement. Summarize who has weighed in (logins + count) so the editor can decide if peer review is sufficient for an RFD merge. |
| 118 | +- [ ] Note any open concerns raised in the discussion that haven't been addressed in the AZIP. |
| 119 | + |
| 120 | +## Step 5 — Manual edits PR 18 will eventually automate |
| 121 | + |
| 122 | +PR 18 adds a `pull_request_target` workflow that, on every AZIP PR push, will: |
| 123 | + |
| 124 | +1. Apply the `has-azip` label to the linked discussion. |
| 125 | +2. Prepend `**AZIP:** [AZIP-N](<pr-url>)` to the discussion body (idempotently). |
| 126 | +3. Prefix the discussion title with `AZIP-N: `. |
| 127 | + |
| 128 | +Until PR 18 is merged, the editor does this by hand. For the PR being reviewed, produce the three concrete edits the editor needs to make on the discussion: |
| 129 | + |
| 130 | +1. **Title change**: current → desired. |
| 131 | + - Desired: `AZIP-<N>: <current title with any existing AZIP-K prefix stripped>`. |
| 132 | +2. **Body prepend**: show the exact line to add at the top: |
| 133 | + - `**AZIP:** [AZIP-<N>](<pr-url>)` |
| 134 | + - If a stale `**AZIP:** [AZIP-K](...)` line is already at the top, replace it rather than stack. |
| 135 | +3. **Label**: add `has-azip` to the discussion if not already present. Verify the label exists on the repo first: |
| 136 | + |
| 137 | +```bash |
| 138 | +gh api graphql -f query='query($o:String!,$n:String!){repository(owner:$o,name:$n){label(name:"has-azip"){id}}}' -F o=AztecProtocol -F n=governance |
| 139 | +``` |
| 140 | + |
| 141 | +Present these as a copy-pasteable list. Do **not** apply them automatically — the editor applies them via the GitHub UI or `gh` so the audit trail is clean. (Once PR 18 lands, this whole step becomes a no-op and should be removed from the skill.) |
| 142 | + |
| 143 | +## Step 6 — Print the changes that are needed |
| 144 | + |
| 145 | +Output a flat, copy-pasteable list of every change required for the AZIP to pass an editor review. No PR comment template, no boilerplate scope statements — just the actionable items, grouped by where the change goes. |
| 146 | + |
| 147 | +Suggested layout: |
| 148 | + |
| 149 | +``` |
| 150 | +### Required changes (in `AZIPs/azip-<N>.md`) |
| 151 | +- <change 1, with the exact line / cell / section to edit> |
| 152 | +- <change 2> |
| 153 | +
|
| 154 | +### Required changes (PR / discussion) |
| 155 | +- <e.g. "create discussion in azip-proposals category and update `discussions-to`"> |
| 156 | +- <e.g. "add PR description with discussion link"> |
| 157 | +
|
| 158 | +### Nits (non-blocking) |
| 159 | +- <minor formatting / whitespace items> |
| 160 | +
|
| 161 | +### Flagged for reviewers (not editor objections) |
| 162 | +- <anything borderline-substantive that Core Contributors should weigh in on> |
| 163 | +
|
| 164 | +### Discussion sync (manual until #18 lands) |
| 165 | +- Title → `AZIP-<N>: <stripped title>` |
| 166 | +- Body prepend: `**AZIP:** [AZIP-<N>](<pr-url>)` |
| 167 | +- Label: `has-azip` |
| 168 | +``` |
| 169 | + |
| 170 | +Keep entries terse and concrete (one line each, naming the exact field/section). The editor or author decides what to do with the list; the skill doesn't pre-write a review comment for them. |
| 171 | + |
| 172 | +If a section has no items, omit the heading rather than printing "none". |
| 173 | + |
| 174 | +## Notes on what NOT to do |
| 175 | + |
| 176 | +- Do **not** evaluate whether the proposal is a good idea, technically correct, or aligned with the roadmap. That is reviewer / Core Contributor territory. |
| 177 | +- Do **not** push commits to the PR branch. Suggest changes; the author applies them. |
| 178 | +- Do **not** mutate the discussion automatically. Hand the edits to the editor. |
| 179 | +- Do **not** merge the PR. Even when everything checks out, the editor merges manually after confirming peer review and stakeholder engagement. |
| 180 | +- Do **not** assign an AZIP number if one is already assigned, even if it is out of sequence — reassignment is an explicit editorial decision. |
| 181 | + |
| 182 | +## References |
| 183 | + |
| 184 | +- `README.md` — editor list and contributor flow. |
| 185 | +- `azip-process.md` — full lifecycle, content requirements, editor responsibilities. |
| 186 | +- `governance-manual.md` — broader governance context, dispute handling. |
| 187 | +- `AZIPs/template.md` — template the preamble and sections must match. |
| 188 | +- PR #18 (`workflow/link-azip-to-discussion`) — the automation that will replace Step 5 once merged. |
0 commit comments