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.
- package/.meta/changelog.json +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +70 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +6 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +214 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +180 -0
- package/content/skills/_data/title-templates.md +632 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +85 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +148 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +71 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +317 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- 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();
|