codeassembly-guidance 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,303 @@
1
+ ---
2
+ name: review-branch
3
+ description: Perform code review of branch changes against a diff base
4
+ user-invocable: true
5
+ dependencies:
6
+ skills:
7
+ - review-criteria
8
+ ---
9
+
10
+ # Review branch
11
+
12
+ Act as a conscientious code reviewer for the changes on the current branch relative to a diff base. Review the diff `merge-base(HEAD, <diff-base>)..HEAD`.
13
+
14
+ This skill is the canonical home of the shared review process. `review-pr` invokes the same review process after resolving platform-specific inputs (PR metadata, HEAD verification, ticket from PR linked issues, PR description as a second specification source).
15
+
16
+ ## Arguments
17
+
18
+ | Flag | Effect | Default |
19
+ | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
20
+ | `--diff-base=<ref>` | Reference to diff against. Reviews `merge-base(HEAD, <ref>)..HEAD`. | Project's default branch |
21
+ | `--ticket=<source>` | Ticket or requirements to check the implementation against. Resolved per [ticket source resolution](../_data/ticket-source-resolution.md). | Auto-resolved (see below) |
22
+ | `--spec-source=remote\|local` | When the ticket is auto-resolved (i.e. `--ticket` is omitted), force which candidate is selected instead of the recency comparison. Ignored when `--ticket` is given. | Newest of the remote issue vs. the local snapshot |
23
+
24
+ ## Process
25
+
26
+ > **When invoked by `review-pr`:** Steps 1–3 are already complete: `review-pr` already invoked the bundled session-context deriver and the platform delegate resolved `merge_base_sha` and `spec_sources`. Begin at step 4 with these values in scope.
27
+
28
+ 1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `default_branch`, `ticket_id`, `ticket_ref`, `scm`, `project_slug`, and `artifact_base_dir` from it.
29
+ 2. **Resolve diff base**: If `--diff-base=<ref>` was provided, use `<ref>`; otherwise use `default_branch`. Compute the merge-base SHA once: `git merge-base HEAD <diff-base>`. Use this SHA for the diff command in step 5.
30
+ 3. **Resolve specification sources**: Produce a list of spec sources (each a `{ source_type, label, content, criteria?, provenance, last_updated }` record). `provenance` is `remote` (a live platform fetch, never stale) or `local_snapshot` (a frozen plan-time artifact that can lag the contract); `last_updated` is the source's last-modified timestamp (ISO 8601), or null when the platform does not expose one.
31
+ - **Explicit `--ticket=<source>`**: Resolve per [ticket source resolution](../_data/ticket-source-resolution.md) and append as a `ticket` source. A fetched platform issue is `remote` with its `updatedAt` as `last_updated`; a file or plain-text source is `local_snapshot` with `last_updated` null when unknown. When the source resolves to a URL, persist it per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url). `--spec-source` does not apply on this path.
32
+ - **Auto-resolve** (when `--ticket` is omitted): Resolve up to two candidates and choose between them.
33
+ - _Remote candidate_: When `ticket_id` is non-null and resolves to a platform ticket (use `scm` from step 1), fetch the remote issue per [ticket source resolution](../_data/ticket-source-resolution.md#auto-resolve), but substitute the local fallback below for that section's "ask the user" terminal step. Its `last_updated` is the issue's `updatedAt`.
34
+ - _Local candidate_: The most recent `*_ticket.md` under `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`. Its `last_updated` is the filename's `YYYYMMDD-HHMMSSZ` prefix converted to ISO 8601 (`YYYY-MM-DDTHH:MM:SSZ`), so it shares the remote candidate's format; if the prefix is unparseable, treat the local candidate as unavailable. (The artifact filename keeps the compact form per `artifact-conventions.md`; only the recorded `last_updated` is normalized.) Read its frontmatter as well as its filename: `copies_remote` decides the selection below, per [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter).
35
+ - _Selection_:
36
+ - If `--spec-source=remote|local` is set, use that candidate. If the named candidate is unavailable (e.g. `--spec-source=local` without a snapshot, or `--spec-source=remote` with a failed/offline fetch or null `ticket_id`), stop and report the missing source rather than silently using the other side: An explicit instruction must not be redirected to the wrong contract. State the remedy (drop the flag to re-enable recency) in the message.
37
+ - Otherwise, if a remote candidate exists and the local candidate's frontmatter sets `copies_remote: true`, use the remote candidate. The snapshot's body is a copy of the ticket of record, so the remote contains at least the content that the snapshot froze, and the snapshot's later write time records the copying rather than a newer contract. A snapshot that does not make that claim falls through to the comparison below.
38
+ - Otherwise use the candidate with the newer `last_updated`. Because both values are ISO 8601 at the same precision, they compare chronologically as plain strings, without per-format parsing. On an exact tie, prefer the remote candidate (canonical for the owned-ticket majority).
39
+ - If only one candidate exists, use it. This single-candidate fallback also covers a failed/offline remote fetch and a null `ticket_id`.
40
+ - Append the chosen candidate as a `ticket` source with its `provenance` and `last_updated`. When the chosen source is the local snapshot and a remote candidate existed, keep that rejected candidate's `content` in-process for the divergence check. Keep raw content rather than extracted criteria: The comparison runs at render time under the extraction rule that the compliance table states, so both candidates are read by one rule. It stays in working memory, not in the `spec_sources` record, because resolution here and rendering in the output are the same `review-branch` invocation (which is also why the record needs only one `last_updated`). When the chosen source is the remote candidate, retain nothing; the callout never appears on that branch.
41
+ - **No source available**: Leave the list empty. The "Specification compliance" section is omitted from the output.
42
+
43
+ `review-pr` may pass additional sources (notably the PR description as `pr_description`). The list is the canonical input for the "Specification compliance" section regardless of who populated it.
44
+
45
+ 4. **Read prior artifacts**: When `ticket_id` is not null, invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs active --ticket-dir {artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` via Bash. The helper prints `{ "runDir": <path or null> }`: the ticket's active run, per [artifact conventions](../_data/artifact-conventions.md#run-directories). When `runDir` is not null, read all artifacts in it chronologically for context (including any prior dispositions).
46
+ 5. **Analyze changes**: `git diff <merge-base-sha>..HEAD`.
47
+ 6. **Review thoroughly** following the guidelines below.
48
+ 7. **Challenge your own findings**: Re-read each finding and delete every one that you would not defend to a skeptical author asking "why does this matter?" A review may legitimately end with zero findings.
49
+ 8. **Assign a score** out of 10.
50
+ 9. **Resolve frontmatter fields** before saving; see [Frontmatter resolution](#frontmatter-resolution).
51
+ 10. **Save the review** per the [Saving](#saving) section.
52
+ 11. **Present next steps**: After saving, present a next-steps prompt following [next-steps options](#next-steps-options). Supply recommendation context: finding counts and categories from the review, which criteria the specification compliance section marked in conflict with the implementation, and the consistency verdict when the consistency section was rendered. The next-steps prompt is interactive output only and is not saved in the review artifact.
53
+
54
+ ## Frontmatter resolution
55
+
56
+ The artifact's frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
57
+
58
+ Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`. Resolve `{author}` from `git log --format='%an' "{default_branch}..HEAD" | sort -u | paste -sd, -` (unique authors of the commits under review). When invoked via `review-pr`, take `{pr_url}` from `pr_metadata.url` (the PR under review); otherwise it does not have a value.
59
+
60
+ Run via Bash, writing each resolved value into the call as literal text and dropping the `--override` flag if `{pr_url}` does not have a value:
61
+
62
+ ```bash
63
+ {harness_home_dir}/scripts/resolve-frontmatter.sh \
64
+ --skill review-branch \
65
+ --interactive true \
66
+ --model "{model_id}" \
67
+ --extra "author={author}" \
68
+ --override "pr={pr_url}"
69
+ ```
70
+
71
+ Prepend the script's output verbatim to the artifact body. The `pr:` field is populated only when reviewing a PR (via `review-pr`); a direct ticket-only review omits it.
72
+
73
+ ## Review guidelines
74
+
75
+ A no-findings review is a complete, valid outcome and the expected default for a clean change: merge-ready, not lazy or unfinished. Raise a finding only when it genuinely warrants the author's action; finding none is success, not a gap to fill.
76
+
77
+ Comprehensive review: Trace logic, verify edge cases, assess architectural impact.
78
+
79
+ ### Criteria
80
+
81
+ Read and apply the `review-criteria` skill (`../review-criteria/SKILL.md`). Additionally for this skill:
82
+
83
+ - Reference associated Jira ticket if integrations.jira.enabled is true
84
+ - Look at commit messages for context
85
+ - Suggest refactoring if new code adds tech debt
86
+
87
+ <!-- guidance-hook: implementation-preferences -->
88
+
89
+ ## Issue numbering
90
+
91
+ Uniquely number all issues for easy reference. See [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix) for full category criteria and criticality mapping.
92
+
93
+ - FIXMEs: `F{n}`. Critical, must fix before merge
94
+ - Warnings: `W{n}`. Questionable decisions, may block merge
95
+ - TODOs: `T{n}`. Should fix, can wait for next PR
96
+ - Recommendations: `R{n}`. Advisable but discretionary
97
+ - Suggestions: `S{n}`. Optional improvement
98
+ - Legacy: `{F,W,T,R,S}{n}-L`. Observation in pre-existing code, not authored in this change. Same severity letter as the equivalent author finding; number it from that letter's shared sequence first, then append `-L` as a marker (e.g., after `F1`, `F2`, the first legacy FIXME is `F3-L`)
99
+ - Insights: `I{n}`. Knowledge worth preserving, gated per the [insight gate](../review-criteria/SKILL.md#insight-gate); does not have a severity and does not count against the score
100
+
101
+ ## Output format
102
+
103
+ Section-header icons (🚨, ⚠️, 📋, 🧠, ☝️, 🔍) come from the canonical [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix), and the 💡 insights icon from [knowledge items](../_data/artifact-conventions.md#knowledge-items); render them as shown. Each finding under "Action required" and "Areas for improvement" follows the canonical per-finding template shown below; see [`review-criteria` § Finding references](../review-criteria/SKILL.md#finding-references) for the rules governing the `Location:` field.
104
+
105
+ When `ticket_ref` is null (the branch does not have a ticket), omit the `{ticket_ref}: ` portion so that the heading reads naturally without it, e.g., `# Code review: {description}`.
106
+
107
+ The artifact begins with YAML frontmatter conforming to the canonical schema; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter) and the field-resolution steps in the [Frontmatter resolution](#frontmatter-resolution) section above. Pass `--extra "author={author}"` to the script to populate the review-artifact `author` field.
108
+
109
+ The body following the frontmatter has this structure:
110
+
111
+ ```markdown
112
+ # Code review: {ticket_ref}: {description in imperative mood}
113
+
114
+ ## Summary of changes
115
+
116
+ ## Strengths
117
+
118
+ ### Code quality
119
+
120
+ ### Documentation
121
+
122
+ ### Test quality
123
+
124
+ ## Action required
125
+
126
+ ### FIXMEs 🚨
127
+
128
+ {Critical issues - regressions, broken functionality, unsafe code, type safety violations}
129
+
130
+ #### F1: {title}
131
+
132
+ - **Location:** `path/to/file.ts:42`
133
+ - **Severity:** critical
134
+ - **Description:** {what is wrong}
135
+ - **Recommendation:** {what to do}
136
+
137
+ (The same shape applies to every finding in the sections below: Only the prefix letter, the `Severity:` value, and the section bucket change. Legacy findings use `-L` suffix IDs and `(legacy)` severity values.)
138
+
139
+ ### Warnings ⚠️
140
+
141
+ {Questionable decisions that may block merge - require justification}
142
+
143
+ ### TODOs 📋
144
+
145
+ {Should-fix changes that can wait for next PR}
146
+
147
+ ## Areas for improvement
148
+
149
+ ### Recommendations 🧠
150
+
151
+ {Advisable but discretionary}
152
+
153
+ ### Suggestions ☝️
154
+
155
+ {Optional improvements}
156
+
157
+ ### Legacy observations 🔍
158
+
159
+ {Observations in pre-existing code, using severity-tagged IDs with `-L` suffix (e.g., `F3-L`, `T2-L`). Frame as future opportunities, don't count against score}
160
+
161
+ ## Insights
162
+
163
+ {Knowledge worth preserving that is not a finding (a pattern, gotcha, or architectural learning found during review). Gated per the [insight gate](../review-criteria/SKILL.md#insight-gate); does not have a severity and does not count against the score. Omit this section entirely when there are none.}
164
+
165
+ ### I1: {title}
166
+
167
+ - **Description:** {the insight and why a future reader is worse off without it}
168
+ - **Destination:** {optional: `ticket comment` or `devlog`}
169
+
170
+ ## Technical assessment
171
+
172
+ {Why the change is correct and adequately tested. For a change to a visible component, what the browser check in {rulebook:accessibility-conventions} found, or that it did not run and which elements it would have covered.}
173
+
174
+ ## Conclusion
175
+
176
+ Score: X/10
177
+
178
+ ## Specification compliance
179
+
180
+ {Omit this entire section when the spec-source list is empty. Otherwise render one subsection per source. With one source the section is structurally identical to the prior single-ticket "Ticket compliance" output; with two or more, repeat the subsection per source.}
181
+
182
+ ### {source.label}
183
+
184
+ {The label is `{source_type}: {short identifier}`, for example, `ticket: #553` or `pr_description: PR #1024`. Use the source's natural identifier so that a reader can tell at a glance which specification a row evaluates against.}
185
+
186
+ **Source:** {Render the source's `provenance` and `last_updated` (echoed verbatim; `last_updated` is already ISO 8601) so that the reader knows what contract this section measured against, e.g. `remote issue (last updated 2026-06-07T01:56:34Z)`, ``local snapshot `20260606-090337Z_..._ticket.md` (last updated 2026-06-06T09:03:37Z)``, or `local source (last updated …)` for an explicit file/plain-text `--ticket` that has no snapshot filename. Omit the "last updated" clause when `last_updated` is null.}
187
+
188
+ {When the chosen source is the local snapshot and a remote candidate existed, compare their acceptance criteria by the same extraction rule that the table below uses. Add a callout only when they differ materially: a criterion on one side without a counterpart on the other (absence on either side counts), or worded differently enough that the verdict could differ. Rewording that cannot change a verdict is not material. The callout names the difference with a ⚠️, states that this review measured against the snapshot rather than the published ticket, and points to `--spec-source=remote` to re-resolve against the remote. Say nothing when the criteria agree, whatever the timestamps. Omit entirely when the chosen source is the remote candidate, when resolution did not find a competing candidate (single source or explicit `--ticket`), or for a `pr_description` source.}
189
+
190
+ #### Acceptance criteria
191
+
192
+ | # | Criterion | Status | Notes |
193
+ | --- | ---------------- | -------- | ------- |
194
+ | 1 | {criterion text} | {status} | {notes} |
195
+
196
+ Status values: ✅ Met, ⚠️ Partial, ❌ Not addressed
197
+
198
+ Assign the status against the criterion's substantive guarantee, not its wording. A criterion is ✅ Met when the implementation delivers that guarantee, whatever shape it took: A criterion phrased "merges additively" is met by an implementation that refuses by default and merges under a flag, because it never overwrites. Implementation that goes beyond a criterion is ✅ Met as well; the excess is reported under Unplanned work and is never a shortfall.
199
+
200
+ ⚠️ Partial and ❌ Not addressed mean the guarantee is undelivered. Two situations produce them, and the Notes cell states which, because only one is a deviation:
201
+
202
+ - **Unbuilt**: The work is incomplete. At review time this is ordinary, and the contract is not in question.
203
+ - **In conflict**: The implementation took a direction that the criterion contradicts, such that a reader who has the criteria would judge the implementation wrong. In a ticket source, this is the sole input to the Deviations sub-block in [next-steps options](#next-steps-options).
204
+
205
+ Extract criteria from whatever structure the source uses (numbered lists, checkboxes, prose). If the source does not have clearly delimited acceptance criteria, derive them from its problem statement and solution description. PR descriptions typically expose criteria as the bullet items under `## What`, `## Summary`, or an explicit acceptance-criteria heading; fall back to the description body when the description does not contain a list.
206
+
207
+ #### Unplanned work
208
+
209
+ {Bullet list of changes not traceable to any criterion in this source. If none, state "None."}
210
+
211
+ #### Assessment
212
+
213
+ {1-2 sentence summary of alignment between the implementation and this source.}
214
+
215
+ ## Specification consistency
216
+
217
+ {Omit this entire section when fewer than two spec sources are present. Otherwise assess semantic alignment across (ticket, PR description, implementation) and render the verdict line plus the per-aspect table below. Include the Details subsection only for rows whose Summary cell cannot fit the explanation.}
218
+
219
+ 🔗 **Consistency:** {emoji} `{verdict}`
220
+
221
+ | # | Aspect | Ticket | PR description | Implementation | Summary |
222
+ | --- | -------------- | ------- | -------------- | -------------------------- | ----------------------------------------- |
223
+ | D1 | {aspect label} | {state} | {state} | {ticket-state}, {PR-state} | {one-line synthesis with concrete values} |
224
+
225
+ Verdict scale (max across all rows): 🟢 `none` (all three aligned; section omitted entirely) / 🟠 `partial` (implementation aligns with one spec source but not the other) / 🔴 `severe` (implementation aligns with neither, or sources contradict each other on a central claim).
226
+
227
+ Cell encoding:
228
+
229
+ | Symbol | Meaning |
230
+ | ----------- | ------------------------------------------------ |
231
+ | ⚫ baseline | This source defines the aspect on this row |
232
+ | ⚪ omitted | This source does not make a claim to compare |
233
+ | 🟢 {ref} | Matches the named reference (semantic alignment) |
234
+ | 🟠 {ref} | Partial mismatch with the named reference |
235
+ | 🔴 {ref} | Severe mismatch with the named reference |
236
+
237
+ Baseline-selection rule: Ticket is baseline when it mentions the aspect; otherwise PR description is baseline. An aspect introduced only by the implementation belongs in `## Specification compliance`'s "Unplanned work" sub-section, not here.
238
+
239
+ Implementation-column ordering: always `{ticket-state}, {PR-state}` regardless of which is meaningful, so that every row reads in the same order.
240
+
241
+ Only rows in which at least two of (ticket, PR description, implementation) differ belong in this table. Fully-aligned aspects appear in `## Specification compliance`, not here.
242
+
243
+ ### Details
244
+
245
+ **D{n}: {aspect label}.** {Free-form prose elaborating aspects that the Summary cell cannot fit. Each entry keys to a `D{n}` ID for cross-reference.}
246
+
247
+ Paraphrasing is not divergence: Evaluate semantic alignment, not textual overlap. The verdict is independent of the F/W/T/R/S finding scheme; author-actionable issues continue to be reported in the existing finding sections. When the PR description defers entirely to the ticket (e.g., a body of just `Closes #N` and a sentence), render a single Details paragraph noting the deferral and emit verdict `none` without a table.
248
+ ```
249
+
250
+ ### Clean reviews
251
+
252
+ When a change does not warrant any findings, render it on this shape rather than as empty `### FIXMEs` / "None." scaffolding:
253
+
254
+ ```markdown
255
+ ## Action required
256
+
257
+ None.
258
+
259
+ ## Areas for improvement
260
+
261
+ None.
262
+
263
+ ## Technical assessment
264
+
265
+ {Why the change is correct and adequately tested. For a change to a visible component, what the browser check in {rulebook:accessibility-conventions} found, or that it did not run and which elements it would have covered.}
266
+
267
+ ## Conclusion
268
+
269
+ A focused, well-tested change without outstanding issues. Merge-ready.
270
+
271
+ Score: 10/10
272
+ ```
273
+
274
+ ## Scoring
275
+
276
+ The score is an honest, at-a-glance quality signal.
277
+
278
+ - A no-findings review is 10/10.
279
+ - Every authored finding that survives the self-challenge lowers the score, weighted by severity from `F` (heaviest) down to `S` (lightest). Every tier lowers the score: A finding worth raising is a finding worth a deduction.
280
+ - Score only the change under review; Legacy and other pre-existing observations never affect the score.
281
+ - Never suppress a real finding to protect a perfect score. An honest 8 is better than a flattering 10.
282
+
283
+ ## Saving
284
+
285
+ ### Path resolution
286
+
287
+ Use `artifact_base_dir`, `project_slug`, and `ticket_id` from step 1.
288
+
289
+ Follow [artifact conventions](../_data/artifact-conventions.md).
290
+
291
+ ### Run artifact
292
+
293
+ The review is saved as a run artifact: `{timestamp}_reviewer_review.md`
294
+
295
+ 1. Resolve ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`. When `ticket_id` is null, auto-generate one in the format `{YYYYMMDD}-{4 random hex}` per [artifact conventions](../_data/artifact-conventions.md#ticket-id); never construct a path with a literal `null` segment.
296
+ 2. Open the run directory: Invoke `node {harness_home_dir}/scripts/resolve-review-run.mjs open --ticket-dir <ticket-dir> --timestamp <timestamp>` via Bash, passing this review's UTC `YYYYMMDD-HHMMSSZ` timestamp. The helper prints `{ "runDir": "<path>" }`: the ticket's active run, or a new `{timestamp}-interactive` run when the ticket directory does not contain one. On a malformed timestamp it exits non-zero and names the problem on stderr.
297
+ 3. Save: `{runDir}/{timestamp}_reviewer_review.md`
298
+
299
+ Each review is a separate artifact in the run directory. Do not append to existing files: The chronological sequence of files is the history.
300
+
301
+ <!-- include: ../_partials/next-steps-after-review.md / -->
302
+
303
+ <!-- include: ../_partials/option-format.md / -->
@@ -0,0 +1,141 @@
1
+ ---
2
+ name: review-criteria
3
+ description: Evaluation criteria and finding classification for code review
4
+ user-invocable: false
5
+ dependencies:
6
+ skills:
7
+ - anti-patterns
8
+ - testing-conventions
9
+ ---
10
+
11
+ # Review criteria
12
+
13
+ Evaluation criteria for code review. Apply proportionally: Match depth to risk.
14
+
15
+ ## Examine
16
+
17
+ - **Correctness**: Logic errors, unhandled error paths, data loss risks
18
+ - **Data changes**: A change that removes or renames data that deployed code still reads, or that depends on a migration run before merge (see {rulebook:shared-data-conventions})
19
+ - **Interfaces**: A change that defines or changes colour tokens, text styles, or a page or UI component (see {rulebook:accessibility-conventions}). For each new or changed interactive element, ask whether it shows that it is interactive, by the states that the rulebook names, and check it in a browser as the rulebook requires rather than by reading the diff alone
20
+ - **Conventions**: Adherence to codebase patterns and project standards
21
+ - **Edge cases**: Boundary conditions, empty collections, zero values, undefined states
22
+ - **Test coverage**: Adequate tests for new functionality; tests that verify behavior and are worth keeping, not just coverage
23
+ - **Clarity**: Naming, documentation, and instructions convey unambiguous intent
24
+ - **Contracts**: Documented behaviors match implementations; implicit assumptions are explicit
25
+ - **Type safety**: Type issues that affect correctness or maintainability
26
+ - **Modern patterns**: Current best practices over outdated approaches
27
+
28
+ ## Skip
29
+
30
+ - Lint or formatting issues (automated tools handle these), e.g., unused imports, missing semicolons, import order, whitespace. Do not create findings for issues that CI linters will catch; at most mention them in passing prose.
31
+ - Author-introduced suppression directives are in scope. A new lint/type suppression added in this change defaults to a Warning (⚠️) unless its rationale demonstrates a legitimate carve-out (see `anti-patterns`). Pre-existing suppressions in unchanged code remain Legacy.
32
+ - Pre-existing issues in unchanged code (categorize as Legacy if noted)
33
+
34
+ ## Logic verification
35
+
36
+ - Trace 2–3 concrete examples with realistic inputs through changed code
37
+ - Test edge cases: zero values, single vs. multiple items, undefined states
38
+ - Watch for variable confusion, context mismatches, assumption violations
39
+ - Verify tests reveal logical errors, not just achieve coverage
40
+
41
+ ## Distinguish author work from legacy
42
+
43
+ Focus findings (F/W/T) only on code authored in the current change; observations in pre-existing code belong in Legacy (suffix `-L`).
44
+
45
+ ## Finding scheme
46
+
47
+ Findings use the canonical [finding scheme](../_data/artifact-conventions.md#finding-scheme-fwtrs--legacy-suffix); see that section for the table, category criteria, criticality mapping, and re-review escalation chain.
48
+
49
+ ## Proposed-change gate
50
+
51
+ A finding is a proposed change. Name the change before writing the finding: A problem is an observation, not a finding, when you cannot pair it with a change that you would make. Record it as an insight when it contains knowledge that a future reader needs, and drop it otherwise. Naming the change is not settling it: When more than one change would resolve the problem and choosing among them depends on knowledge that the author has, name the alternatives and say the choice is theirs, because the author knows something you do not, never because you could not settle on a fix. Full treatment: [finding scheme § Proposed-change gate](../_data/artifact-conventions.md#proposed-change-gate).
52
+
53
+ ## Actionability gate
54
+
55
+ A named change still has to be worth making. Hedging language inside a finding ("no action this PR", "not actionable here", "just capturing a thought", "call it out only if X", "would matter once Y") is your own signal that it does not belong; drop it, don't soften it. A finding that endorses the current state and then proposes a change anyway is incoherent; drop it. Self-test: _Would I make this change right now if it were my code?_ If no, it is not a finding. Apply this hardest to R and S. Full treatment, including where dropped content goes: [finding scheme § Actionability gate](../_data/artifact-conventions.md#actionability-gate).
56
+
57
+ ## Insight gate
58
+
59
+ Reviewers may emit insights (`I{n}`), knowledge worth preserving that is not a finding. An insight must clear a gate as strict as the Actionability gate: Emit it only when it is non-obvious knowledge without which a future reader is materially worse off, and name that benefit. Distinguish it from a Suggestion (`S`): An `S` proposes a change to make now; an `I` records knowledge without an attached action. When an action is implied, it is an `S`, not an insight. Number insights sequentially (`I1`, `I2`, …) in their own sequence, without a severity or an `-L` marker. Full treatment: [knowledge items § Insight gate](../_data/artifact-conventions.md#insight-gate).
60
+
61
+ ## Finding concision
62
+
63
+ Compose each finding at the tight altitude ([concision principle](../_data/concision.md)): State the defect, its location, and the decision that the author must make, then stop. Cut code already visible to the author, hedged narration, and rationale for why you looked. Every reader spends attention on each line, so weigh each sentence against the decision that it enables, not its completeness.
64
+
65
+ ## Comment findings
66
+
67
+ Comment text that you propose for a source file (a replacement doc comment, a suggested inline comment) is a source comment, and the full [comment discipline](#comment-discipline) audit applies to it. Prefer a short `todo:` naming what is stale over a rewritten comment, and never copy an example value out of the source.
68
+
69
+ "Add a comment explaining X" is a finding only when X is a constraint that the code cannot show. Do not request a comment that the discipline would delete.
70
+
71
+ ## Do not recommend a test that is not worth keeping
72
+
73
+ Every test that you recommend clears the bar in the `testing-conventions` skill, which states the filters and the authoring-side rule. A recommendation that fails a filter is withdrawn rather than reworded, and absence of a test is not by itself a finding.
74
+
75
+ The commonest instance is a test asserting that deleted code, text, or behavior is absent (a `not.toContain` guard, a `.toBe(false)` on a removed variant). The assertion is noise, not a guard: It encodes history and fails only on a verbatim revert, and such assertions accumulate without limit. The deletion is the fix; the positive assertion describing the replacement behavior is the behavioral guard. This extends the [comment discipline](#comment-discipline) ban on change-history artifacts from comments to test assertions.
76
+
77
+ ## Grown test files
78
+
79
+ A test file that the change adds to and leaves past the ceiling in the `testing-conventions` skill is a Warning, and its proposed change is a split by aspect as that skill describes. When the file starts expensive setup of its own, such as a database engine, the proposed change shares that setup before the split, so that the split does not add to it. The diff does not show a file's length, so measure each test file that the change adds to. If the project's lint applies `max-lines` to test files, the lint is the guard, and this is not a finding. A file past the ceiling that the change does not add to is Legacy.
80
+
81
+ ## Test placement
82
+
83
+ Two defects against the placement rules in the `testing-conventions` skill are Warnings:
84
+
85
+ - **A misplaced expensive example.** The change adds an example at an expensive tier, and a cheaper tier could observe it. The proposed change moves the case to the cheaper tier. If the change's plan or pull-request description explains why a cheaper tier cannot observe the case, it is not a finding.
86
+ - **A kept superseded suite.** The change adds cheaper coverage but keeps the higher-tier examples that the new coverage supersedes. The proposed change deletes those examples. To find them, read each process-spawning or full-fixture example that exercises the logic which the change's new tests cover, and compare its assertions with the new tests.
87
+
88
+ The same defects in tests that the change neither adds nor supersedes are Legacy.
89
+
90
+ ## Database tests and setup cost
91
+
92
+ Three defects against the database and setup rules in the `testing-conventions` skill are Warnings:
93
+
94
+ - **A database for a test whose subject is not SQL.** The proposed change tests the logic against a fake client or a mock at the boundary of the module containing the SQL.
95
+ - **A test per constraint.** The proposed change deletes it; the test that the migrations apply covers the schema.
96
+ - **A split that adds per-file setup.** The change adds or splits a test file, and each file starts its own expensive setup. The proposed change shares that setup across the files.
97
+
98
+ The same defects in tests that the change does not add, split, or modify are Legacy.
99
+
100
+ ## Test data and timeouts
101
+
102
+ Two defects against the test-data and timeout rules in the `testing-conventions` skill are Warnings:
103
+
104
+ - **A raised timeout.** The change raises a hook's, a test's, or a tier's timeout, in a test or in config. The proposed change reduces the work by the fixes that the skill names. A reason stated in the plan or the pull-request description does not exempt the raise: Check the reason against those fixes, and report the finding when one of them still applies.
105
+ - **A test that renders or builds production-scale data.** The proposed change passes the smallest data that proves the behavior, and makes the data injectable when the code under test reads it from a module-level singleton, even when the singleton is in code that the change does not touch. The diff does not show the data's size, so read what the code under test imports.
106
+
107
+ The same defects in tests and config that the change does not add or modify are Legacy.
108
+
109
+ ## Noisy tests
110
+
111
+ A test that the change adds and that writes output on a passing run is a Suggestion, and its proposed change is the interception that the `testing-conventions` skill describes. The diff does not show runtime output: Read the test run's output when one is available, and otherwise read for logging calls on the paths that the test exercises. A noisy test that the change does not add is Legacy.
112
+
113
+ ## Always-loaded context
114
+
115
+ A change that adds to what every session loads is a Warning unless nearly every session needs the content, and a ticket that asks for the change does not exempt it. Such a change makes a rulebook ambient, adds an ambient rulebook to a collection or a `codeassembly.yaml` declaration, or grows an `AGENTS.md`, a `CLAUDE.md`, or another file loaded at session start. The proposed change is `skill` or `hook` delivery, or a move of the content into a skill. A skill's or subagent's description is not a finding: Every session needs it to discover what it describes.
116
+
117
+ ## Finding references
118
+
119
+ Conventions for how findings reference files and code locations.
120
+
121
+ 1. **Repo-relative path required when localizable.** When a finding refers to specific code, the `- **Location:** ` line must be the first bullet under the finding heading, with a repo-relative path. Example: `packages/devtools-panel/config/renderReleaseNotesHtml.ts:69-76`, not `renderReleaseNotesHtml.ts:69-76`.
122
+ 2. **Multi-range syntax.** Multiple ranges or single lines in the same file concatenate with comma separation, dropping the path on subsequent entries: `path/to/file.ts:42, :69-76, :152-155`.
123
+ 3. **Multiple files.** Findings that span multiple files use one `- **Location:** ` bullet per file.
124
+ 4. **Prose may abbreviate after the canonical reference.** Once `Location:` establishes the path, the Description and Recommendation may refer to the file by basename.
125
+
126
+ ## PR comment format
127
+
128
+ When posting findings as PR comments (e.g., inline comments on a pull request), use a descriptive label instead of the raw finding ID. Finding IDs like `F1` or `W2` are internal to review documents and do not mean anything to readers in PR context.
129
+
130
+ | Finding prefix | PR comment label |
131
+ | -------------- | --------------------------------------------------------------- |
132
+ | `F` | `fixme:` |
133
+ | `W` | `warning:` |
134
+ | `T` | `todo:` |
135
+ | `S` | `suggestion:` |
136
+ | `R` | `recommendation:` |
137
+ | `-L` suffix | `legacy {severity}:` (e.g., `legacy fixme:`, `legacy warning:`) |
138
+
139
+ <!-- include: ../../_partials/comment-discipline.md / -->
140
+
141
+ <!-- guidance-hook: implementation-preferences -->
@@ -0,0 +1,155 @@
1
+ ---
2
+ name: review-gh-pr
3
+ description: Fetch GitHub PR metadata, verify HEAD, and resolve specification sources for review-pr
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Review GitHub pull request
8
+
9
+ Internal delegate that handles the GitHub-specific work for `review-pr`: Fetch PR metadata in a single `gh pr view` call, verify the local HEAD matches the PR's head commit, resolve the ticket from PR linked issues (with body-parse fallback), and prepare the spec-source list. Returns a resolved-input record that `review-pr` passes to `review-branch`'s shared review process.
10
+
11
+ This skill does not run a review. The review logic is implemented in `review-branch`.
12
+
13
+ ## Delegate interface
14
+
15
+ | Input | Type | Description |
16
+ | -------------------- | -------------- | ------------------------------------------------------------------------------------ |
17
+ | `pr_id` | string | PR number (e.g., `"1024"`) or full URL (`"https://github.com/owner/repo/pull/1024"`) |
18
+ | `diff_base_override` | string \| null | `--diff-base` value from `review-pr` if provided |
19
+ | `ticket_override` | string \| null | `--ticket` value from `review-pr` if provided |
20
+ | `project_slug` | string | From session context |
21
+ | `ticket_id` | string \| null | From session context |
22
+ | `artifact_base_dir` | string | From session context |
23
+
24
+ ## Resolved-output contract
25
+
26
+ On success, return a record with the following fields. `review-pr` passes this directly to `review-branch`:
27
+
28
+ | Field | Type | Description |
29
+ | ---------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
30
+ | `merge_base_sha` | string | Result of `git merge-base HEAD <diff_base>` |
31
+ | `diff_base` | string | Resolved ref (override if provided, else `baseRefName`) |
32
+ | `spec_sources` | array of `{ source_type, label, content, criteria?, provenance, last_updated }` | One entry per available specification source (PR description always present; ticket if resolved). Every source is `provenance: "remote"` (this path fetches live and never reads a local snapshot), so the review never renders a divergence note for it |
33
+ | `pr_metadata` | object | `{ number, url, head_oid, base_ref, title }` |
34
+
35
+ On HEAD mismatch, do not return; exit non-zero with the mismatch error. `review-pr` reports the message and stops.
36
+
37
+ ## Process
38
+
39
+ ### 1. Normalize `pr_id`
40
+
41
+ If `pr_id` is a URL of the form `https://github.com/{owner}/{repo}/pull/{number}`, extract `{number}`. Otherwise treat `pr_id` as the number directly.
42
+
43
+ ### 2. Fetch PR metadata
44
+
45
+ Issue a single `gh pr view` call with all fields needed downstream, and save its output for step 5:
46
+
47
+ ```bash
48
+ pr_json=$(mktemp "${TMPDIR:-/tmp}/review-gh-pr.XXXXXX")
49
+ gh pr view {pr_number} --json number,title,body,url,updatedAt,headRefName,headRefOid,baseRefName,closingIssuesReferences > "$pr_json"
50
+ echo "$pr_json"
51
+ ```
52
+
53
+ Write the printed absolute path wherever `{pr_json}` appears below. Parse the JSON with a real parser (`python3 -c "import sys,json; ..."` or `jq`). Capture:
54
+
55
+ - `number`, `title`, `body`, `url`, `updatedAt`
56
+ - `headRefName`, `headRefOid`, `baseRefName`
57
+ - `closingIssuesReferences` (array of `{ number, title, url }` or empty)
58
+
59
+ If `gh pr view` exits non-zero, report its stderr and stop.
60
+
61
+ ### 3. Verify HEAD
62
+
63
+ Compare the local HEAD against the PR's head commit:
64
+
65
+ ```bash
66
+ git rev-parse HEAD
67
+ ```
68
+
69
+ If the printed HEAD does not equal `headRefOid`, exit non-zero with:
70
+
71
+ ```
72
+ PR #{number}'s head commit is {short(headRefOid)} but HEAD is at {short(HEAD)}. Run "gh pr checkout {number}" first.
73
+ ```
74
+
75
+ Use the first 7 characters of each SHA for the short form. **Fail closed**: Never proceed with mismatched state. Compilation, dependency installation, and test execution all require the working tree to match the commit being reviewed.
76
+
77
+ ### 4. Resolve the diff base
78
+
79
+ Apply this cascade:
80
+
81
+ 1. If `diff_base_override` is non-null, use it.
82
+ 2. Otherwise, use `baseRefName` from PR metadata.
83
+
84
+ Compute the merge-base once:
85
+
86
+ ```bash
87
+ git merge-base HEAD {diff_base}
88
+ ```
89
+
90
+ ### 5. Resolve the ticket
91
+
92
+ Apply this cascade in order and use the first match:
93
+
94
+ 1. **`ticket_override`**: If non-null, resolve per [ticket source resolution](../_data/ticket-source-resolution.md) and use it.
95
+ 2. **Linked or referenced issue**: Run the bundled helper on the saved PR JSON:
96
+
97
+ ```bash
98
+ node {harness_home_dir}/skills/review-gh-pr/select-pr-ticket.mjs < {pr_json}
99
+ ```
100
+
101
+ It prints `{"number": <n or null>, "source": "<source>"}`. `source` is `closing-reference` (the first entry in `closingIssuesReferences`), `body-keyword` or `body-bare` (the earliest issue reference in the body outside code), or `none`, with `number` null. When `number` is not null, fetch the issue via `gh issue view --json number,title,body,labels,updatedAt {number}` and use it. When the helper exits non-zero, report its stderr and stop.
102
+
103
+ 3. **No ticket**: When `source` is `none`, proceed with the PR description as the only spec source.
104
+
105
+ ### 6. Build the spec-source list
106
+
107
+ Always include the PR description as a source:
108
+
109
+ ```
110
+ {
111
+ source_type: "pr_description",
112
+ label: "pr_description: PR #{number}",
113
+ content: <body>,
114
+ criteria: <optional: extracted bullets from `## What`, `## Summary`, or an explicit acceptance-criteria heading; null when the description does not contain a list>,
115
+ provenance: "remote",
116
+ last_updated: <PR `updatedAt`>
117
+ }
118
+ ```
119
+
120
+ If a ticket was resolved in step 5, prepend it:
121
+
122
+ ```
123
+ {
124
+ source_type: "ticket",
125
+ label: "ticket: {ticket_ref or short identifier}",
126
+ content: <ticket body>,
127
+ criteria: <optional: extracted from the ticket structure>,
128
+ provenance: "remote",
129
+ last_updated: <issue `updatedAt`>
130
+ }
131
+ ```
132
+
133
+ The list order is `[ticket?, pr_description]`: When both are present, the ticket is listed first because the ticket is the higher-authority source (PR description is a presentation of what the implementation delivers; the ticket states what was asked).
134
+
135
+ ### 7. Return the resolved-output record
136
+
137
+ Return:
138
+
139
+ ```
140
+ {
141
+ merge_base_sha: <from step 4>,
142
+ diff_base: <from step 4>,
143
+ spec_sources: <from step 6>,
144
+ pr_metadata: { number, url, head_oid: headRefOid, base_ref: baseRefName, title }
145
+ }
146
+ ```
147
+
148
+ `review-pr` passes this to `review-branch` and the review proceeds.
149
+
150
+ ## Important
151
+
152
+ - **Single `gh pr view` call.** All fields are fetched at once. Do not split into multiple calls: Repeated `gh` invocations are slow and add failure modes.
153
+ - **HEAD mismatch is a hard stop.** The error message must include the literal `gh pr checkout {number}` suggestion so that the user has a one-line copy-pasteable fix.
154
+ - **Ticket-resolution cascade order is fixed.** `ticket_override` → `closingIssuesReferences[0]` → body parse → none. Document this order in any future change so that future readers do not silently rearrange it.
155
+ - **No review logic here.** This delegate prepares inputs only. The review process (diff analysis, finding generation, "Specification compliance" rendering) runs inside `review-branch` after `review-pr` invokes it with the resolved inputs.
@@ -0,0 +1,8 @@
1
+ import { createRequire as __cjsCreateRequire } from 'node:module';
2
+ const require = __cjsCreateRequire(import.meta.url);
3
+ var y=Object.defineProperty;var n=(r,e)=>y(r,"name",{value:e,configurable:!0});import u from"node:process";function f(r){return r instanceof Error||Object.prototype.toString.call(r)==="[object Error]"}n(f,"isError");function s(r){try{return f(r)&&typeof r.message=="string"&&r.message!==""?r.message:String(r)}catch{return"[unstringifiable value]"}}n(s,"describeError");import{realpathSync as a}from"node:fs";import m from"node:process";import{fileURLToPath as k}from"node:url";function l(r,e){let t=m.argv[1];if(t===void 0)return!1;try{return a(k(r))===a(t)}catch(o){return m.stderr.write(`${e}: warning: could not determine entry point: ${s(o)}
4
+ `),!0}}n(l,"isEntryPoint");async function d(r){let e=[];for await(let t of r){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");e.push(t)}return Buffer.concat(e).toString("utf8")}n(d,"readAll");function c(r){return w(r)&&!Array.isArray(r)}n(c,"isRecord");function w(r){return typeof r=="object"&&r!==null}n(w,"isObject");var h=/\b(?:closes|fixes|resolves):?\s+#(\d+)\b|(?<![\w/#&])#(\d+)\b/iu;function b(r){if(!c(r))throw new Error("input must be a JSON object");let{body:e,closingIssuesReferences:t}=r;if(e!=null&&typeof e!="string")throw new Error("body must be a string");if(t!==void 0&&!Array.isArray(t))throw new Error("closingIssuesReferences must be an array");let o=(t??[]).map(i=>{if(!c(i)||typeof i.number!="number"||!Number.isSafeInteger(i.number))throw new Error("each closingIssuesReferences entry must have an integer number");return i.number});return{body:e??"",closingIssueNumbers:o}}n(b,"parsePrTicketInput");function p(r){let[e]=r.closingIssueNumbers;if(e!==void 0)return{number:e,source:"closing-reference"};let t=h.exec(E(r.body));if(t===null)return{number:null,source:"none"};let[,o,i=""]=t;return o!==void 0?{number:Number(o),source:"body-keyword"}:{number:Number(i),source:"body-bare"}}n(p,"selectPrTicket");function g(r){return r.replaceAll(/[^\n]/gu," ")}n(g,"blank");function E(r){return N(x(r))}n(E,"maskCode");function x(r){let e;return r.split(`
5
+ `).map(t=>{let o=/^ {0,3}(`{3,}|~{3,})/u.exec(t)?.[1];if(e===void 0){if(o===void 0)return t;e={char:o.charAt(0),length:o.length}}else o!==void 0&&o.charAt(0)===e.char&&o.length>=e.length&&t.trim()===o&&(e=void 0);return g(t)}).join(`
6
+ `)}n(x,"maskFencedBlocks");function N(r){return r.replaceAll(/(?<!`)(`+)(?!`)(?:(?!\n[ \t]*\n)[\s\S])*?(?<!`)\1(?!`)/gu,e=>g(e))}n(N,"maskInlineCode");async function I(){try{let r=u.argv.slice(2);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let e=b(JSON.parse(await d(u.stdin)));u.stdout.write(`${JSON.stringify(p(e))}
7
+ `)}catch(r){u.stderr.write(`select-pr-ticket: ${s(r)}
8
+ `),u.exit(1)}}n(I,"main");l(import.meta.url,"select-pr-ticket")&&await I();