codeassembly-guidance 0.1.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -34,7 +34,7 @@ Do NOT generate the implementation plan until the ticket has been approved. This
34
34
 
35
35
  ### Phase 1: Resolve task source and assess relevancy
36
36
 
37
- 1. **Resolve the task source** using the [ticket source resolution](../_data/ticket-source-resolution.md) table. Request the `updatedAt` field for use in the relevancy check. Store the resolved metadata for use in the relevancy check and Phase 5's optional remote update. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument.
37
+ 1. **Resolve the task source** using the [ticket source resolution](../_data/ticket-source-resolution.md) table. Request the `updatedAt` field for use in the relevancy check. Store the resolved metadata for use in the relevancy check and Phase 5's optional remote update. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Then report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), whether or not the relevancy check runs, and continue: A blocker does not stop design. Then check the branch per [branch currency](../_data/branch-currency.md) before exploring the codebase, reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names.
38
38
 
39
39
  2. **Assess relevancy**: Determine whether the ticket may be stale and, if so, verify it is still relevant.
40
40
 
@@ -64,11 +64,11 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
64
64
 
65
65
  ### Phase 2: Understand the task
66
66
 
67
- 1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase.
67
+ 1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase. Read the project's declared stage from the manifest's `project_maturity`, `project_sensitivity`, and `project_audience` fields, which `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits.
68
68
 
69
69
  2. **Evaluate the ticket on its merits**: Apply the criteria in [ticket evaluation](../_data/ticket-evaluation.md). When evaluation reveals a divergence from the ticket as written, recommend a disposition, build the design on it, and present the divergence at the ticket checkpoint; raise it earlier only when the design cannot proceed without the answer. Divergence includes scope that should grow: By default, fold work that the problem requires into this change rather than into a follow-up (see [scope-and-deferral](../_data/scope-and-deferral.md)).
70
70
 
71
- 3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate where you can, and record the answer as a decision taken, with its reason. Carry the asks that survive the gate forward to the ticket checkpoint in Phase 3; ask earlier only where the design cannot proceed without the answer, and prefer multiple choice when you do.
71
+ 3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate when you can, and record the answer as a decision taken, with its reason. Defer the asks that survive the gate to the ticket checkpoint in Phase 3; ask earlier only when the design cannot proceed without the answer, and prefer multiple choice when you do. Treat the declared stage as the premise of every security, availability, and infrastructure question, per [project stage](../_data/project-stage.md). Treat a step that a person must run on each machine as a defect of the design, per [who applies the change](../_data/design-priorities.md#who-applies-the-change): Prefer a design that the agent applies and verifies itself, and when the step stays, the ticket's `## Proposed solution` names the rung of that ladder that shapes it. Ask for each undeclared stage value: in this step when the design has such a question, since the answer decides it, and otherwise at the ticket checkpoint. The ticket's `## Context` states each premise that decided such a question, and the plan includes a task that declares each answered value.
72
72
  - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
73
73
 
74
74
  **Important:** Do not use `{tool:AskUserQuestion}` or any interactive selector (pop-up, arrow-key, structured-choice) for multiple-choice questions. Ask the question as plain text in the message body, with options as a numbered list.
@@ -77,14 +77,14 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
77
77
 
78
78
  ### Phase 3: Converge on a design and refine the ticket
79
79
 
80
- 1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
80
+ 1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), in which a design that needs a person to act on each machine ranks below one that the agent applies itself, and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
81
81
  - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
82
82
 
83
83
  2. **Draft the ticket on the recommended approach, provisionally.** The design is the draft ticket: Its `## Proposed solution` states the design, scaled to complexity, and a fork that survived the gate is written on its recommended branch until the checkpoint settles it.
84
84
 
85
85
  **Spike mode.** If this is a spike, use the spike ticket template in [spike conventions](../_data/spike-conventions.md) in place of the skeleton below; everything else in this phase is unchanged.
86
86
 
87
- If the source ticket already covers problem, context, proposed solution, and acceptance criteria adequately and the design did not surface any changes, propose adopting it as-is at the checkpoint. Skip the rewrite. Only add or revise sections for which the design revealed gaps or shifts in understanding.
87
+ If the source ticket already covers problem, context, proposed solution, and acceptance criteria adequately and the design did not reveal any changes, propose adopting it as-is at the checkpoint. Skip the rewrite. Only add or revise sections for which the design revealed gaps or shifts in understanding.
88
88
 
