codeassembly-guidance 0.0.0 → 0.1.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 +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- 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 +66 -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 +5 -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 +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -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 +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -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 +18 -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 +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -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 +43 -0
- package/content/scripts/README.md +41 -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 +209 -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/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -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/recommendation-gradient.md +90 -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 +147 -0
- package/content/skills/_data/title-templates.md +624 -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/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 +84 -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/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 +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -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 +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -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 +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -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 +136 -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 +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -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 +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -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 +115 -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 +69 -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 +308 -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 +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -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 +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -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 +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,161 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: review-bb-pr
|
|
3
|
+
description: Fetch Bitbucket PR metadata, verify HEAD, and resolve specification sources for review-pr
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Review Bitbucket pull request
|
|
8
|
+
|
|
9
|
+
Internal delegate that handles the Bitbucket-specific work for `review-pr`: Fetch PR metadata, verify the local HEAD matches the PR's head commit, resolve the ticket (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., `"42"`) or full Bitbucket PR URL |
|
|
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 same shape as `review-gh-pr`'s output. `review-pr` consumes both delegates' outputs interchangeably:
|
|
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 PR's destination branch) |
|
|
32
|
+
| `spec_sources` | array of `{ source_type, label, content, criteria?, provenance, last_updated }` | One entry per available specification source. 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; `last_updated` is null when the platform does not expose it (e.g. Jira) |
|
|
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
|
+
## Bitbucket access
|
|
38
|
+
|
|
39
|
+
Every Bitbucket call below goes through the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). That document owns the tool, the coordinates, the field vocabulary, and the not-connected stop; this skill states only what it does with them.
|
|
40
|
+
|
|
41
|
+
## Process
|
|
42
|
+
|
|
43
|
+
### 1. Normalize `pr_id` and resolve coordinates
|
|
44
|
+
|
|
45
|
+
If `pr_id` is a URL of the form `https://bitbucket.org/{workspace}/{repo}/pull-requests/{number}`, take `{number}` as the PR number.
|
|
46
|
+
|
|
47
|
+
Otherwise treat `pr_id` as the number directly.
|
|
48
|
+
|
|
49
|
+
Resolve `workspaceId` and `repoId` per [Coordinates](../_data/bitbucket-pr-access.md#coordinates), which takes them from the `pr_id` URL when it is one.
|
|
50
|
+
|
|
51
|
+
### 2. Fetch PR metadata
|
|
52
|
+
|
|
53
|
+
Issue a single `action: "get"` call with `prId` set to the PR number, per [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request). Capture `id`, `title`, `description`, `links.html.href`, `updated_on`, `source.branch.name`, `source.commit.hash`, and `destination.branch.name`.
|
|
54
|
+
|
|
55
|
+
If the call fails, report the tool's error and stop.
|
|
56
|
+
|
|
57
|
+
### 3. Verify HEAD
|
|
58
|
+
|
|
59
|
+
Compare the local HEAD against the PR's head commit:
|
|
60
|
+
|
|
61
|
+
```bash
|
|
62
|
+
git rev-parse HEAD
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
The comparison is a prefix test, not an equality test, because the tool may return `source.commit.hash` abbreviated; see [Reading a pull request](../_data/bitbucket-pr-access.md#reading-a-pull-request) for the rule. If `source.commit.hash` is not a prefix of the printed HEAD of at least 7 characters, exit non-zero with:
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
PR #{number}'s head commit is {short(source_commit_hash)} but HEAD is at {short(HEAD)}. Check out the PR branch first (e.g., "git fetch origin pull-requests/{number}/from:pr-{number} && git checkout pr-{number}") or pull the latest commits on {source_branch_name}.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Use the first 7 characters for short SHAs. **Fail closed**: Never proceed with mismatched state.
|
|
72
|
+
|
|
73
|
+
### 4. Resolve the diff base
|
|
74
|
+
|
|
75
|
+
Apply this cascade:
|
|
76
|
+
|
|
77
|
+
1. If `diff_base_override` is non-null, use it.
|
|
78
|
+
2. Otherwise, use `destination.branch.name` from PR metadata.
|
|
79
|
+
|
|
80
|
+
Compute the merge-base once:
|
|
81
|
+
|
|
82
|
+
```bash
|
|
83
|
+
git merge-base HEAD {diff_base}
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
### 5. Resolve the ticket
|
|
87
|
+
|
|
88
|
+
**Bitbucket linked-issues divergence from GitHub.** Bitbucket Cloud's PR API does not expose a structured `closingIssuesReferences` field equivalent to GitHub's. (Bitbucket has a separate Issues product with linked-issue support, but its surface differs and is not always enabled per workspace.) Rather than introducing a partial linked-issues mechanism here, this delegate uses a simpler cascade:
|
|
89
|
+
|
|
90
|
+
1. **`ticket_override`**: If non-null, resolve per [ticket source resolution](../_data/ticket-source-resolution.md) and use it.
|
|
91
|
+
2. **Parse PR body for issue references**: Scan `description` for the first match of any of these patterns (case-insensitive):
|
|
92
|
+
- `closes #{n}`, `closes: #{n}`
|
|
93
|
+
- `fixes #{n}`, `fixes: #{n}`
|
|
94
|
+
- `resolves #{n}`, `resolves: #{n}`
|
|
95
|
+
- bare `#{n}`
|
|
96
|
+
- Jira-style keys (e.g., `MAC-42`) when the project's `ticket_ref_prefix` is configured to a Jira prefix.
|
|
97
|
+
|
|
98
|
+
Fetch the matched issue per [ticket source resolution](../_data/ticket-source-resolution.md).
|
|
99
|
+
|
|
100
|
+
3. **No ticket**: Proceed with the PR description as the only spec source.
|
|
101
|
+
|
|
102
|
+
The divergence from `review-gh-pr` is intentional and documented here so that future readers do not assume parity. If Bitbucket linked-issue parity is added later (via the Jira integration or a future Bitbucket API field), a new step fits between override and body parse without breaking the delegate interface.
|
|
103
|
+
|
|
104
|
+
### 6. Build the spec-source list
|
|
105
|
+
|
|
106
|
+
Always include the PR description as a source:
|
|
107
|
+
|
|
108
|
+
```
|
|
109
|
+
{
|
|
110
|
+
source_type: "pr_description",
|
|
111
|
+
label: "pr_description: PR #{number}",
|
|
112
|
+
content: <description>,
|
|
113
|
+
criteria: <optional: extracted from `## What`, `## Summary`, or an explicit acceptance-criteria heading>,
|
|
114
|
+
provenance: "remote",
|
|
115
|
+
last_updated: <PR `updated_on`>
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
If a ticket was resolved in step 5, prepend it:
|
|
120
|
+
|
|
121
|
+
```
|
|
122
|
+
{
|
|
123
|
+
source_type: "ticket",
|
|
124
|
+
label: "ticket: {ticket_ref or short identifier}",
|
|
125
|
+
content: <ticket body>,
|
|
126
|
+
criteria: <optional: extracted from the ticket structure>,
|
|
127
|
+
provenance: "remote",
|
|
128
|
+
last_updated: <ticket last-updated when the platform exposes it (GitHub `updatedAt`); null when it does not (e.g. Jira)>
|
|
129
|
+
}
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The list order is `[ticket?, pr_description]`, same as `review-gh-pr`.
|
|
133
|
+
|
|
134
|
+
### 7. Return the resolved-output record
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
{
|
|
138
|
+
merge_base_sha: <from step 4>,
|
|
139
|
+
diff_base: <from step 4>,
|
|
140
|
+
spec_sources: <from step 6>,
|
|
141
|
+
pr_metadata: {
|
|
142
|
+
number: <id>,
|
|
143
|
+
url: <links.html.href>,
|
|
144
|
+
head_oid: <the HEAD printed in step 3>,
|
|
145
|
+
base_ref: <destination.branch.name>,
|
|
146
|
+
title: <title>
|
|
147
|
+
}
|
|
148
|
+
}
|
|
149
|
+
```
|
|
150
|
+
|
|
151
|
+
`head_oid` contains the local HEAD rather than `source.commit.hash`, which step 3 may have matched abbreviated. The two name the same commit once step 3 passes, and the local one is the full 40 characters expected by a consumer of an OID.
|
|
152
|
+
|
|
153
|
+
`review-pr` passes this to `review-branch` and the review proceeds.
|
|
154
|
+
|
|
155
|
+
## Important
|
|
156
|
+
|
|
157
|
+
- **Single read for metadata.** All fields are fetched at once. Do not split into multiple calls.
|
|
158
|
+
- **The REST pin is no longer needed.** This delegate used to pin the REST API because a generic "whatever tooling is available" instruction could not guarantee that a client returned `source.commit.hash`, which the _Verify HEAD_ step fails closed on. Naming one tool removes that reason, and the field is verified present in its response. Do not restore the credential cascade or the REST endpoint because of the old comment.
|
|
159
|
+
- **HEAD mismatch is a hard stop.** The error message must include a Bitbucket-equivalent checkout suggestion so that the user has a one-line fix path even though Bitbucket lacks `gh pr checkout`'s exact equivalent.
|
|
160
|
+
- **Linked-issues divergence is intentional.** The Bitbucket cascade lacks the GitHub `closingIssuesReferences` step. This is documented above so that the parity gap is visible to future readers; do not silently re-add a partial implementation.
|
|
161
|
+
- **No review logic here.** This delegate prepares inputs only. The review process runs inside `review-branch` after `review-pr` invokes it with the resolved inputs.
|
|
@@ -0,0 +1,301 @@
|
|
|
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
|
+
## Conclusion
|
|
173
|
+
|
|
174
|
+
Score: X/10
|
|
175
|
+
|
|
176
|
+
## Specification compliance
|
|
177
|
+
|
|
178
|
+
{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.}
|
|
179
|
+
|
|
180
|
+
### {source.label}
|
|
181
|
+
|
|
182
|
+
{The label is `{source_type}: {short identifier}`, for example, `ticket: #553` or `pr_description: PR #1024`. Use the source's natural identifier so a reader can tell at a glance which specification a row evaluates against.}
|
|
183
|
+
|
|
184
|
+
**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.}
|
|
185
|
+
|
|
186
|
+
{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.}
|
|
187
|
+
|
|
188
|
+
#### Acceptance criteria
|
|
189
|
+
|
|
190
|
+
| # | Criterion | Status | Notes |
|
|
191
|
+
| --- | ---------------- | -------- | ------- |
|
|
192
|
+
| 1 | {criterion text} | {status} | {notes} |
|
|
193
|
+
|
|
194
|
+
Status values: ✅ Met, ⚠️ Partial, ❌ Not addressed
|
|
195
|
+
|
|
196
|
+
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.
|
|
197
|
+
|
|
198
|
+
⚠️ 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:
|
|
199
|
+
|
|
200
|
+
- **Unbuilt**: The work is incomplete. At review time this is ordinary, and the contract is not in question.
|
|
201
|
+
- **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).
|
|
202
|
+
|
|
203
|
+
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.
|
|
204
|
+
|
|
205
|
+
#### Unplanned work
|
|
206
|
+
|
|
207
|
+
{Bullet list of changes not traceable to any criterion in this source. If none, state "None."}
|
|
208
|
+
|
|
209
|
+
#### Assessment
|
|
210
|
+
|
|
211
|
+
{1-2 sentence summary of alignment between the implementation and this source.}
|
|
212
|
+
|
|
213
|
+
## Specification consistency
|
|
214
|
+
|
|
215
|
+
{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.}
|
|
216
|
+
|
|
217
|
+
🔗 **Consistency:** {emoji} `{verdict}`
|
|
218
|
+
|
|
219
|
+
| # | Aspect | Ticket | PR description | Implementation | Summary |
|
|
220
|
+
| --- | -------------- | ------- | -------------- | -------------------------- | ----------------------------------------- |
|
|
221
|
+
| D1 | {aspect label} | {state} | {state} | {ticket-state}, {PR-state} | {one-line synthesis with concrete values} |
|
|
222
|
+
|
|
223
|
+
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).
|
|
224
|
+
|
|
225
|
+
Cell encoding:
|
|
226
|
+
|
|
227
|
+
| Symbol | Meaning |
|
|
228
|
+
| ----------- | ------------------------------------------------ |
|
|
229
|
+
| ⚫ baseline | This source defines the aspect on this row |
|
|
230
|
+
| ⚪ omitted | This source does not make a claim to compare |
|
|
231
|
+
| 🟢 {ref} | Matches the named reference (semantic alignment) |
|
|
232
|
+
| 🟠 {ref} | Partial mismatch with the named reference |
|
|
233
|
+
| 🔴 {ref} | Severe mismatch with the named reference |
|
|
234
|
+
|
|
235
|
+
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.
|
|
236
|
+
|
|
237
|
+
Implementation-column ordering: always `{ticket-state}, {PR-state}` regardless of which is meaningful, so that every row reads in the same order.
|
|
238
|
+
|
|
239
|
+
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.
|
|
240
|
+
|
|
241
|
+
### Details
|
|
242
|
+
|
|
243
|
+
**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.}
|
|
244
|
+
|
|
245
|
+
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.
|
|
246
|
+
```
|
|
247
|
+
|
|
248
|
+
### Clean reviews
|
|
249
|
+
|
|
250
|
+
When a change does not warrant any findings, render it on this shape rather than as empty `### FIXMEs` / "None." scaffolding:
|
|
251
|
+
|
|
252
|
+
```markdown
|
|
253
|
+
## Action required
|
|
254
|
+
|
|
255
|
+
None.
|
|
256
|
+
|
|
257
|
+
## Areas for improvement
|
|
258
|
+
|
|
259
|
+
None.
|
|
260
|
+
|
|
261
|
+
## Technical assessment
|
|
262
|
+
|
|
263
|
+
{Why the change is correct and adequately tested.}
|
|
264
|
+
|
|
265
|
+
## Conclusion
|
|
266
|
+
|
|
267
|
+
A focused, well-tested change without outstanding issues. Merge-ready.
|
|
268
|
+
|
|
269
|
+
Score: 10/10
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
## Scoring
|
|
273
|
+
|
|
274
|
+
The score is an honest, at-a-glance quality signal.
|
|
275
|
+
|
|
276
|
+
- A no-findings review is 10/10.
|
|
277
|
+
- 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.
|
|
278
|
+
- Score only the change under review; Legacy and other pre-existing observations never affect the score.
|
|
279
|
+
- Never suppress a real finding to protect a perfect score. An honest 8 is better than a flattering 10.
|
|
280
|
+
|
|
281
|
+
## Saving
|
|
282
|
+
|
|
283
|
+
### Path resolution
|
|
284
|
+
|
|
285
|
+
Use `artifact_base_dir`, `project_slug`, and `ticket_id` from step 1.
|
|
286
|
+
|
|
287
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
288
|
+
|
|
289
|
+
### Run artifact
|
|
290
|
+
|
|
291
|
+
The review is saved as a run artifact: `{timestamp}_reviewer_review.md`
|
|
292
|
+
|
|
293
|
+
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.
|
|
294
|
+
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.
|
|
295
|
+
3. Save: `{runDir}/{timestamp}_reviewer_review.md`
|
|
296
|
+
|
|
297
|
+
Each review is a separate artifact in the run directory. Do not append to existing files: The chronological sequence of files is the history.
|
|
298
|
+
|
|
299
|
+
<!-- include: ../_partials/next-steps-after-review.md / -->
|
|
300
|
+
|
|
301
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -0,0 +1,108 @@
|
|
|
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
|
+
- **Conventions**: Adherence to codebase patterns and project standards
|
|
20
|
+
- **Edge cases**: Boundary conditions, empty collections, zero values, undefined states
|
|
21
|
+
- **Test coverage**: Adequate tests for new functionality; tests that verify behavior and earn their place, not just coverage
|
|
22
|
+
- **Clarity**: Naming, documentation, and instructions convey unambiguous intent
|
|
23
|
+
- **Contracts**: Documented behaviors match implementations; implicit assumptions are explicit
|
|
24
|
+
- **Type safety**: Type issues that affect correctness or maintainability
|
|
25
|
+
- **Modern patterns**: Current best practices over outdated approaches
|
|
26
|
+
|
|
27
|
+
## Skip
|
|
28
|
+
|
|
29
|
+
- 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.
|
|
30
|
+
- 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.
|
|
31
|
+
- Pre-existing issues in unchanged code (categorize as Legacy if noted)
|
|
32
|
+
|
|
33
|
+
## Logic verification
|
|
34
|
+
|
|
35
|
+
- Trace 2–3 concrete examples with realistic inputs through changed code
|
|
36
|
+
- Test edge cases: zero values, single vs. multiple items, undefined states
|
|
37
|
+
- Watch for variable confusion, context mismatches, assumption violations
|
|
38
|
+
- Verify tests reveal logical errors, not just achieve coverage
|
|
39
|
+
|
|
40
|
+
## Distinguish author work from legacy
|
|
41
|
+
|
|
42
|
+
Focus findings (F/W/T) only on code authored in the current change; observations in pre-existing code belong in Legacy (suffix `-L`).
|
|
43
|
+
|
|
44
|
+
## Finding scheme
|
|
45
|
+
|
|
46
|
+
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.
|
|
47
|
+
|
|
48
|
+
## Proposed-change gate
|
|
49
|
+
|
|
50
|
+
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).
|
|
51
|
+
|
|
52
|
+
## Actionability gate
|
|
53
|
+
|
|
54
|
+
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).
|
|
55
|
+
|
|
56
|
+
## Insight gate
|
|
57
|
+
|
|
58
|
+
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).
|
|
59
|
+
|
|
60
|
+
## Finding concision
|
|
61
|
+
|
|
62
|
+
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.
|
|
63
|
+
|
|
64
|
+
## Comment findings
|
|
65
|
+
|
|
66
|
+
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.
|
|
67
|
+
|
|
68
|
+
"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.
|
|
69
|
+
|
|
70
|
+
## Do not recommend a test that does not earn its place
|
|
71
|
+
|
|
72
|
+
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.
|
|
73
|
+
|
|
74
|
+
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.
|
|
75
|
+
|
|
76
|
+
## Grown test files
|
|
77
|
+
|
|
78
|
+
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. The diff does not show a file's length, so measure each test file that the change adds to. Where 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.
|
|
79
|
+
|
|
80
|
+
## Noisy tests
|
|
81
|
+
|
|
82
|
+
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.
|
|
83
|
+
|
|
84
|
+
## Finding references
|
|
85
|
+
|
|
86
|
+
Conventions for how findings reference files and code locations.
|
|
87
|
+
|
|
88
|
+
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`.
|
|
89
|
+
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`.
|
|
90
|
+
3. **Multiple files.** Findings that span multiple files use one `- **Location:** ` bullet per file.
|
|
91
|
+
4. **Prose may abbreviate after the canonical reference.** Once `Location:` establishes the path, the Description and Recommendation may refer to the file by basename.
|
|
92
|
+
|
|
93
|
+
## PR comment format
|
|
94
|
+
|
|
95
|
+
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.
|
|
96
|
+
|
|
97
|
+
| Finding prefix | PR comment label |
|
|
98
|
+
| -------------- | --------------------------------------------------------------- |
|
|
99
|
+
| `F` | `fixme:` |
|
|
100
|
+
| `W` | `warning:` |
|
|
101
|
+
| `T` | `todo:` |
|
|
102
|
+
| `S` | `suggestion:` |
|
|
103
|
+
| `R` | `recommendation:` |
|
|
104
|
+
| `-L` suffix | `legacy {severity}:` (e.g., `legacy fixme:`, `legacy warning:`) |
|
|
105
|
+
|
|
106
|
+
<!-- include: ../../_partials/comment-discipline.md / -->
|
|
107
|
+
|
|
108
|
+
<!-- guidance-hook: implementation-preferences -->
|