codeassembly-guidance 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,350 @@
1
+ ## Next-steps options
2
+
3
+ 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.
4
+
5
+ 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).
6
+
7
+ **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.
8
+
9
+ **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.
10
+
11
+ ### Proposed-edit preview
12
+
13
+ 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.
14
+
15
+ **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.
16
+
17
+ 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.
18
+
19
+ **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:
20
+
21
+ - **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.
22
+ - `Reword: {old} → {new}` for a criterion whose direction the implementation deliberately contradicts
23
+ - `Drop: {criterion}` for a criterion that the implementation deliberately abandoned, never for one that it has not yet reached
24
+ - **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}`.
25
+ - **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.
26
+ - 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.
27
+
28
+ 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.
29
+
30
+ 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.
31
+
32
+ **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.
33
+
34
+ **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.
35
+
36
+ **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.
37
+
38
+ ### Deviations sub-block
39
+
40
+ 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.
41
+
42
+ 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.
43
+
44
+ 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.
45
+
46
+ #### Options
47
+
48
+ | # | Emoji | Option | Description |
49
+ | --- | ----- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
50
+ | 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 |
51
+ | 2 | ⏭️ | Leave as-is | Accept the deviation without updating the ticket |
52
+
53
+ #### Output format
54
+
55
+ 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.
56
+
57
+ **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.
58
+
59
+ **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:
60
+
61
+ ```
62
+ 1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
63
+ - or `1 local`: update the local snapshot alone, leaving {ticket_ref} as it stands
64
+ 2. ⏭️ ■□□ Leave as-is
65
+ ```
66
+
67
+ For a selection qualified `local`, run the delegate with `--write-target=local`.
68
+
69
+ Example (rendered for the recommendation case):
70
+
71
+ ```
72
+ Next steps:
73
+
74
+ Deviations from ticket:
75
+
76
+ Proposed edit to the acceptance criteria:
77
+ - Reword: "Warns on an unknown directive" → "Fails on an unknown directive"
78
+ - ⚠️ W2 asks whether an unknown directive should fail the run at all; accepting this reword settles it as the contract
79
+ - Drop: A `--strict` flag gates the new validation
80
+
81
+ 1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
82
+ 2. ⏭️ ■□□ Leave as-is
83
+ ```
84
+
85
+ When the recommendation rules do not indicate a preference, omit markers from both options per the gradient's pure-taste-call form.
86
+
87
+ #### Recommendation rules
88
+
89
+ 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.
90
+ 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.
91
+ 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.
92
+
93
+ #### Marker strengths
94
+
95
+ 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.
96
+
97
+ ### Source divergence sub-block
98
+
99
+ 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.
100
+
101
+ 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.
102
+
103
+ #### Options
104
+
105
+ The options are:
106
+
107
+ | Emoji | Option | Action |
108
+ | ----- | --------------------- | --------------------------------------------------- |
109
+ | 📝 | Update PR description | Edit the PR description to match the implementation |
110
+ | ⏭️ | Leave as-is | Accept the divergence |
111
+
112
+ Every case that renders offers both, so the pair is fixed; what varies by case is which marker each takes.
113
+
114
+ #### Output format
115
+
116
+ 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.
117
+
118
+ Case 2 (implementation matches ticket; PR description is the stale source):
119
+
120
+ ```
121
+ Source divergence:
122
+
123
+ Proposed edit to the PR description:
124
+ - D2: "Retries use a fixed 200ms delay" → "Retries use exponential backoff from 200ms"
125
+
126
+ 1. 📝 ■■□ Update PR description
127
+ 2. ⏭️ ■□□ Leave as-is
128
+ ```
129
+
130
+ Case 3 (implementation matches PR description; ticket is the stale source) renders nothing; see [the sub-block's own scope](#source-divergence-sub-block).
131
+
132
+ 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).
133
+
134
+ Source-divergence options preserve conversation context, and the preview that each renders binds the reconciliation that follows, per [proposed-edit preview](#proposed-edit-preview).
135
+
136
+ #### Recommendation rules
137
+
138
+ 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.
139
+
140
+ Determine the case from the implementation column of the consistency-section table:
141
+
142
+ | Implementation column shows | Verdict | Case | Recommended option |
143
+ | --------------------------------------------- | ------------ | ---- | ---------------------- |
144
+ | `🟢 ticket, 🟠/🔴 PR` on every divergent row | 🟠 `partial` | 2 | Update PR description |
145
+ | `🟠/🔴 ticket, 🟢 PR` on every divergent row | 🟠 `partial` | 3 | None (does not render) |
146
+ | `🟠/🔴 ticket, 🟠/🔴 PR` on any divergent row | 🔴 `severe` | 4 | None (marker-free) |
147
+
148
+ #### Marker strengths
149
+
150
+ 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.
151
+
152
+ ### Findings sub-block
153
+
154
+ Shown when the review has at least one finding.
155
+
156
+ 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.
157
+
158
+ 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.
159
+
160
+ 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.
161
+
162
+ 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.
163
+
164
+ #### Options: Local-branch variant (review-branch)
165
+
166
+ | # | Emoji | Option | Description |
167
+ | --- | ----- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
168
+ | 1 | 🚀 | Implement directly and commit | Fix the findings in this session and commit the fix |
169
+ | 2 | 📋 | Ask the author to address the findings | Hand the findings to the author for disposition |
170
+ | 3 | 📋🔍 | Wait for the author to address the findings, then re-review | Wait for the author's fixes, then re-review the branch |
171
+ | 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 |
172
+
173
+ #### Options: PR variant (review-pr)
174
+
175
+ | # | Emoji | Option | Description |
176
+ | --- | ----- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
177
+ | 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) |
178
+ | 2 | 🚀 | Implement directly and commit | Fix the findings in this session and commit the fix |
179
+ | 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 |
180
+
181
+ #### Output format
182
+
183
+ 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.
184
+
185
+ **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.
186
+
187
+ **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.
188
+
189
+ Local-branch variant, rendered for a review whose findings are all discretionary and all a single named change:
190
+
191
+ ```
192
+ Next steps:
193
+
194
+ Actionable findings:
195
+
196
+ Proposed edits to the source:
197
+
198
+ **T1: test code.** Assert the corrected error classes in `parseRange.test.ts`. Every changed row keeps its message text and only gains the wrapper.
199
+
200
+ | Line | Case | `toThrow(…)` becomes |
201
+ | ------------ | ------------------- | -------------------------------------- |
202
+ | 62 | index out of bounds | `toThrow(new RangeError(msg))` |
203
+ | 33, 38, 43 | missing key | unchanged; that throw is still `Error` |
204
+
205
+ **S1: comment.** Replace the stale `@returns` line on `resolveBase` (`resolve.ts:88`) with a `todo:` naming what went stale.
206
+
207
+ 1. 🚀 ■■□ Implement directly and commit
208
+ 2. 📋 ■□□ Ask the author to address the findings
209
+ 3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
210
+ 4. 🎫 ■□□ Create a follow-up ticket
211
+
212
+ If the author is an agent, run {skill?:respond-to-review} in that session.
213
+ ```
214
+
215
+ 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:
216
+
217
+ ```
218
+ Next steps:
219
+
220
+ Actionable findings:
221
+
222
+ Proposed edits to the source:
223
+
224
+ **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.
225
+
226
+ 1. 🚀 ■□□ Implement directly and commit
227
+ 2. 📋 ■■□ Ask the author to address the findings
228
+ 3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
229
+ 4. 🎫 ■□□ Create a follow-up ticket
230
+
231
+ If the author is an agent, run {skill?:respond-to-review} in that session.
232
+ ```
233
+
234
+ 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:
235
+
236
+ ```
237
+ Next steps:
238
+
239
+ Actionable findings:
240
+
241
+ Proposed edits to the source:
242
+
243
+ **S1: source.** Rename `x` to `descriptiveName` at its four sites in `resolve.ts`.
244
+
245
+ **S2: comment.** Drop the paraphrase above the `useDocumentTitle` call in `Header.tsx:31`.
246
+
247
+ **S3: test code.** Add the empty-input case to `parseRange.test.ts`, asserting the `RangeError` that the guard now throws.
248
+
249
+ **R2: source.** Extract the retry loop from `client.ts` into a helper shared by the three callers.
250
+
251
+ 1. 🚀 ■■□ Implement directly and commit
252
+ 2. 📋 ■□□ Ask the author to address the findings
253
+ 3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
254
+ 4. 🎫 ■□□ Create a follow-up ticket for R2
255
+
256
+ If the author is an agent, run {skill?:respond-to-review} in that session.
257
+ ```
258
+
259
+ PR variant, rendered for the default case. "Implement directly and commit" is on the menu, so the preview renders here too:
260
+
261
+ ```
262
+ Next steps:
263
+
264
+ Actionable findings:
265
+
266
+ Proposed edits to the source:
267
+
268
+ **F1: source.** Guard the null branch in `parseRange.ts:44` before the index read, returning the empty result that the caller already handles.
269
+
270
+ **S1: test code.** Add the empty-input case to `parseRange.test.ts`.
271
+
272
+ 1. 📋 ■■□ Post findings on the PR
273
+ 2. 🚀 ■□□ Implement directly and commit
274
+ 3. 🎫 ■□□ Create a follow-up ticket
275
+ ```
276
+
277
+ Per the session-boundary rule, two options name a skill in the render:
278
+
279
+ - **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.
280
+ - **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.
281
+
282
+ #### Recommendation rules
283
+
284
+ 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.
285
+
286
+ 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.
287
+ 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.
288
+ 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.
289
+ 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.
290
+
291
+ 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.
292
+
293
+ 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.
294
+
295
+ 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.
296
+
297
+ #### Marker strengths
298
+
299
+ 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.
300
+
301
+ Complexity levels classify individual findings, but the recommendation applies to the collection.
302
+
303
+ 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.
304
+
305
+ ### Blocked-step sub-block
306
+
307
+ 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:
308
+
309
+ ```
310
+ {step} was blocked: {blocker}.
311
+
312
+ 1. 🔓 ■■■ {Action that supplies the resource, e.g. run `! {login command}`}, then re-run {step}
313
+ 2. ⏭️ ■□□ Accept the review without {step}
314
+ ```
315
+
316
+ ### Combined output format
317
+
318
+ 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:
319
+
320
+ ```
321
+ Next steps:
322
+
323
+ **A1: Deviations from ticket**
324
+
325
+ Proposed edit to the acceptance criteria:
326
+ - Drop: A `--strict` flag gates the new validation
327
+
328
+ 1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
329
+ 2. ⏭️ ■□□ Leave as-is
330
+
331
+ **A2: Source divergence**
332
+
333
+ Proposed edit to the PR description:
334
+ - D2: "Unknown directives are warned on" → "Unknown directives fail the run"
335
+
336
+ 1. 📝 ■■□ Update PR description
337
+ 2. ⏭️ ■□□ Leave as-is
338
+
339
+ **A3: Actionable findings**
340
+
341
+ Proposed edits to the source:
342
+
343
+ **F1: source.** Fail on an unknown directive in `directives.ts:52`, replacing the warning that the loop currently emits.
344
+
345
+ **S1: test code.** Add the unknown-directive case to `directives.test.ts`, asserting the failure.
346
+
347
+ 1. 📋 ■■□ Post findings on the PR
348
+ 2. 🚀 ■□□ Implement directly and commit
349
+ 3. 🎫 ■□□ Create a follow-up ticket
350
+ ```
@@ -0,0 +1,85 @@
1
+ ## Option format
2
+
3
+ **Confirm that the menu is needed before rendering it.** Mark the options first, check the leader as "Check the leader before rendering" below states, then read the markers: Render the menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class below. Decide every other field: State the decision in one line with its reason, record it, and proceed. Decide an all-■□□ field too. An unmarked list is a pure-preference call, and a preference is in the gated class. The rejected alternative belongs in a clause ("X rather than Y, because Z"), never as a numbered option awaiting selection.
4
+
5
+ A determination that has one right answer under a governing document, such as a change's work type under the work-type test, is not a fork. Resolve doubt about which answer the test yields by applying the test and picking: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact. The developer holds less of the evidence than the agent, so handing the doubt back produces a worse-informed answer.
6
+
7
+ The gated class is closed. Ask about these decisions whatever the markers say:
8
+
9
+ - the shape of a public API or a contract
10
+ - remote shared state: a ticket edit, a push, a merge, the creation of a branch or a ticket
11
+ - data loss, or any action that cannot be undone
12
+ - spend or budget
13
+ - a preference for which you do not hold any evidence
14
+
15
+ Decide everything else yourself by default. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it. A templated next-steps menu is in the class, because what to do next is a preference about the developer's time, for which you do not hold any evidence. Verification is never in the gated class: Run a check that a command, a test, or a browser could settle.
16
+
17
+ **Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it ⏳ as "Record what you did not ask" states, and ask at the checkpoint; revise if overruled. In a skill without a phase structure, treat the skill's own approval gate, or the end of its work, as the checkpoint.
18
+
19
+ **Batch, never stream.** Collect the asks that survive the gate into one review at the checkpoint, not one per turn.
20
+
21
+ **Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason; when the work does not have a plan, write it into the turn's summary. Always record: A silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with ⏳, wherever you state it: in the record, and in a turn's narrative, such as a checkpoint summary or a list of decisions. The marker lets the developer find what they may overrule without reading every line. Drop it once the developer approves the checkpoint at which the decision was presented.
22
+
23
+ **Never rank the options by your own elapsed time, round trips, or effort.** You measure these costs yourself, and that measure counts the user's context switch and review cycles as nothing. Measuring one does not make the call yours, and a more accurate measurement still cannot rank the options.
24
+
25
+ Ordering follows from the gate. When the order changes the code or the total effort -- upstream before downstream, a refactor before the feature that would otherwise be written twice -- recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved. When the outcomes are identical and only the timing differs, such as when queued work is picked up, present the cost, render the options unmarked, and put the choice at the checkpoint.
26
+
27
+ Asking is not neutral. It costs the developer a context switch, and it idles the session until the answer arrives. A wrong-but-stated recommendation costs them a word to correct; a decision handed back costs them an evaluation and costs the session the wait.
28
+
29
+ Render every option-style question in this form: any numbered list of 2 or more choices with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions. Reserve `👍🏼👎🏼` for confirmation prompts, in which a single action has been proposed and "no" means "let's adjust or discuss" rather than a concrete alternative.
30
+
31
+ **Number every option**: `1.`, `2.`, `3.` The number is how the user selects. Never render the options as bullets or bare prose.
32
+
33
+ **Mark every option with a strength marker.** The recommended option is the one with the strongest marker. Do not write a separate "I recommend option N" sentence, and a recommendation that does not match the strongest marker is a defect.
34
+
35
+ | Marker | Label | When to use |
36
+ | ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
37
+ | ■■■ | strongly recommended | One option is clearly better on the criteria governing the decision, and your ranking does not turn on a preference that only the user holds. |
38
+ | ■■□ | recommended | Your lean. Default level when you have a preference. |
39
+ | ■□□ | weakly recommended | A slight edge; mostly preference. |
40
+ | □□□ | not recommended | Clear drawbacks; included for completeness or to rule out explicitly. |
41
+
42
+ Marking is all-or-none: Once any option has a marker, give every option one. Without a preference (a pure taste call), omit markers from every option and don't explain the omission; the absence is the signal. Mark at the strength that you actually hold: A marker that reads the same whatever the analysis found does not convey any information, and the reader must do all the work of telling a real choice from a formality. Render markers as plain text, never inside backticks; backticks shrink the glyphs and hurt readability.
43
+
44
+ **Format each option** as marker, then title, then a colon. Make each pro (`➕`) and con (`➖`) a nested list item beneath its option, without terminal punctuation. Apply this even when an option has only one pro or con. Lead with the strongest argument.
45
+
46
+ Make every line subordinate to an option (a pro, a con, invocation guidance) a nested list item, never a whitespace-indented continuation. Indentation by spaces, ASCII or non-breaking alike, does not survive terminal rendering: The lines collapse to the left margin, and the reader cannot tell which reason belongs to which option. Markdown structure survives; whitespace does not.
47
+
48
+ Stop nesting at one level: Never put a sub-option in an option or a sub-pro in a pro. Terminal rendering stops being reliable at deeper nesting, so this contract is written never to need it.
49
+
50
+ **Write only bullets that are real.** Bullets report the weight of each option, not a balance between the options: When the options differ in quality, an uneven menu is the accurate one, and a menu that looks balanced misreports the analysis. A `➕` or `➖` asserts that the reader should weigh it, and bullets render at equal visual weight. A manufactured one reads exactly like a load-bearing one, and it takes a round trip to discover that it was empty. Seven tests:
51
+
52
+ - **Falsifiability.** A `➖` must be false for at least one other option on the menu, and a `➕` likewise. Anything that would still be true if this were the only option is a mechanic of carrying it out rather than a tradeoff; it belongs on the invocation line or nowhere.
53
+ - **Decision weight.** Would a reader who believed this bullet choose differently? Bookkeeping, mechanically-implied, and trivially-reversible consequences (a doc line to update, a criterion to reword, a rename to propagate) are real, specific, and decision-irrelevant. Restatements of an option's inherent properties ("longer wall time", "structured review pass", "ships faster") are one instance of the same failure.
54
+ - **Session context.** Cut a bullet that cites the conversation, what the session holds, or what is "already in context". Every handoff goes through a saved artifact, so session context does not distinguish one option from another, and a bullet that rests on it tells the reader that the artifact is incomplete. When the bullet is true, the artifact has a gap: Add the fact to the artifact rather than citing the session.
55
+ - **Consequence.** State in a `➖` what breaks or what it costs, and for whom, concretely enough that the reader can weigh it without investigating. Cut a con that cannot be stated that way.
56
+ - **The qualifier tell.** A bullet undercut by its own qualifier ("negligible", "inert", "harmless") is filler. The only repair is to cut the bullet: Deleting the qualifier leaves the same minor con, now looking weighty.
57
+ - **One tradeoff, stated once.** When one option's `➕` restates another option's `➖`, the two options are the sides of one tradeoff. State it once, in a line above the list, rather than as bullets split between the options, which the reader counts as separate reasons.
58
+ - **Check before you hedge.** If a cheap check would settle whether a con is real, run the check. Presenting the uncertainty as a bullet transfers the check to the user.
59
+
60
+ Asymmetry is a report, not a defect. Give an option that has three real pros but lacks a real con its three pros, and do not give it a con. Never add a bullet to fill a slot, reach parity between options, or avoid looking one-sided; when the honest cost is hard to find, that difficulty is itself evidence the option is strong. When every option lacks a real bullet, omit them all and let the markers alone convey the recommendation. Do not add tiebreaker text for equal-strength options; the developer picks the number.
61
+
62
+ Keep on a `□□□` option the `➖` that explains why you ruled it out. Under the falsifiability test that bullet is real by construction, and without it the reader is left with a veto that they cannot check.
63
+
64
+ **Check the leader before rendering.** Once you have drafted the bullets, and before you read the markers against the gate, run this check. It applies to a gated decision as fully as to any other: The menu renders whatever the markers say, and the marker tells the developer how much deliberation the ask needs.
65
+
66
+ 1. For each alternative, look for a cost that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand. When you find one, state it as the alternative's `➖`.
67
+ 2. For each `➖` on the strongest-marked option, name the reader who would choose differently because of it. Cut the bullet if there is none.
68
+ 3. Re-mark the options. When every alternative has a disqualifying `➖`, mark the leader ■■■. The observed bias is a marker set too weak, not one set too strong.
69
+ 4. Re-apply the gate. Outside the gated class, a leader marked above every other option means that the field is decided: State the decision in one line, and do not render a menu. Inside the class, render the menu with the leader's marker as the check set it.
70
+
71
+ **Identify each question** when a single response contains 2 or more option-style questions: Prefix them `Q1`, `Q2`, and so on, so that the user can reference answers unambiguously. When the underlying data already has stable identifiers (plan-review findings such as `C1` or `X2`), use those in place of `Q1`/`Q2`. For a single option-style question, omit the identifier. Inside an [action-items block](../_data/action-items.md), identifiers are mandatory whenever the block contains more than one item (or more than one independently-numbered list), and they distinguish actions (`A`) from questions (`Q`).
72
+
73
+ Example:
74
+
75
+ ```
76
+ How should the exported `loadConfig` report a missing file?
77
+ 1. ■■■ Return `undefined`:
78
+ - ➕ matches the package's three other loaders, so callers keep one pattern
79
+ 2. ■□□ Throw `ConfigNotFoundError`:
80
+ - ➖ each of the 14 call sites needs a new `try`/`catch` to keep its current behavior
81
+ 3. □□□ Return an empty config:
82
+ - ➖ a caller cannot tell a missing file from an empty one, so a mistyped path silently disables every setting
83
+ ```
84
+
85
+ The decision is the shape of a public API, so the gate renders the menu although one option leads. The leader does not have a `➖` because none survived the check.
@@ -0,0 +1,97 @@
1
+ **Detail threshold:** Include enough detail that a competent engineer, reading only the plan and ticket, would make the same architectural decisions you would. Omit details that they'd arrive at independently. Compose at this altitude from the outset ([concision principle](../_data/concision.md)); a plan drafted tight beats a fuller one pared down.
2
+
3
+ ```markdown
4
+ # Implementation plan: {Title}
5
+
6
+ ## Context
7
+
8
+ {Brief context linking this plan to the ticket}
9
+
10
+ ## Approach
11
+
12
+ {High-level strategy, 2-3 sentences}
13
+
14
+ ## Decisions taken
15
+
16
+ - {⏳ while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason}
17
+
18
+ ## Tasks
19
+
20
+ ### Task 1: {Name}
21
+
22
+ **Files:**
23
+
24
+ - Create: `path/to/new-file.ts`
25
+ - Modify: `path/to/existing.ts`
26
+ - Test: `path/to/test.ts`
27
+
28
+ **What:** {What this task accomplishes and why}
29
+
30
+ **Key decisions:**
31
+
32
+ - {Design choice that the coder needs to know}
33
+
34
+ **Acceptance criteria:**
35
+
36
+ - {How to know this task is done}
37
+
38
+ ### Task 2: {Name}
39
+
40
+ ...
41
+
42
+ ## Risks
43
+
44
+ {Known risks, unknowns, or areas where the coder may need to adapt}
45
+
46
+ ## Verification
47
+
48
+ {The checks that the agent runs to verify the whole plan is complete: quality gates, integration checks}
49
+ ```
50
+
51
+ `## Dependencies` (external dependencies or blockers) is the one optional section: Insert it between `## Risks` and `## Verification` only when the plan has external blockers, and omit it otherwise.
52
+
53
+ **Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
54
+
55
+ **Per-task documentation criterion:** When a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include updating documentation, help text, and usage examples, including removal of references to anything that no longer exists.
56
+
57
+ **Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
58
+
59
+ **Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
60
+
61
+ **Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge.
62
+
63
+ **Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
64
+
65
+ **Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that the tests do not assert. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
66
+
67
+ Before (a verification task handed to the developer):
68
+
69
+ > **What:** After the branch is pushed and Vercel builds the preview, the owner exercises `/lab/book-row` by keyboard and on a touch device against the checklist in Task 9. Defects found there are fixed on the branch. Once the owner confirms, delete the lab route in its own commit.
70
+ >
71
+ > **Acceptance criteria:** The owner has confirmed the controls on the preview.
72
+
73
+ After (the agent runs the check, and the residue is the one part that emulation cannot show):
74
+
75
+ > **What:** Drive `/lab/book-row` through the debug browser with keyboard input and touch emulation against the checklist in Task 9, fix what the check finds on the branch, then delete the lab route in its own commit.
76
+ >
77
+ > **Residue:** How the rating control feels on a physical phone: emulation does not report touch feel.
78
+ >
79
+ > **Acceptance criteria:** Every item of the checklist passes in the debug browser, and the lab route is gone.
80
+
81
+ #### What belongs in the plan
82
+
83
+ - Task decomposition with ordering and dependencies
84
+ - File-level decisions (create, modify, test)
85
+ - Key decisions that state design choices
86
+ - The decisions ledger: every call that the agent took in place of an ask, its reason, and whether it is provisional
87
+ - Acceptance criteria per task
88
+ - Risks and unknowns
89
+
90
+ Code belongs in the plan only when it records a decision that isn't obvious from prose: for example, an interface that constrains how components interact, or an algorithm whose shape isn't implied by the description.
91
+
92
+ #### What does NOT belong in the plan
93
+
94
+ - Commit messages
95
+ - Shell commands (test runners, build commands)
96
+ - TDD step-by-step ceremony
97
+ - Implementation code for straightforward logic
@@ -0,0 +1,5 @@
1
+ **Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}** (ready now)` or `(after {blocker_ref} merges)`, followed by a fenced block that contains only the text to paste:
2
+
3
+ - The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, and omitting the plan when the ticket does not have one.
4
+ - The scope notes that the session needs and that the artifacts do not state, such as "only tasks 2 and 3" or "merge only after `live` contains #N".
5
+ - The ticket's blockers, by reference.
@@ -0,0 +1,5 @@
1
+ Selecting Split is the developer's consent to the split at the seam that its `➕` line names. Nothing is created before that selection, and the bodies get one confirmation before anything is created.
2
+
3
+ **Compose.** Compose a ticket body per piece (problem, context, acceptance criteria) from the piece's work and the ticket's criteria. Compose the originating ticket's new body as well: With two pieces, rewrite it to the first piece, so that the originating ticket and one new ticket cover the two pieces; with three or more, make it an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. When the work does not have a governing ticket, every piece is a new ticket and there is nothing to rewrite.
4
+
5
+ **Confirm once.** Show every body, every relationship, and everything that the steps below create or change in one block, and confirm once. This single confirmation stands in for the per-ticket confirmation that `{skill:create-ticket}` would otherwise raise for each piece.
@@ -0,0 +1,3 @@
1
+ **Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. For a piece that depends on an earlier piece being merged first, pass `--blocked-by` naming that piece's reference, which exists by then.
2
+
3
+ **Rewrite the originating ticket.** Write the originating ticket's new body per the platform-specific write in [ticket source resolution](../_data/ticket-source-resolution.md#platform-specific-write).
@@ -0,0 +1,33 @@
1
+ **Sweep the artifacts for anything the conversation settled that they do not record.** After the plan is approved or drafted, before the artifacts are saved, re-read them against the conversation and apply the handoff test: Could a competent developer, reading only the ticket and plan without access to this conversation, achieve the intended result and make the same decisions? Whatever fails that test is a gap.
2
+
3
+ This sweep is the completeness counterpart of the [concision](../_data/concision.md) self-check: That one asks what can be cut, this one asks what was never captured. They are a deliberate pair, not competing pressures. An artifact that drops a settled decision isn't concise, it's incomplete.
4
+
5
+ The handoff test has two halves, and each needs a different reader. The sweep checks that each settled decision is recorded, and it runs in the main session because only the session knows what the conversation settled. The handoff pass checks that the artifacts stand alone, and it runs in a subagent because only a reader without memory of the session can see a gap: The writer fills each one from memory without noticing the fill.
6
+
7
+ **Sweep for:**
8
+
9
+ - Settled decisions, including the rejected alternatives.
10
+ - Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked ⏳ when it awaits this checkpoint.
11
+ - Constraints and scope boundaries on which the conversation agreed.
12
+ - Edge cases and success criteria raised in discussion but missing from the acceptance criteria.
13
+ - Tacit context of the form "the implementer might not realize X": What the conversation established as known and the artifacts leave the reader to rediscover.
14
+
15
+ **Place each gap by kind**, per the placement doctrine: Fold the change's subject and outcomes into the ticket and the mechanism into the plan. Where the gap came up in conversation does not decide where it goes. When the invocation does not produce a ticket artifact, fold a subject-level gap into the plan's context section.
16
+
17
+ **Classify the plan once the sweep's gaps are folded in.** Read the plan against the [complexity rubric](../_data/complexity-classification.md) inline, without dispatching `classify-complexity`; a spike plan is classified by its investigation steps. At level 1–2, skip the handoff pass: Report the skip in one line that names the level, and proceed to save. At level 3–4, run the pass. The rubric's tie rule applies, so a plan on the border gets the pass.
18
+
19
+ **Run the handoff pass at level 3–4.** Write the ticket and the plan as drafts to a scratch directory created with `mktemp -d "${TMPDIR:-/tmp}/handoff.XXXXXX"`, using the absolute path that the call prints; they are saved to the artifact directory only once, after this pass. When the invocation does not produce a ticket artifact, `ticket-source` is the ticket's URL or reference. Dispatch the `{subagent:handoff-reviewer}` subagent via the {tool:Task} tool with this block:
20
+
21
+ ```dispatch
22
+ ticket-source: {ticket draft path, or ticket URL or reference}
23
+ plan: {plan draft path}
24
+ root: {repository root}
25
+ ```
26
+
27
+ The block contains scalars only, and only these keys. Do not compose any prose into it: A sentence written here gives the reader the session's knowledge, and the pass is worth nothing once the reader shares what the writer knows.
28
+
29
+ **A reply that lacks the `Phase: handoff-review` return block is a reviewer stopped by its turn limit.** Resume that reviewer once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. The resumption continues the same dispatch, so it is not the second dispatch that the pass forbids. When the harness cannot resume a subagent, or the resumed reviewer still does not return a report, do not dispatch again: Save the drafts without the pass, and report that the handoff pass did not return a report, even when the sweep found nothing.
30
+
31
+ **Fold in each item that the reader returns**, into the drafts: Place a missing fact by kind, per the paragraph above, and correct a claim that the repository contradicts. A question that the conversation settled is answered in the artifact. A question that the conversation never settled is asked of the user before saving, and the answer is folded in like any other item. Do not dispatch again after the fold-in: The pass runs once.
32
+
33
+ **Report and proceed.** When the sweep or the handoff pass finds gaps, fold them in, report the amendments as a brief list, then save the drafts as the artifacts. The report is informational: The amendments record what the conversation already settled or what the repository shows, so they do not open an approval gate, and the only ask that the sweep opens is a reader question that the conversation never settled. When neither pass finds anything, save silently; a clean sweep is not worth a line. The skip line is the one exception: A pass that was not run is a decision that the user should see.