codeassembly-guidance 0.2.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.
Files changed (88) hide show
  1. package/.meta/changelog.json +227 -0
  2. package/CHANGELOG.md +59 -0
  3. package/README.md +37 -121
  4. package/content/_partials/README.md +19 -3
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/kb-standard-tags.md +7 -0
  7. package/content/codeassembly-content.yaml +6 -0
  8. package/content/collections/recommended.md +1 -1
  9. package/content/guidance/README.md +1 -1
  10. package/content/guidance/rulebooks/cli-conventions.md +16 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
  12. package/content/guidance/rulebooks/commit-conventions.md +3 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
  14. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  15. package/content/guidance/shared/AGENTS.md +31 -4
  16. package/content/scripts/check-prose.mjs +38 -38
  17. package/content/scripts/describe-change.mjs +69 -69
  18. package/content/scripts/manage-jira-ticket.mjs +73 -73
  19. package/content/scripts/validate-preferences.mjs +1 -1
  20. package/content/skills/_data/action-items.md +2 -0
  21. package/content/skills/_data/artifact-conventions.md +18 -2
  22. package/content/skills/_data/complexity-classification.md +1 -1
  23. package/content/skills/_data/design-priorities.md +12 -1
  24. package/content/skills/_data/spike-conventions.md +21 -6
  25. package/content/skills/_data/title-templates.md +3 -1
  26. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  27. package/content/skills/_partials/commit-title-rendering.md +1 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +1 -1
  29. package/content/skills/_partials/option-format.md +2 -2
  30. package/content/skills/_partials/plan-template.md +4 -2
  31. package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
  32. package/content/skills/_partials/ticket-composition.md +40 -0
  33. package/content/skills/_partials/ticket-skeleton.md +15 -1
  34. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
  35. package/content/skills/assess-code-health/SKILL.md +127 -0
  36. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  37. package/content/skills/assess-usability/SKILL.md +3 -1
  38. package/content/skills/capture-event/SKILL.md +2 -0
  39. package/content/skills/capture-feedback/SKILL.md +1 -1
  40. package/content/skills/collaborate/SKILL.md +2 -2
  41. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  42. package/content/skills/create-commit/SKILL.md +1 -1
  43. package/content/skills/create-gh-pr/SKILL.md +4 -1
  44. package/content/skills/create-pr/SKILL.md +2 -1
  45. package/content/skills/create-ticket/SKILL.md +3 -7
  46. package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
  47. package/content/skills/design-and-plan/SKILL.md +5 -9
  48. package/content/skills/implement-plan/SKILL.md +2 -2
  49. package/content/skills/index-prototypes/SKILL.md +1 -1
  50. package/content/skills/kb-add/SKILL.md +2 -0
  51. package/content/skills/kb-edit/SKILL.md +2 -0
  52. package/content/skills/kb-edit/kb-edit.mjs +24 -24
  53. package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
  54. package/content/skills/kb-retrieve-events/SKILL.md +19 -10
  55. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
  56. package/content/skills/kb-update-events/SKILL.md +9 -6
  57. package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
  58. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  59. package/content/skills/plan/SKILL.md +1 -1
  60. package/content/skills/refine-guidance/SKILL.md +97 -0
  61. package/content/skills/review-branch/SKILL.md +350 -1
  62. package/content/skills/revise-prose/revise-prose.mjs +85 -85
  63. package/content/skills/save-artifact/SKILL.md +1 -1
  64. package/content/skills/streamline-guidance/SKILL.md +10 -15
  65. package/content/skills/streamline-guidance/streamline-guidance.mjs +73 -73
  66. package/content/skills/summarize-change/SKILL.md +1 -1
  67. package/content/skills/testing-conventions/SKILL.md +7 -1
  68. package/content/skills/triage-feedback/SKILL.md +150 -0
  69. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  70. package/content/skills/triage-spike-findings/SKILL.md +5 -5
  71. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
  72. package/content/skills/update-project-guidance/SKILL.md +10 -10
  73. package/content/subagents/code-health-assessor.md +98 -0
  74. package/content/subagents/feedback-triage-challenger.md +81 -0
  75. package/content/subagents/lesson-clusterer.md +68 -0
  76. package/package.json +13 -13
  77. package/schemas/preferences.v1.json +22 -6
  78. package/schemas/work-types.v1.json +1 -1
  79. package/content/_partials/code-descriptions.md +0 -4
  80. package/content/_partials/code-style.md +0 -7
  81. package/content/_partials/live-repo-writes.md +0 -13
  82. package/content/_partials/reduced-object-relative.md +0 -28
  83. package/content/_partials/test-structure-audit-checklist.md +0 -7
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  85. package/content/skills/_partials/next-steps-after-review.md +0 -350
  86. package/content/skills/_partials/ticket-concision.md +0 -18
  87. package/content/skills/_partials/ticket-placement.md +0 -14
  88. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