89
89
  When the ticket needs work, produce or update it to state the proposed approach:
90
90
 
@@ -94,20 +94,18 @@ When the ticket needs work, produce or update it to state the proposed approach:
94
94
  <!-- include: ../_partials/ticket-skeleton.md / -->
95
95
  ```
96
96
 
97
- <!-- include: ../_partials/ticket-skeleton-tiers.md / -->
98
-
99
- <!-- include: ../_partials/ticket-concision.md / -->
100
-
101
- <!-- include: ../../_partials/prose-line-breaks.md / -->
102
-
103
- <!-- include: ../_partials/ticket-placement.md / -->
97
+ <!-- include: ../_partials/ticket-composition.md / -->
104
98
 
105
99
  Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ticket omits is recorded there, not dropped.
106
100
 
107
101
  <!-- include: ../_partials/ticket-criteria-conventions.md / -->
108
102
 
103
+ <!-- include: ../../_partials/prose-line-breaks.md / -->
104
+
109
105
  **Present the ticket as the first checkpoint**, in one turn: the draft ticket, the decisions taken so far with their reasons, and the forks that survived the gate as option-style questions. Revise until approved. Approval of the ticket is approval of the design.
110
106
 
107
+ **When the checkpoint splits the ticket**, the session continues with one piece: With two pieces, it plans the originating ticket, which keeps the first piece; with an umbrella, it plans the first child, whose work belongs in that child's own worktree. Phase 5 then ends with the launch prompts that [Splitting the ticket](#splitting-the-ticket) defines, with each ticket's entry point chosen by that section's **Report.** rule, and the planned piece's prompt names its saved plan. With two pieces, the next-steps menu stays for the originating ticket, and that ticket's prompt heading adds that this session continues with it at the menu. With an umbrella, the launch prompts replace the `Next action` menu, so that nothing offers to implement a child in the current worktree.
108
+
111
109
  ### Phase 4: Generate implementation plan
112
110
 
113
111
  <HARD-GATE>
@@ -134,12 +132,13 @@ Then save both artifacts:
134
132
  - Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout (auto-generate ticket ID as `{YYYYMMDD}-{4 random hex}` if none found)
135
133
  - Target: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
136
134
  - `mkdir -p` the target directory
135
+ - After an umbrella split, save the plan in the planned child's directory instead, `tickets/{child_id}/`, beside the ticket artifact that `{skill:create-ticket}` saved there
137
136
 
138
137
  2. Resolve frontmatter fields for both artifacts. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
139
138
 
140
- Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill design-and-plan --interactive true` via Bash. Prepend the output verbatim to each artifact body.
139
+ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill design-and-plan --interactive true` via Bash. Prepend the output verbatim to each artifact body. For a plan saved in a child's directory, append `--override ticket_id="{child_id}" --override ticket_ref="{child_ref}"` to the plan's invocation, so that its frontmatter names the child rather than the current branch's ticket.
141
140
 
142
- Append `--extra copies_remote=true` to the ticket artifact's invocation, and to that one alone, when the source was a remote ticket and the refined ticket does not differ from its body: the same condition under which the remote-issue offer below is not made. This records that the saved body is a copy of the ticket of record; see [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). When the offer is made, omit it on both outcomes: On consent, the remote is written after the artifact is saved, so recency already prefers the remote, and a refusal leaves the snapshot genuinely newer.
141
+ Append `--extra copies_remote=true` to the ticket artifact's invocation, and to that one alone, when the source was a remote ticket and the refined ticket does not differ from its body: the same condition under which the remote-issue offer below is not made. This records that the saved body is a copy of the ticket of record; see [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). When the offer is made, omit it on both outcomes: On consent, the remote is written after the artifact is saved, so the remote is already the more recent copy, and a refusal leaves the snapshot genuinely newer.
143
142
 
144
143
  3. Save both artifacts following `save-artifact` naming conventions:
145
144
  - Ticket: `{YYYYMMDD-HHMMSSZ}_{slug}_ticket.md`
@@ -147,7 +146,7 @@ Then save both artifacts:
147
146
 
148
147
  Prepend the resolved frontmatter to each artifact content before writing.
149
148
 
150
- 4. Report paths and present next steps.
149
+ 4. Report paths and present next steps. After a split at the ticket checkpoint, end with the launch prompts, per the checkpoint-split rule in Phase 3.
151
150
 
152
151
  ```
