codeassembly-guidance 0.1.0 → 0.3.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 +984 -0
- package/CHANGELOG.md +240 -0
- package/README.md +45 -99
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +21 -5
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +17 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +206 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
- package/content/guidance/rulebooks/commit-conventions.md +5 -4
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +39 -4
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +98 -98
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +64 -16
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +15 -4
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +22 -12
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +11 -11
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +7 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +98 -0
- package/content/skills/capture-event/SKILL.md +4 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +3 -3
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +28 -10
- package/content/skills/create-pr/SKILL.md +7 -6
- package/content/skills/create-ticket/SKILL.md +64 -23
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
- package/content/skills/design-and-plan/SKILL.md +17 -18
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +27 -23
- package/content/skills/index-prototypes/SKILL.md +86 -31
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +4 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +5 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
- package/content/skills/kb-retrieve-events/SKILL.md +20 -11
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
- package/content/skills/kb-update-events/SKILL.md +10 -7
- package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +2 -2
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +354 -3
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +3 -1
- package/content/skills/streamline-guidance/SKILL.md +11 -16
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +23 -14
- package/content/skills/testing-conventions/SKILL.md +81 -8
- package/content/skills/triage-feedback/SKILL.md +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +12 -12
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/feedback-triage-challenger.md +81 -0
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/lesson-clusterer.md +68 -0
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +21 -17
- package/schemas/preferences.v1.json +50 -7
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -169,6 +169,8 @@ The body following the frontmatter has this structure:
|
|
|
169
169
|
|
|
170
170
|
## Technical assessment
|
|
171
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
|
+
|
|
172
174
|
## Conclusion
|
|
173
175
|
|
|
174
176
|
Score: X/10
|
|
@@ -179,7 +181,7 @@ Score: X/10
|
|
|
179
181
|
|
|
180
182
|
### {source.label}
|
|
181
183
|
|
|
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.}
|
|
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.}
|
|
183
185
|
|
|
184
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.}
|
|
185
187
|
|
|
@@ -260,7 +262,7 @@ None.
|
|
|
260
262
|
|
|
261
263
|
## Technical assessment
|
|
262
264
|
|
|
263
|
-
{Why the change is correct and adequately tested.}
|
|
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.}
|
|
264
266
|
|
|
265
267
|
## Conclusion
|
|
266
268
|
|
|
@@ -296,6 +298,355 @@ The review is saved as a run artifact: `{timestamp}_reviewer_review.md`
|
|
|
296
298
|
|
|
297
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.
|
|
298
300
|
|
|
299
|
-
|
|
301
|
+
## Next-steps options
|
|
302
|
+
|
|
303
|
+
The next-steps block has four independent sub-blocks. Each is shown only when its condition is met. If every condition is unmet, the next-steps block does not appear. Whatever combination of sub-blocks is shown, always wrap the output in a `Next steps:` header. When two or more sub-blocks appear, label each with its `A` identifier as a bold prefix (`**A1: Deviations from ticket**`, and so on) and keep each sub-block's own 1-based numbering, so the user answers `A1: 1, A2: 2`; a lone sub-block does not take an identifier.
|
|
304
|
+
|
|
305
|
+
Use `~/`-relative paths when possible and absolute paths otherwise. Every line subordinate to an option (invocation guidance as much as a pro or con) is a nested list item, never a whitespace-indented continuation; see [option format](#option-format).
|
|
306
|
+
|
|
307
|
+
**Naming a skill in the render.** Name a skill in the rendered option only when the user must carry the invocation across a session boundary: clearing context, handing off to another session, or waiting for someone else to act. When the agent runs the skill in the current session, the skill name appears in the sub-block's Options table and the rendered line is a bare action. This limits each rendered line to the step that the user performs.
|
|
308
|
+
|
|
309
|
+
**Reviewer and author roles.** A review reports findings; the author disposes of them. The options below send the reviewer's output to the author or record what the review found; they never ask the reviewer to re-design, re-plan, or coordinate a workflow, none of which is the reviewer's job.
|
|
310
|
+
|
|
311
|
+
### Proposed-edit preview
|
|
312
|
+
|
|
313
|
+
Three of the sub-blocks below offer options that rewrite an artifact, one each: the Deviations sub-block rewrites the ticket's acceptance criteria, the source-divergence sub-block rewrites the PR description, and the Findings sub-block rewrites the source. The user consents to that rewrite by picking a number, so every such option renders a preview of the edit that it would make. The reviewer judges which criteria are genuinely in conflict with the implementation and which findings name a change that it can carry out; the preview makes those judgments reviewable instead of silent.
|
|
314
|
+
|
|
315
|
+
**Placement.** The preview renders above the numbered options, inside its sub-block, under a `Proposed edit to the {target}:` label naming what it would change; the source target's label is plural, `Proposed edits to the source:`, because it covers every open finding. Option lines stay bare actions: The preview is never a pro, a con, or a line nested beneath an option. An option that mutates nothing, such as "Leave as-is", does not render a preview.
|
|
316
|
+
|
|
317
|
+
Ticket and PR-description deltas render as a flat list, one line per change. Source entries render as blocks instead, each led by its bolded finding ID.
|
|
318
|
+
|
|
319
|
+
**Notation.** The preview is a delta. It never restates the ticket, the PR description, or a finding's Recommendation, which would duplicate the artifact in the terminal, and it contains one entry per change:
|
|
320
|
+
|
|
321
|
+
- **Ticket targets** derive their delta from the in-conflict criteria rows of `## Specification compliance`'s ticket subsection, and from nothing else. Unplanned work is never a source: Implementation that goes beyond the criteria is not a deviation, so it does not yield a line. Because a ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when it was written, this menu does not offer an edit that changes them; a divergence between one of them and the implementation is reported in the PR description instead.
|
|
322
|
+
- `Reword: {old} → {new}` for a criterion whose direction the implementation deliberately contradicts
|
|
323
|
+
- `Drop: {criterion}` for a criterion that the implementation deliberately abandoned, never for one that it has not yet reached
|
|
324
|
+
- **PR-description targets** render the concrete claim changes, each keyed to the divergent `D{n}` row from which it came: `D2: {claim as written} → {claim as built}`.
|
|
325
|
+
- **Source targets** derive their delta from the open findings, one entry per finding, keyed to its ID. An entry states two things: the surface that the change touches (source, test, comment, docs, config) and the substance of the edit. Its form follows the edit's own granularity rather than a fixed notation, so a literal single-site edit is a `{old} → {new}` clause, many sites sharing one edit are a table captioned with what is invariant across its rows, and a structural edit is a prose clause naming the shape of the resulting diff. A code snippet is one rendering among these, never the required form.
|
|
326
|
+
- When an entry covers several sites and deliberately leaves one of them alone, it names that site with the reason. The entry states its own boundary rather than leaving the reader to infer it from silence.
|
|
327
|
+
|
|
328
|
+
Every finding has one of the two shapes that the [Proposed-change gate](../review-criteria/SKILL.md#proposed-change-gate) defines, and a source entry renders which one it has: a single named change, or a choice among named alternatives that the author decides. The second is tagged as the author's choice, and its alternatives are named rather than resolved.
|
|
329
|
+
|
|
330
|
+
Do not render an exclusions line. A criterion genuinely arguable as in conflict belongs in the delta, where the user can strike it. Listing what was left out adds noise and hides the proposal that it was meant to qualify.
|
|
331
|
+
|
|
332
|
+
**Open findings.** When a ticket or PR-description delta line would settle or obviate an open finding, follow it with a sibling `⚠️` list item naming that finding, so that the user can see that accepting the edit pre-empts the finding's disposition. Those preview lists stay flat; nothing nests beneath a delta line.
|
|
333
|
+
|
|
334
|
+
**The preview is the contract.** The edit executed is the edit previewed. When carrying it out reveals a change that the preview did not contain, stop and re-confirm with the new line shown; never widen the edit under consent already given.
|
|
335
|
+
|
|
336
|
+
**Empty delta.** When the judgment drops every line, the Deviations sub-block has nothing to propose and does not render at all; see its [trigger](#deviations-sub-block). When a source divergence proposes a PR-description edit, that delta is never empty, because a divergence that the implementation resolves in the ticket's favor always leaves a claim to reconcile.
|
|
337
|
+
|
|
338
|
+
### Deviations sub-block
|
|
339
|
+
|
|
340
|
+
Shown when at least one criterion in the ticket subsection of `## Specification compliance` is in conflict with the implementation, equivalently when the criteria delta contains at least one line. Compute the delta first: When it is empty, do not render the sub-block.
|
|
341
|
+
|
|
342
|
+
A criterion from another spec source never fires this sub-block, whose only edit rewrites the ticket. Every ticket edit offered by a review is this sub-block's, and a PR description at odds with the implementation is the [source divergence sub-block](#source-divergence-sub-block)'s.
|
|
343
|
+
|
|
344
|
+
A criterion that is merely unbuilt does not contribute a line. The work is unfinished, not redirected, and a contract is not revised to match a moving target. Implementation that exceeds the criteria contributes none either.
|
|
345
|
+
|
|
346
|
+
#### Options
|
|
347
|
+
|
|
348
|
+
| # | Emoji | Option | Description |
|
|
349
|
+
| --- | ----- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
350
|
+
| 1 | 📝 | Update the acceptance criteria | Run `align-ticket-with-implementation`, which revises acceptance criteria alone, bound to the previewed delta, and writes the ticket of record when one resolves |
|
|
351
|
+
| 2 | ⏭️ | Leave as-is | Accept the deviation without updating the ticket |
|
|
352
|
+
|
|
353
|
+
#### Output format
|
|
354
|
+
|
|
355
|
+
Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker. Option 1 renders the criteria delta above the list per [proposed-edit preview](#proposed-edit-preview). Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific deviation presents a tradeoff that survives the option-format tests (e.g., "the abandoned criterion was load-bearing for downstream tests"). Generic restatements ("ships faster," "ticket drifts from reality") are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
|
|
356
|
+
|
|
357
|
+
**Name the artifact that the edit writes.** Option 1's rendered line ends with its target: `on {ticket_ref}` when a ticket of record resolves, whichever artifact supplied the spec source, and `in the local ticket snapshot` when none does. A ticket of record is the manifest's `ticket_url`, or `ticket_id` with `scm`; when auto-resolve passed over a remote candidate on recency, it already has one.
|
|
358
|
+
|
|
359
|
+
**Offer the local-only form when the snapshot may be the contract.** When the review measured against the local snapshot while a remote candidate existed, nest one invocation line under option 1; omit it otherwise:
|
|
360
|
+
|
|
361
|
+
```
|
|
362
|
+
1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
|
|
363
|
+
- or `1 local`: update the local snapshot alone, leaving {ticket_ref} as it stands
|
|
364
|
+
2. ⏭️ ■□□ Leave as-is
|
|
365
|
+
```
|
|
366
|
+
|
|
367
|
+
For a selection qualified `local`, run the delegate with `--write-target=local`.
|
|
368
|
+
|
|
369
|
+
Example (rendered for the recommendation case):
|
|
370
|
+
|
|
371
|
+
```
|
|
372
|
+
Next steps:
|
|
373
|
+
|
|
374
|
+
Deviations from ticket:
|
|
375
|
+
|
|
376
|
+
Proposed edit to the acceptance criteria:
|
|
377
|
+
- Reword: "Warns on an unknown directive" → "Fails on an unknown directive"
|
|
378
|
+
- ⚠️ W2 asks whether an unknown directive should fail the run at all; accepting this reword settles it as the contract
|
|
379
|
+
- Drop: A `--strict` flag gates the new validation
|
|
380
|
+
|
|
381
|
+
1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
|
|
382
|
+
2. ⏭️ ■□□ Leave as-is
|
|
383
|
+
```
|
|
384
|
+
|
|
385
|
+
When the recommendation rules do not indicate a preference, omit markers from both options per the gradient's pure-taste-call form.
|
|
386
|
+
|
|
387
|
+
#### Recommendation rules
|
|
388
|
+
|
|
389
|
+
1. **Recommend "Update the acceptance criteria"**: The implementation's direction is deliberate and sound, so the criteria as written would lead a later reader to judge correct code wrong.
|
|
390
|
+
2. **Recommend "Leave as-is"**: The review raised a finding on the conflicting behavior. The code is in question, and revising the contract to match it would hide the finding.
|
|
391
|
+
3. **No recommendation** (omit markers from both options): The reviewer cannot tell whether the criteria or the implementation is the wrong one. The user decides.
|
|
392
|
+
|
|
393
|
+
#### Marker strengths
|
|
394
|
+
|
|
395
|
+
For rules 1 and 2, the recommended option's marker follows how cleanly the rule's test is met: ■■■ when the evidence is unambiguous (the direction is plainly deliberate and sound for rule 1, or the finding plainly stands for rule 2), and ■■□ when the reading is defensible but arguable. The other option takes ■□□. Under rule 3, both options go unmarked.
|
|
396
|
+
|
|
397
|
+
### Source divergence sub-block
|
|
398
|
+
|
|
399
|
+
Shown when the consistency section of the review reports a `partial` or `severe` verdict, and the divergence leaves a PR-description claim to reconcile. The consistency section renders only when two spec sources are present (ticket and PR description), so this sub-block appears in PR reviews. The case (which spec source the implementation matches) is drawn from the consistency-section table; see `review-branch/SKILL.md` § Specification consistency.
|
|
400
|
+
|
|
401
|
+
This sub-block edits the PR description alone. Because a ticket delta derives from in-conflict criteria rows, which are the [Deviations sub-block](#deviations-sub-block)'s trigger, a ticket edit offered here would duplicate that sub-block's preview and menu for one decision. Case 3 (the ticket is the stale source) therefore renders nothing of its own: When its divergence rests on a criterion, Deviations proposes the edit, and when it rests on a narrative section, the ticket's authoring-time record stands and nothing is proposed.
|
|
402
|
+
|
|
403
|
+
#### Options
|
|
404
|
+
|
|
405
|
+
The options are:
|
|
406
|
+
|
|
407
|
+
| Emoji | Option | Action |
|
|
408
|
+
| ----- | --------------------- | --------------------------------------------------- |
|
|
409
|
+
| 📝 | Update PR description | Edit the PR description to match the implementation |
|
|
410
|
+
| ⏭️ | Leave as-is | Accept the divergence |
|
|
411
|
+
|
|
412
|
+
Every case that renders offers both, so the pair is fixed; what varies by case is which marker each takes.
|
|
413
|
+
|
|
414
|
+
#### Output format
|
|
415
|
+
|
|
416
|
+
Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker per case. Option 1 renders its PR-description delta above the list, per [proposed-edit preview](#proposed-edit-preview); "Leave as-is" has none. Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific divergence presents a tradeoff that survives the option-format tests (e.g., "the diverging AC was load-bearing for adjacent work that has already shipped"). Generic restatements are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
|
|
417
|
+
|
|
418
|
+
Case 2 (implementation matches ticket; PR description is the stale source):
|
|
419
|
+
|
|
420
|
+
```
|
|
421
|
+
Source divergence:
|
|
422
|
+
|
|
423
|
+
Proposed edit to the PR description:
|
|
424
|
+
- D2: "Retries use a fixed 200ms delay" → "Retries use exponential backoff from 200ms"
|
|
425
|
+
|
|
426
|
+
1. 📝 ■■□ Update PR description
|
|
427
|
+
2. ⏭️ ■□□ Leave as-is
|
|
428
|
+
```
|
|
429
|
+
|
|
430
|
+
Case 3 (implementation matches PR description; ticket is the stale source) renders nothing; see [the sub-block's own scope](#source-divergence-sub-block).
|
|
431
|
+
|
|
432
|
+
Case 4 (implementation matches neither source, severe) renders the same pair as case 2, marker-free: The reviewer cannot tell whether the code or the specs are the wrong one, so it recommends neither. The "code is wrong" path is not offered here: The review's findings already report a divergence when the code is at fault, and disposing of those findings is the author's job (see the Findings sub-block).
|
|
433
|
+
|
|
434
|
+
Source-divergence options preserve conversation context, and the preview that each renders binds the reconciliation that follows, per [proposed-edit preview](#proposed-edit-preview).
|
|
435
|
+
|
|
436
|
+
#### Recommendation rules
|
|
437
|
+
|
|
438
|
+
In the typical flow, the ticket is written first and rarely revised, while the PR description describes the implementation as built. When the two diverge and the implementation matches one of them, the unmatched source is the stale one; update it to match reality. When the implementation matches neither (severe), the reviewer cannot attribute the fault, so the menu offers only ratification of the PR description and leaves the code-is-wrong path to the findings.
|
|
439
|
+
|
|
440
|
+
Determine the case from the implementation column of the consistency-section table:
|
|
441
|
+
|
|
442
|
+
| Implementation column shows | Verdict | Case | Recommended option |
|
|
443
|
+
| --------------------------------------------- | ------------ | ---- | ---------------------- |
|
|
444
|
+
| `🟢 ticket, 🟠/🔴 PR` on every divergent row | 🟠 `partial` | 2 | Update PR description |
|
|
445
|
+
| `🟠/🔴 ticket, 🟢 PR` on every divergent row | 🟠 `partial` | 3 | None (does not render) |
|
|
446
|
+
| `🟠/🔴 ticket, 🟠/🔴 PR` on any divergent row | 🔴 `severe` | 4 | None (marker-free) |
|
|
447
|
+
|
|
448
|
+
#### Marker strengths
|
|
449
|
+
|
|
450
|
+
For case 2, the recommended option's marker follows how cleanly the case's own test is met: ■■■ when the divergence is unambiguous and the PR description is plainly the stale source, ■■□ when which source leads is arguable. The other option takes ■□□. In case 4, both options go unmarked.
|
|
451
|
+
|
|
452
|
+
### Findings sub-block
|
|
453
|
+
|
|
454
|
+
Shown when the review has at least one finding.
|
|
455
|
+
|
|
456
|
+
The trigger does not include a tier condition; do not reintroduce one. Every finding emitted by a review has already cleared the [Proposed-change gate](../_data/artifact-conventions.md#proposed-change-gate), which requires it to name a change on which the author can act; anything without an envisioned change was dropped before it was written to the artifact. Severity orders how findings rank and what blocks merge. It never decides whether they are shown, or whether the user is offered a way to act on them.
|
|
457
|
+
|
|
458
|
+
Stating the trigger as a list of tiers is the failure that this rule replaces: An enumeration goes stale the next time the finding scheme changes, and silently withdraws the menu from whichever tier it omits.
|
|
459
|
+
|
|
460
|
+
Legacy (`-L`) findings trigger the sub-block on the same terms, with the full option pool. Do not trim the author hand-offs for a legacy-only review: That would leave implementing-in-place as the only route and forfeit the adversarial second look, which pre-existing code needs at least as much as authored code, since a legacy fix is not constrained by any ticket criterion or supported by any design discussion. The recommendation rules handle legacy findings without a carve-out: A legacy fix naming a single change satisfies rule 2 like any other, and one leaving its choice to the author falls through to a ticket or a hand-off.
|
|
461
|
+
|
|
462
|
+
The option set depends on whether the review covers a pull request. Select the variant by the review that the agent just produced: A `review-pr` run has a PR reference in the review header and a PR-description spec source, and its author is typically someone else; a `review-branch` run has neither, and its code is typically our own.
|
|
463
|
+
|
|
464
|
+
#### Options: Local-branch variant (review-branch)
|
|
465
|
+
|
|
466
|
+
| # | Emoji | Option | Description |
|
|
467
|
+
| --- | ----- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
468
|
+
| 1 | 🚀 | Implement directly and commit | Fix the findings in this session and commit the fix |
|
|
469
|
+
| 2 | 📋 | Ask the author to address the findings | Hand the findings to the author for disposition |
|
|
470
|
+
| 3 | 📋🔍 | Wait for the author to address the findings, then re-review | Wait for the author's fixes, then re-review the branch |
|
|
471
|
+
| 4 | 🎫 | Create a follow-up ticket | Spin the separable findings into their own ticket, per `scope-and-deferral.md`; the next matching rule decides the rest |
|
|
472
|
+
|
|
473
|
+
#### Options: PR variant (review-pr)
|
|
474
|
+
|
|
475
|
+
| # | Emoji | Option | Description |
|
|
476
|
+
| --- | ----- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
477
|
+
| 1 | 📋 | Post findings on the PR | Post the findings as comments anchored to file and line. On Bitbucket, use the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md); GitHub does not have a posting mechanism yet (see #1018) |
|
|
478
|
+
| 2 | 🚀 | Implement directly and commit | Fix the findings in this session and commit the fix |
|
|
479
|
+
| 3 | 🎫 | Create a follow-up ticket | Spin the separable findings into their own ticket, per `scope-and-deferral.md`; the next matching rule decides the rest |
|
|
480
|
+
|
|
481
|
+
#### Output format
|
|
482
|
+
|
|
483
|
+
Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker. Whenever an option would change source, which is every rendering of this sub-block that offers "Implement directly and commit", the source delta renders above the list per [proposed-edit preview](#proposed-edit-preview). Pros and cons are omitted by default: Add a `➕` or `➖` line only when the specific findings present a tradeoff that survives the option-format tests bearing on which option fits (e.g., "the fixes touch a shared contract used outside this package"). Generic option properties are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
|
|
484
|
+
|
|
485
|
+
**What the commit records.** Selecting the option applies the previewed edits and commits them, composed per `{skill:create-commit}`, whose one-unit rule decides whether they form one commit or several. The commit is always a new one, never an amend: The separate commit keeps the fix visible as a diff and revertible while the branch exists, and a squash merge discards the history that an amend would tidy. Nothing is pushed, which matters most in the PR variant, in which the branch belongs to someone else.
|
|
486
|
+
|
|
487
|
+
**Naming the ticket's subset.** When only some open findings clear rule 1's spin-off bar, the follow-up-ticket line names the ones that it would cover, as `Create a follow-up ticket for R2, S1`. Choosing it disposes of those findings alone. In this case the ticket option composes with the recommendation rather than replacing it: The cascade's remaining rules run on the findings that the ticket does not cover, the option selected by those rules is the one marked, and answering with both numbers disposes of every open finding. A ticket option covering every open finding renders bare.
|
|
488
|
+
|
|
489
|
+
Local-branch variant, rendered for a review whose findings are all discretionary and all a single named change:
|
|
490
|
+
|
|
491
|
+
```
|
|
492
|
+
Next steps:
|
|
493
|
+
|
|
494
|
+
Actionable findings:
|
|
495
|
+
|
|
496
|
+
Proposed edits to the source:
|
|
497
|
+
|
|
498
|
+
**T1: test code.** Assert the corrected error classes in `parseRange.test.ts`. Every changed row keeps its message text and only gains the wrapper.
|
|
499
|
+
|
|
500
|
+
| Line | Case | `toThrow(…)` becomes |
|
|
501
|
+
| ------------ | ------------------- | -------------------------------------- |
|
|
502
|
+
| 62 | index out of bounds | `toThrow(new RangeError(msg))` |
|
|
503
|
+
| 33, 38, 43 | missing key | unchanged; that throw is still `Error` |
|
|
504
|
+
|
|
505
|
+
**S1: comment.** Replace the stale `@returns` line on `resolveBase` (`resolve.ts:88`) with a `todo:` naming what went stale.
|
|
506
|
+
|
|
507
|
+
1. 🚀 ■■□ Implement directly and commit
|
|
508
|
+
2. 📋 ■□□ Ask the author to address the findings
|
|
509
|
+
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
510
|
+
4. 🎫 ■□□ Create a follow-up ticket
|
|
511
|
+
|
|
512
|
+
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
513
|
+
```
|
|
514
|
+
|
|
515
|
+
Local-branch variant, rendered when a finding names alternatives that the author owns. The entry states the alternatives; choosing option 1 hands that call to whoever implements:
|
|
516
|
+
|
|
517
|
+
```
|
|
518
|
+
Next steps:
|
|
519
|
+
|
|
520
|
+
Actionable findings:
|
|
521
|
+
|
|
522
|
+
Proposed edits to the source:
|
|
523
|
+
|
|
524
|
+
**W2: source, author's choice.** `flush()` in `writer.ts:140` swallows the write error. Propagate it, or log and continue; which one turns on whether callers can recover.
|
|
525
|
+
|
|
526
|
+
1. 🚀 ■□□ Implement directly and commit
|
|
527
|
+
2. 📋 ■■□ Ask the author to address the findings
|
|
528
|
+
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
529
|
+
4. 🎫 ■□□ Create a follow-up ticket
|
|
530
|
+
|
|
531
|
+
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
532
|
+
```
|
|
533
|
+
|
|
534
|
+
Local-branch variant, rendered when three findings naming a single change each appear next to one separable recommendation. The ticket option's findings keep their entries, since the user is consenting to their disposition too:
|
|
535
|
+
|
|
536
|
+
```
|
|
537
|
+
Next steps:
|
|
538
|
+
|
|
539
|
+
Actionable findings:
|
|
540
|
+
|
|
541
|
+
Proposed edits to the source:
|
|
542
|
+
|
|
543
|
+
**S1: source.** Rename `x` to `descriptiveName` at its four sites in `resolve.ts`.
|
|
544
|
+
|
|
545
|
+
**S2: comment.** Drop the paraphrase above the `useDocumentTitle` call in `Header.tsx:31`.
|
|
546
|
+
|
|
547
|
+
**S3: test code.** Add the empty-input case to `parseRange.test.ts`, asserting the `RangeError` that the guard now throws.
|
|
548
|
+
|
|
549
|
+
**R2: source.** Extract the retry loop from `client.ts` into a helper shared by the three callers.
|
|
550
|
+
|
|
551
|
+
1. 🚀 ■■□ Implement directly and commit
|
|
552
|
+
2. 📋 ■□□ Ask the author to address the findings
|
|
553
|
+
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
554
|
+
4. 🎫 ■□□ Create a follow-up ticket for R2
|
|
555
|
+
|
|
556
|
+
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
557
|
+
```
|
|
558
|
+
|
|
559
|
+
PR variant, rendered for the default case. "Implement directly and commit" is on the menu, so the preview renders here too:
|
|
560
|
+
|
|
561
|
+
```
|
|
562
|
+
Next steps:
|
|
563
|
+
|
|
564
|
+
Actionable findings:
|
|
565
|
+
|
|
566
|
+
Proposed edits to the source:
|
|
567
|
+
|
|
568
|
+
**F1: source.** Guard the null branch in `parseRange.ts:44` before the index read, returning the empty result that the caller already handles.
|
|
569
|
+
|
|
570
|
+
**S1: test code.** Add the empty-input case to `parseRange.test.ts`.
|
|
571
|
+
|
|
572
|
+
1. 📋 ■■□ Post findings on the PR
|
|
573
|
+
2. 🚀 ■□□ Implement directly and commit
|
|
574
|
+
3. 🎫 ■□□ Create a follow-up ticket
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
Per the session-boundary rule, two options name a skill in the render:
|
|
578
|
+
|
|
579
|
+
- **Ask the author to address the findings**: The author's disposition happens in another session. The separate line below the list names `respond-to-review` for the case in which that author is an agent.
|
|
580
|
+
- **Wait for the author to address the findings, then re-review**: Names `review-branch` in the render, because the re-review runs after a wait that only the user can end. It does not have a "Clear context" prefix: The saved review records the findings, so the re-review works the same in this session or a fresh one.
|
|
581
|
+
|
|
582
|
+
#### Recommendation rules
|
|
583
|
+
|
|
584
|
+
Both variants share one cascade. Check the rules in order and stop at the first match. Every rule states a firing condition, and an option is never a default that fires for lack of one: A conditionless option outranks a conditioned one in practice, however the conditions are worded.
|
|
585
|
+
|
|
586
|
+
1. **Create a follow-up ticket**: Every open finding clears one of [`scope-and-deferral.md`](../_data/scope-and-deferral.md)'s affirmative reasons for spinning off, namely a genuinely separable concern, a materially different risk surface, size that would overwhelm the current change, or independent prioritization. "The ticket didn't mention it" is never such a reason. Absent an affirmative reason the fold-in default applies and the cascade continues.
|
|
587
|
+
2. **Implement directly and commit**: Every open finding names a single change rather than a choice among alternatives, which are the two shapes that the [Proposed-change gate](../review-criteria/SKILL.md#proposed-change-gate) admits. Implementing forfeits the second look, and the single-change shape makes that acceptable: The fix's diff is the finding restated, so a reviewer would be re-reading text that the review already contains. One finding leaving its choice to the author is enough to fail this rule, however small the alternatives look, since implementing would settle it on the author's behalf.
|
|
588
|
+
3. **Wait for the author to address the findings, then re-review**: The findings need judgment that the author owns, and the fixes are substantial enough that the result needs another review pass. PR variant: Skip this rule.
|
|
589
|
+
4. **Ask the author to address the findings**: Residual. The reviewer reports; the author disposes. PR variant: **Post findings on the PR**, since the author is typically someone else and comments on the PR are how they receive the findings.
|
|
590
|
+
|
|
591
|
+
Every rule tests the open findings as a collection, which lets one recommendation stand for the set. When only some findings clear rule 1's spin-off bar, the cascade evaluates the remainder: The recommendation comes from the findings that stay, while the separable ones go to the follow-up-ticket option, whose rendered line names them.
|
|
592
|
+
|
|
593
|
+
Whether a change is discretionary and which shape it has are independent axes. Whether a change is optional is a different question from who decides it: An `S` reading "rename `x` to `descriptiveName`" is discretionary and still a single named change, since the only decision left is yes or no and the person reading the menu is the one making it. Handing that to the author sends an edit that is already settled through a second session.
|
|
594
|
+
|
|
595
|
+
Do not attempt to detect whether the author is the person reading the review. Agents commit under the user's git identity, so the review's resolved `{author}` cannot distinguish them. Rule 2 turns on the review's own content, which is decidable.
|
|
596
|
+
|
|
597
|
+
#### Marker strengths
|
|
598
|
+
|
|
599
|
+
The selected option's marker follows how cleanly its rule matched: ■■■ when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, ■■□ when the fit is good but an alternative stays defensible, ■□□ when little separates the options. The others take ■□□ by default, and □□□ when one has a clear drawback in the current context.
|
|
600
|
+
|
|
601
|
+
Complexity levels classify individual findings, but the recommendation applies to the collection.
|
|
602
|
+
|
|
603
|
+
When the cascade's conditions leave two options genuinely in balance, prefer the one that keeps a human in the loop. That resolves a tie and nothing more: It never overrides a rule that fired, and a fix that satisfies rule 2's single-change test is not a tie.
|
|
604
|
+
|
|
605
|
+
### Blocked-step sub-block
|
|
606
|
+
|
|
607
|
+
Shown when something that the user can clear, such as a sandbox denial, a missing credential, or a stopped service, blocked a review step and remains once the routes that do not need any action from the user, such as an ephemeral runner for a missing tool, are exhausted. A clean review renders it like any other trigger. The line above the options names the step and the blocker, and the first option names the action that supplies the missing resource, such as a login or a grant, never the blocked step for the user to run:
|
|
608
|
+
|
|
609
|
+
```
|
|
610
|
+
{step} was blocked: {blocker}.
|
|
611
|
+
|
|
612
|
+
1. 🔓 ■■■ {Action that supplies the resource, e.g. run `! {login command}`}, then re-run {step}
|
|
613
|
+
2. ⏭️ ■□□ Accept the review without {step}
|
|
614
|
+
```
|
|
615
|
+
|
|
616
|
+
### Combined output format
|
|
617
|
+
|
|
618
|
+
When multiple sub-blocks are shown, present them as separate sections within a single next-steps block. Ordering is Blocked step → Deviations → Source divergence → Actionable findings. Each sub-block that edits an artifact edits a different one, so selecting several runs each edit against its own preview. Because source divergence appears only in PR reviews, a block that includes it renders the Findings PR variant. The example below illustrates one such arrangement; each sub-block's recommendation rules and marker strengths determine which marker applies to each option:
|
|
619
|
+
|
|
620
|
+
```
|
|
621
|
+
Next steps:
|
|
622
|
+
|
|
623
|
+
**A1: Deviations from ticket**
|
|
624
|
+
|
|
625
|
+
Proposed edit to the acceptance criteria:
|
|
626
|
+
- Drop: A `--strict` flag gates the new validation
|
|
627
|
+
|
|
628
|
+
1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
|
|
629
|
+
2. ⏭️ ■□□ Leave as-is
|
|
630
|
+
|
|
631
|
+
**A2: Source divergence**
|
|
632
|
+
|
|
633
|
+
Proposed edit to the PR description:
|
|
634
|
+
- D2: "Unknown directives are warned on" → "Unknown directives fail the run"
|
|
635
|
+
|
|
636
|
+
1. 📝 ■■□ Update PR description
|
|
637
|
+
2. ⏭️ ■□□ Leave as-is
|
|
638
|
+
|
|
639
|
+
**A3: Actionable findings**
|
|
640
|
+
|
|
641
|
+
Proposed edits to the source:
|
|
642
|
+
|
|
643
|
+
**F1: source.** Fail on an unknown directive in `directives.ts:52`, replacing the warning that the loop currently emits.
|
|
644
|
+
|
|
645
|
+
**S1: test code.** Add the unknown-directive case to `directives.test.ts`, asserting the failure.
|
|
646
|
+
|
|
647
|
+
1. 📋 ■■□ Post findings on the PR
|
|
648
|
+
2. 🚀 ■□□ Implement directly and commit
|
|
649
|
+
3. 🎫 ■□□ Create a follow-up ticket
|
|
650
|
+
```
|
|
300
651
|
|
|
301
652
|
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -16,9 +16,10 @@ Evaluation criteria for code review. Apply proportionally: Match depth to risk.
|
|
|
16
16
|
|
|
17
17
|
- **Correctness**: Logic errors, unhandled error paths, data loss risks
|
|
18
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
|
|
19
20
|
- **Conventions**: Adherence to codebase patterns and project standards
|
|
20
21
|
- **Edge cases**: Boundary conditions, empty collections, zero values, undefined states
|
|
21
|
-
- **Test coverage**: Adequate tests for new functionality; tests that verify behavior and
|
|
22
|
+
- **Test coverage**: Adequate tests for new functionality; tests that verify behavior and are worth keeping, not just coverage
|
|
22
23
|
- **Clarity**: Naming, documentation, and instructions convey unambiguous intent
|
|
23
24
|
- **Contracts**: Documented behaviors match implementations; implicit assumptions are explicit
|
|
24
25
|
- **Type safety**: Type issues that affect correctness or maintainability
|
|
@@ -67,7 +68,7 @@ Comment text that you propose for a source file (a replacement doc comment, a su
|
|
|
67
68
|
|
|
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.
|
|
69
70
|
|
|
70
|
-
## Do not recommend a test that
|
|
71
|
+
## Do not recommend a test that is not worth keeping
|
|
71
72
|
|
|
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.
|
|
73
74
|
|
|
@@ -75,12 +76,44 @@ The commonest instance is a test asserting that deleted code, text, or behavior
|
|
|
75
76
|
|
|
76
77
|
## Grown test files
|
|
77
78
|
|
|
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.
|
|
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.
|
|
79
108
|
|
|
80
109
|
## Noisy tests
|
|
81
110
|
|
|
82
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.
|
|
83
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
|
+
|
|
84
117
|
## Finding references
|
|
85
118
|
|
|
86
119
|
Conventions for how findings reference files and code locations.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var
|
|
4
|
-
`)
|
|
5
|
-
`)}
|
|
6
|
-
`)}
|
|
7
|
-
`)
|
|
8
|
-
`)
|
|
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();
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: revise-comments
|
|
3
|
-
description: Revise comments in target files per the comment-discipline rules, editing in place
|
|
3
|
+
description: Revise comments in target files per the comment-discipline rules, adding missing code descriptions and fixing drifted ones, editing in place
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Revise comments
|
|
8
8
|
|
|
9
|
-
Apply the comment-discipline audit to a target file set, editing comments in place. The default workflow is `{skill:revise-comments}` after a feature is implemented; explicit paths support cleaning up legacy code.
|
|
9
|
+
Apply the comment-discipline audit to a target file set, editing comments in place: Keep, delete, or rewrite each comment, add a description to each declaration that lacks one, and rewrite each description that misstates its code. The default workflow is `{skill:revise-comments}` after a feature is implemented; explicit paths support cleaning up legacy code.
|
|
10
10
|
|
|
11
11
|
If the `revise-prose` sweep is wanted on the same files, run this skill first: It decides whether a comment exists at all, and it may delete the very comment that the prose sweep would otherwise polish.
|
|
12
12
|
|
|
@@ -26,9 +26,9 @@ If the `revise-prose` sweep is wanted on the same files, run this skill first: I
|
|
|
26
26
|
git diff --name-only "{default_branch}...HEAD"
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
2. **Apply the audit per file.** Read each target file. Put every comment through the tests below. Decide one of
|
|
29
|
+
2. **Apply the audit per file.** Read each target file. Put every comment through the tests below, and every declaration through [Description coverage and accuracy](#description-coverage-and-accuracy). Decide one of four actions: kept, deleted, rewritten, or added. In normal mode, apply edits in place via the Edit tool. In `--dry-run` mode, record the proposed action without editing.
|
|
30
30
|
|
|
31
|
-
3. **Audit the diff** per [Diff audit](#diff-audit), over the edits just applied. A re-worded comment is the reach sweep's central case: It can invalidate a sibling doc, a README, or a test title that echoed the phrasing that it replaced. Such a file is outside the resolved target set, so the hard gate in [Target file set](#target-file-set) applies
|
|
31
|
+
3. **Audit the diff** per [Diff audit](#diff-audit), over the edits just applied. A re-worded comment is the reach sweep's central case: It can invalidate a sibling doc, a README, or a test title that echoed the phrasing that it replaced. Such a file is outside the resolved target set, so the hard gate in [Target file set](#target-file-set) applies: Report the hit to the user alongside the summary rather than repair it. Because `--dry-run` does not apply any edits, the step is skipped under that flag.
|
|
32
32
|
|
|
33
33
|
4. **Emit the summary.** After processing all targets, emit one table per file with non-trivial decisions.
|
|
34
34
|
|
|
@@ -38,6 +38,15 @@ If the `revise-prose` sweep is wanted on the same files, run this skill first: I
|
|
|
38
38
|
|
|
39
39
|
<!-- include: ../../_partials/diff-audit-checklist.md / -->
|
|
40
40
|
|
|
41
|
+
## Description coverage and accuracy
|
|
42
|
+
|
|
43
|
+
Because the baseline above requires a description, this skill acts on declarations as well as on the comments that they have:
|
|
44
|
+
|
|
45
|
+
- **Coverage.** Add a description (`added`) to each function, method, class, and component that lacks one, helpers in test files included. Skip an anonymous callback passed inline, which is not a declaration. Do not add one to a constant or a type, for which the baseline makes a description optional.
|
|
46
|
+
- **Accuracy.** Compare each description with the code that it describes, and rewrite one that misstates what the code does or is. Length alone is not a reason to rewrite an accurate description.
|
|
47
|
+
- **Never deleted.** Rewrite a declaration's description that fails one of the four tests; never delete it, because the baseline requires one.
|
|
48
|
+
- **Form.** Write an added or rewritten description in the doc-comment form that the file already uses, or else in the language's standard form, such as JSDoc in TypeScript.
|
|
49
|
+
|
|
41
50
|
## File-level carve-outs
|
|
42
51
|
|
|
43
52
|
The carve-outs above apply to comments. Two file-level rules decide which lines this skill may touch at all:
|
|
@@ -52,6 +61,7 @@ The default is to act. Pause and ask the user when one of these holds:
|
|
|
52
61
|
- A test comment could plausibly be non-obvious setup, but the test name already conveys the setup intent.
|
|
53
62
|
- An `eslint-disable` rationale is at the boundary between tight and over-scoped.
|
|
54
63
|
- A file header describes potentially load-bearing architecture (composition order, threading model, invariants across functions), so it may state a constraint that the code cannot show.
|
|
64
|
+
- A description and its code disagree, and the code could be the part that is wrong, such as when the declaration's name agrees with the description. Rewriting the description would record the defect as intended behavior, and this skill never edits code.
|
|
55
65
|
|
|
56
66
|
## Summary format
|
|
57
67
|
|
|
@@ -69,7 +79,9 @@ src/lib/payload.ts
|
|
|
69
79
|
| 6 | kept | n/a | why-inline |
|
|
70
80
|
```
|
|
71
81
|
|
|
72
|
-
|
|
82
|
+
`Test` names the test that decided the action: one of the four, `accuracy`, `baseline` for an added description, or `n/a`. For `added`, `Line` is the declaration's line.
|
|
83
|
+
|
|
84
|
+
Line numbers refer to the pre-edit file, so check each row against `git diff` output before emitting the table: The `Action` column reports what the diff shows, not what was intended. For a comment failing more than one test, report the first that it fails.
|
|
73
85
|
|
|
74
86
|
## Worked example
|
|
75
87
|
|
|
@@ -87,6 +99,15 @@ export function buildPayload(input: Input): Payload {
|
|
|
87
99
|
const items = Array.isArray(input.value) ? input.value : [input.value];
|
|
88
100
|
return { items };
|
|
89
101
|
}
|
|
102
|
+
|
|
103
|
+
/** Returns the first item, or undefined when the payload is empty. */
|
|
104
|
+
export function lastItem(payload: Payload): Item | undefined {
|
|
105
|
+
return payload.items.at(-1);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function isEmptyPayload(payload: Payload): boolean {
|
|
109
|
+
return payload.items.length === 0;
|
|
110
|
+
}
|
|
90
111
|
```
|
|
91
112
|
|
|
92
113
|
**After:**
|
|
@@ -98,6 +119,16 @@ export function buildPayload(input: Input): Payload {
|
|
|
98
119
|
const items = Array.isArray(input.value) ? input.value : [input.value];
|
|
99
120
|
return { items };
|
|
100
121
|
}
|
|
122
|
+
|
|
123
|
+
/** Returns the last item, or undefined when the payload is empty. */
|
|
124
|
+
export function lastItem(payload: Payload): Item | undefined {
|
|
125
|
+
return payload.items.at(-1);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Reports whether the payload has no items. */
|
|
129
|
+
export function isEmptyPayload(payload: Payload): boolean {
|
|
130
|
+
return payload.items.length === 0;
|
|
131
|
+
}
|
|
101
132
|
```
|
|
102
133
|
|
|
103
134
|
**Summary emitted:**
|
|
@@ -112,4 +143,6 @@ src/lib/payload.ts
|
|
|
112
143
|
| 2 | deleted | stranger | PR reference |
|
|
113
144
|
| 4 | rewritten | stranger | "we discussed" |
|
|
114
145
|
| 6 | kept | n/a | why-inline |
|
|
146
|
+
| 11 | rewritten | accuracy | says first; code returns last |
|
|
147
|
+
| 16 | added | baseline | no description |
|
|
115
148
|
```
|
|
@@ -122,7 +122,7 @@ rules: {rule-id}, {rule-id}
|
|
|
122
122
|
EOF
|
|
123
123
|
```
|
|
124
124
|
|
|
125
|
-
`sweptAt` is today's ISO calendar date. `roots` lists the invocation's narrowing paths, or `["."]` for a whole-repository sweep. `units` names every unit from step 1 at its current version. `rules` names every rule that step 2 passed with a version, `plain-speech` included, with its unit and its sweep version; the helper records for each whether it
|
|
125
|
+
`sweptAt` is today's ISO calendar date. `roots` lists the invocation's narrowing paths, or `["."]` for a whole-repository sweep. `units` names every unit from step 1 at its current version. `rules` names every rule that step 2 passed with a version, `plain-speech` included, with its unit and its sweep version; the helper records for each whether it has a detector for the rule.
|
|
126
126
|
|
|
127
127
|
`rejections` contains every subagent rejection plus every questionable rejected in step 5.1, by you or by the user, each containing `rule`, `file`, `phrase` as the text reads after this run's edits, and `ground`. A rejected questionable's `ground` is the reason recorded for its rejection. Leave out a rejection under a rule that `rules` does not name, which is a rule without a sweep version: Nothing records such a rule, and the helper refuses the fold.
|
|
128
128
|
|