@@ -36,7 +36,7 @@ The body following the frontmatter uses the shared implementation-plan template,
36
36
  - Focus on clarity and actionability
37
37
  - Include concrete steps, not vague goals
38
38
  - Call out risks and unknowns explicitly
39
- - When comparing approaches, rank options per [design priorities](../_data/design-priorities.md)
39
+ - When comparing approaches, rank options per [design priorities](../_data/design-priorities.md), including [who applies the change](../_data/design-priorities.md#who-applies-the-change): A design that needs a person to act on each machine is a defect to raise, not a step to document
40
40
 
41
41
  ## Sweep for completeness
42
42
 
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: refine-guidance
3
+ description: Turn a lesson into a guidance change, conversationally. Finds the rule that already states the lesson or places a new artifact per the content specification, confirms the placement, drafts the edits for approval, applies them, opens a pull request, and marks any feedback events that the lesson came with as addressed by it. Use when a lesson from the conversation, a pasted finding, or a triage-feedback ticket should become a change to a skill, subagent, rulebook, partial, or AGENTS.md.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Refine guidance
8
+
9
+ Turn one lesson into one guidance pull request. You find whether a rule already states the lesson, place the change, draft the edits, and deliver them; the developer approves the placement and then the edits. A rule that exists and keeps failing is the common case, and it calls for changing that rule rather than adding a parallel one.
10
+
11
+ **Announce at start:** "Using refine-guidance to turn this lesson into a guidance change."
12
+
13
+ ## Arguments
14
+
15
+ | Argument | Description | Required |
16
+ | ---------------- | --------------------------------------------------------------------------------------------------- | -------- |
17
+ | `[target]` | A guidance file to change: a source file or a deployed copy. Without one, step 4 places the change. | No |
18
+ | `--ticket <ref>` | A ticket that states the lesson, such as one that {skill?:triage-feedback} filed. | No |
19
+
20
+ The lesson comes from the conversation when the conversation states one. Otherwise it comes from `--ticket`, and without that, from the branch's ticket.
21
+
22
+ ## Prerequisites
23
+
24
+ Placement follows the `codeassembly-content-specification` rulebook, which deploys as the `consult-codeassembly-content-specification` skill in a repository that declares it. When it is not deployed, report that and stop before step 4.
25
+
26
+ ## Never edit
27
+
28
+ - Text inside a generated region, which the next deployment rewrites.
29
+ - A deployed copy. Edit its source, which step 3 resolves.
30
+ - A file in another repository. Step 4 offers a ticket there instead.
31
+
32
+ ## Process
33
+
34
+ ### 1. Preflight
35
+
36
+ Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `branch_name`, `default_branch`, and `ticket_id`. Stop on the default branch, and report that the change needs a ticket branch: This skill commits and opens a pull request from the current branch.
37
+
38
+ ### 2. Resolve the lesson
39
+
40
+ Take the lesson from the conversation or from a finding pasted into it. When the conversation does not state one, resolve `--ticket`, or else the branch's ticket, per [ticket source resolution](../_data/ticket-source-resolution.md), and take the lesson from the ticket. Restate the lesson in one sentence: the behavior that the agent showed and the behavior that the lesson asks for.
41
+
42
+ Collect any feedback event ids that the input contains, with their store. An event id is a ULID, 26 Crockford base32 characters; a {skill?:triage-feedback} ticket lists them in its context under the store name. When the input names ids without a store, the store is `@feedback`. Input without ids makes step 9 a no-op.
43
+
44
+ ### 3. Find existing coverage
45
+
46
+ Search the guidance for a rule that states the lesson: the library's content, the repository's `.agents/content`, and its `AGENTS.md`. Search with `rg` on the lesson's key terms, then read each matching section and the descriptions of the rulebooks that it reaches. A rule states the lesson when following its directive would have prevented the behavior that the lesson describes. A rule that covers the lesson in part is still the rule to change.
47
+
48
+ Run `resolve` on the target, or on the files that the search found:
49
+
50
+ ```bash
51
+ node {harness_home_dir}/skills/streamline-guidance/streamline-guidance.mjs resolve {paths}
52
+ ```
53
+
54
+ It maps each deployed copy to its source (`redirectedFrom`) and reports each file's `dirty` state and `generatedRegions`. Report every redirect.
55
+
56
+ ### 4. Place the change
57
+
58
+ Decide the mode, and give its reason in one sentence:
59
+
60
+ - **An existing rule states the lesson**: `strengthen`, `relocate`, or `illustrate` it, per "Choosing a kind" in the content specification.
61
+ - **The guidance does not state it**: a new artifact, `new {kind} in {content root}`, with the kind and the content root chosen per the same section.
62
+
63
+ Decide which repository owns the target. A file with a `<!-- codeassembly-` marker, or a file in the CodeAssembly guidance library, belongs to the CodeAssembly repository, per [deployed-file provenance](../_data/deployed-file-provenance.md); a project's `.agents/content` file or `AGENTS.md` belongs to that project's repository. When the owner is not the current repository, do not edit the file: Offer to file the lesson there with {skill:create-ticket} `--repo {repo}`, and stop.
64
+
65
+ Present the placement: the lesson, the mode and its reason, and the target file or the new artifact's path. Ask for confirmation before drafting.
66
+
67
+ ### 5. Draft the edits
68
+
69
+ Draft under "Adding guidance" in the content specification: Change the fewest surfaces that plausibly account for the behavior, and trim any text that the change makes redundant, in that file or another. A new artifact follows the content specification and the repository's content conventions: its frontmatter, its naming, its dependency declarations, and the tests that the repository runs over its content.
70
+
71
+ Before presenting the edits, run `resolve` on every existing file that a drafted edit changes and on each rulebook whose `version` step 6 will bump. Stop if any of them is `dirty`, and name it: The commit must contain only this run's edits.
72
+
73
+ Present each edit as a numbered row: file, line, the text that it replaces (or `new file`), and the new text. Ask for one approval that covers applying the edits, the commit, the push, and the pull request. A row that the developer declines is dropped; re-draft only when the developer asks.
74
+
75
+ ### 6. Apply
76
+
77
+ <!-- include: ../_partials/apply-guidance-edits.md / -->
78
+
79
+ ### 7. Commit
80
+
81
+ Commit per {skill:create-commit}, passing the edited paths and the purpose `{mode}: {reason}` from step 4.
82
+
83
+ ### 8. Open the pull request
84
+
85
+ Push with `git push --set-upstream origin HEAD`, which the approval in step 5 covers: {skill:create-pr} does not push, and it stops when the branch is not up to date with its remote. On a failed push, report it and stop. Then open the pull request with {skill:create-pr}.
86
+
87
+ ### 9. Mark the events
88
+
89
+ Skip this step when step 2 did not collect any event id: This skill does not write to a knowledge base otherwise.
90
+
91
+ Mark the events with {skill:kb-update-events}: `--store {store} --add-addressed-by={pull request URL}` and the event ids. Report each id whose result has `ok: false`.
92
+
93
+ ### 10. Report
94
+
95
+ Report the pull request's URL, the mode and its reason, the edited files, the marked event ids, and each id that failed. When an edited file is larger than before, offer {skill:streamline-guidance} on it in the action-items block, per "Adding guidance": That run commits on the same branch, which adds its cuts to the open pull request. The block contains nothing else.
96
+
97
+ <!-- include: ../_partials/action-items.md / -->
@@ -298,6 +298,355 @@ The review is saved as a run artifact: `{timestamp}_reviewer_review.md`
298
298
 
299
299
  Each review is a separate artifact in the run directory. Do not append to existing files: The chronological sequence of files is the history.
300
300
 
301
- <!-- include: ../_partials/next-steps-after-review.md / -->
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
+ ```
302
651
 
303
652
  <!-- include: ../_partials/option-format.md / -->