153
152
  Design and plan complete:
@@ -168,14 +167,14 @@ Next steps:
168
167
 
169
168
  **A2: Next action**
170
169
  1. 🧠 ■□□ Refine plan:
171
- - Clear context and use the `refine-plan` skill with plan: {plan_path}, ticket: {ticket_path}
170
+ - Clear context, then {skill?:refine-plan} with plan: {plan_path}, ticket: {ticket_path}
172
171
  ...
173
172
  ```
174
173
 
175
174
  On consent, write the refined ticket per [platform-specific write](../_data/ticket-source-resolution.md#platform-specific-write). The refined ticket is the whole body approved by the user, so it replaces the remote body outright.
176
175
 
177
176
  <HARD-GATE>
178
- Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The `**A1: Remote issue**` and `**A2: Next action**` sub-block labels above are the sanctioned wrapper when the remote offer is shown; they do not add or reorder any option. The plan was developed interactively, with the ticket and the plan each approved at a checkpoint; use this as recommendation context. Include both `{ticket_path}` and `{plan_path}` in each skill-invoking option line.
177
+ Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The `**A1: Remote issue**` and `**A2: Next action**` sub-block labels above are the sanctioned wrapper when the remote offer is shown; they do not add or reorder any option. After an umbrella split at the ticket checkpoint, the launch prompts take the place of the `Next action` menu, per the checkpoint-split rule in Phase 3. The plan was developed interactively, with the ticket and the plan each approved at a checkpoint; use this as recommendation context. Include both `{ticket_path}` and `{plan_path}` in each skill-invoking option line.
179
178
  </HARD-GATE>
180
179
 
181
180
  **STOP.** Beyond the remote-issue update above, do not invoke any skill. Do not begin implementation.
@@ -187,7 +186,7 @@ Follow the options, output format, and recommendation rules in [next-steps optio
187
186
  - **YAGNI ruthlessly**: Cut unnecessary scope from designs
188
187
  - **Scale to complexity**: A simple task gets a short design and a short plan
189
188
  - **Plan for engineers, not transcribers**: Communicate decisions, not ceremony
190
- - **The ticket is the contract**: If facts on the ground differ from the plan, the ticket's acceptance criteria are the source of truth
189
+ - **The ticket is the contract**: If the facts found during implementation differ from the plan, the ticket's acceptance criteria are the source of truth
191
190
 
192
191
  <!-- include: ../_partials/next-steps-after-plan.md / -->
193
192
 
@@ -6,7 +6,7 @@ user-invocable: true
6
6
 
7
7
  # Groom backlog
8
8
 
9
- Sweep a repository's open GitHub issues for tickets whose motivation other work has met, whose premise the codebase has outgrown, or whose fate hinges on another ticket. A bundled helper does the mechanical half: It fetches and selects the tickets, detects which are in progress, finds candidate cross-references, keeps the ledger, classifies each assessment under the policy, proposes an action for each escalation, and renders the digests, the drafted edits, and the comments. You do the rest: one `{subagent:ticket-assessor}` subagent per ticket, one confirmation per digest page, and every write to GitHub.
9
+ Sweep a repository's open GitHub issues for tickets whose motivation other work has met, whose premise the codebase has outgrown, or whose outcome depends on another ticket. A bundled helper does the mechanical half: It fetches and selects the tickets, detects which are in progress, finds candidate cross-references, keeps the ledger, classifies each assessment under the policy, proposes an action for each escalation, and renders the digests, the drafted edits, and the comments. You do the rest: one `{subagent:ticket-assessor}` subagent per ticket, one confirmation per digest page, and every write to GitHub.
10
10
 
11
11
  The sweep decides by default. Every selected ticket is assessed, and each digest page asks one question: whether to apply the actions that it proposes.
12
12
 
@@ -64,7 +64,7 @@ The helper applies the umbrella case in `ingest` and in `comment`.
64
64
  | A `keep` | `keep` |
65
65
  | Anything else, including a close below high confidence | `leave` |
66
66
 
67
- `leave` writes nothing; the entry still shows the recommendation, so that the user can name it. The assessor drafts the edit behind every `update`, `revise`, and `split`: the replacement sections of the body and, for a split, the child tickets. The digest shows each draft under its entry.
67
+ `leave` writes nothing; the entry still shows the recommendation, so that the user can name it. The assessor drafts the edit behind every `update`, `revise`, and `split`: the replacement sections of the body, a replacement title when the current one no longer describes the ticket, and, for a split, the child tickets. The digest shows each draft under its entry.
68
68
 
69
69
  **What the digest groups.** A hub is an open ticket on whose outcome two or more escalations of one digest page depend; the page shows it once, above its dependents, so that the user decides it first. Overlapping open tickets are merged into one group with the assessors' recommended survivor. Merging tickets stays the user's action, through the ticket skills.
70
70
 
@@ -74,7 +74,7 @@ The helper applies the umbrella case in `ingest` and in `comment`.
74
74
 
75
75
  ## Process
76
76
 
77
- Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`, except where a step below says otherwise. Invoke the helper as:
77
+ Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`, except when a step below says otherwise. Invoke the helper as:
78
78
 
79
79
  ```bash
80
80
  node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs {command} --run {run} {flags}
@@ -159,7 +159,7 @@ Run `digest` once, and walk the pages of that one result: A `leave` stays undeci
159
159
 
160
160
  The result contains the run's open escalations, `total`, and `pages`: each escalation whose latest assessment escalated and that does not have a decision recorded after it. Each page's `entries` give each entry's `proposed` action, a `decision` with an optional `supersededBy`. Present one page at a time, verbatim from its `markdown`, and close the turn with an action-items block that asks one question: whether to apply the page's proposed actions. The user answers `yes` to apply them all, or names the entries to change, in the decision vocabulary (`keep`, `update`, `revise`, `split`, `close-complete`, `close-superseded` optionally by `#N`, `close-not-planned`, or `leave`), with an optional reason: `yes, except 3 keep, 5 close-superseded by #40`. Naming a `leave` entry applies what it names. A `no` without changes applies nothing on the page.
161
161
 
162
- Under `--dry-run`, present every page, take no decisions, and go to the summary.
162
+ Under `--dry-run`, present every page, do not take any decisions, and go to the summary.
163
163
 
164
164
  ### 7. Apply the confirmed actions and summarize
165
165
 
@@ -196,7 +196,7 @@ Every action on a ticket follows one order: apply the drafted edit when the deci
196
196
  gh issue edit {child number} --parent {number}
197
197
  ```
198
198
 
199
- Then replace the ticket's body:
199
+ Then replace the ticket's body, adding `--title "{title}"` when the result's `title` is not `null`:
200
200
 
201
201
  ```bash
202
202
  body_path="{body path}"
@@ -204,6 +204,8 @@ Every action on a ticket follows one order: apply the drafted edit when the deci
204
204
  gh issue edit {number} --body-file "$body_path"
205
205
  ```
206
206
 
207
+ Edit a ticket only through this step: A title or label edited after the decision is recorded makes the ticket look changed, and the next `collect` selects it again.
208
+
207
209
  2. **Render the comment** to a file:
208
210
 
209
211
  ```bash
@@ -214,7 +216,7 @@ Every action on a ticket follows one order: apply the drafted edit when the deci
214
216
 
215
217
  Pass `--reason` when the user stated one, `--superseded-by` when the decision names the superseding ticket, and `--children` with the created children's numbers for a split. `--decision` is one of `keep`, `close-complete`, `close-superseded`, `close-not-planned`, `update`, `revise`, and `split`.
216
218
 
217
- The result's `post` states whether the comment is posted. When it is `false`, the helper writes no body: Skip to step 5.
219
+ The result's `post` states whether the comment is posted. When it is `false`, the helper does not write a body: Skip to step 5.
218
220
 
219
221
  3. **Post it**, per [gh body file](#gh-body-file):
220
222