codeassembly-guidance 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,194 @@
1
+ ---
2
+ name: design-and-plan
3
+ description: Interactive design exploration followed by ticket refinement and implementation planning
4
+ user-invocable: true
5
+ dependencies:
6
+ skills:
7
+ - save-artifact
8
+ - testing-conventions
9
+ ---
10
+
11
+ # Design and plan
12
+
13
+ Interactive design exploration followed by ticket refinement and implementation planning. Produces two artifacts: a refined ticket and an implementation plan.
14
+
15
+ **Announce at start:** "Using design-and-plan to explore requirements and produce a ticket + implementation plan."
16
+
17
+ ## Arguments
18
+
19
+ - Task source (required): Issue URL, shorthand reference (`#99`, `issue 99`), file path, or description of what to build
20
+ - `--check-staleness` (optional): Always run the relevancy check, regardless of the heuristic
21
+ - `--skip-staleness` (optional): Never run the relevancy check, regardless of the heuristic
22
+
23
+ ## Overview
24
+
25
+ Turn a task into a well-defined ticket and actionable implementation plan through collaborative dialogue. Explore requirements interactively, converge on a design, and produce two artifacts that together give a competent coder everything they need.
26
+
27
+ <HARD-GATE>
28
+ Do NOT generate the implementation plan until the ticket has been approved. This applies regardless of perceived simplicity.
29
+ </HARD-GATE>
30
+
31
+ <!-- guidance-hook: ticketing-preferences -->
32
+
33
+ ## Process
34
+
35
+ ### Phase 1: Resolve task source and assess relevancy
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.
38
+
39
+ 2. **Assess relevancy**: Determine whether the ticket may be stale and, if so, verify it is still relevant.
40
+
41
+ **Override arguments take precedence:**
42
+
43
+ - If `--check-staleness` was passed: Run the relevancy check immediately, without prompting the user.
44
+ - If `--skip-staleness` was passed: Skip the relevancy check entirely.
45
+ - If neither was passed: Evaluate the heuristic below.
46
+
47
+ **Heuristic** (evaluated only when the task source is a remote ticket with a last-updated date):
48
+
49
+ 1. Retrieve the ticket's last-updated date from the resolved metadata (e.g., GitHub's `updatedAt` field).
50
+ 2. Count commits since that date: `git rev-list --count --after="{last-updated date}" HEAD`
51
+ 3. If the ticket was updated within the last 3 days _or_ fewer than 5 commits have been made since the last update, skip the relevancy check.
52
+ 4. Otherwise, prompt the user: "This ticket may be out of date ({N} commits since the last update on {date}). Would you like me to check for staleness and relevancy?" If the user declines, continue into Phase 2.
53
+
54
+ If the task source is plain text or a file (without remote metadata), skip the relevancy check unless `--check-staleness` was explicitly passed.
55
+
56
+ **The relevancy check** (when triggered by user approval or `--check-staleness`):
57
+
58
+ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mode `drift`.
59
+
60
+ **After the check**: Interpret the drift verdict:
61
+
62
+ - 🟢 `none`: Continue silently into Phase 2.
63
+ - 🟠 `partial` or 🔴 `severe`: Present the assessment findings to the user. Ask whether to proceed as-is, adjust the scope, or stop.
64
+
65
+ ### Phase 2: Understand the task
66
+
67
+ 1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase.
68
+
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
+
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.
72
+ - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
73
+
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.
75
+
76
+ <!-- include: ../_partials/action-items.md / -->
77
+
78
+ ### Phase 3: Converge on a design and refine the ticket
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.
81
+ - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
82
+
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
+
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
+
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.
88
+
89
+ When the ticket needs work, produce or update it to state the proposed approach:
90
+
91
+ ```markdown
92
+ # {Title}
93
+
94
+ <!-- include: ../_partials/ticket-skeleton.md / -->
95
+ ```
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 / -->
104
+
105
+ Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ticket omits is recorded there, not dropped.
106
+
107
+ <!-- include: ../_partials/ticket-criteria-conventions.md / -->
108
+
109
+ **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
+
111
+ ### Phase 4: Generate implementation plan
112
+
113
+ <HARD-GATE>
114
+ Do NOT start this phase until the ticket from Phase 3 has been explicitly approved.
115
+ </HARD-GATE>
116
+
117
+ Produce a plan that gives a competent coder everything they need, and enough context to adapt when the codebase doesn't match expectations.
118
+
119
+ > Phase 4 produces the same implementation plan as the standalone `plan` skill, drawn from one shared template. When a ticket is already good and only the plan is needed, run `plan` directly to skip the design phase.
120
+
121
+ **Spike mode.** If this is a spike, use the spike plan template in [spike conventions](../_data/spike-conventions.md) in place of the template below; everything else in this phase is unchanged.
122
+
123
+ <!-- include: ../_partials/plan-template.md / -->
124
+
125
+ Present the plan as the second checkpoint, with its `## Decisions taken` section and any ask that survived the gate since the ticket was approved. Revise until approved.
126
+
127
+ ### Phase 5: Sweep for completeness, save artifacts, and stop
128
+
129
+ <!-- include: ../_partials/ticket-and-plan-completeness.md / -->
130
+
131
+ Then save both artifacts:
132
+
133
+ 1. Resolve artifact directory using `save-artifact` conventions:
134
+ - 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
+ - Target: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
136
+ - `mkdir -p` the target directory
137
+
138
+ 2. Resolve frontmatter fields for both artifacts. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
139
+
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.
141
+
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.
143
+
144
+ 3. Save both artifacts following `save-artifact` naming conventions:
145
+ - Ticket: `{YYYYMMDD-HHMMSSZ}_{slug}_ticket.md`
146
+ - Plan: `{YYYYMMDD-HHMMSSZ}_{slug}_plan.md`
147
+
148
+ Prepend the resolved frontmatter to each artifact content before writing.
149
+
150
+ 4. Report paths and present next steps.
151
+
152
+ ```
153
+ Design and plan complete:
154
+ Ticket: {ticket_path}
155
+ Plan: {plan_path}
156
+ ```
157
+
158
+ **Remote issue update**: Offer to update the remote issue only when the source was a remote ticket (URL or shorthand reference) and the refined ticket differs from the remote body. Phase 3 may adopt a good source ticket unchanged and the sweep may find nothing to fold in; the remote is then already current; do not make the offer. This is a shared-state action; do not update without explicit consent, and never open a turn of its own for the ask.
159
+
160
+ Render the offer inside the next-steps block as its own labelled sub-block above the options, under the same `Next steps:` header. With two selects present, each shows its `A`/`Q` identifier as a bold prefix (`**A1: Remote issue**`, `**A2: Next action**`) and keeps its own 1-based option numbering, so the user answers `A1: 1, A2: 3`. The consent is independent of the single-select next-step choice, and the next-action options keep their order. Recommend the update: The offer appears only when the remote body is stale against the refined ticket. The recommended option's marker follows how stark that staleness is (■■■ when the refined ticket plainly supersedes the remote body, ■■□ when the delta is real but arguable), and Leave as-is takes ■□□.
161
+
162
+ ```
163
+ Next steps:
164
+
165
+ **A1: Remote issue**
166
+ 1. 📝 ■■□ Update {ticket_ref} with the refined ticket
167
+ 2. ⏭️ ■□□ Leave as-is
168
+
169
+ **A2: Next action**
170
+ 1. 🧠 ■□□ Refine plan:
171
+ - Clear context and use the `refine-plan` skill with plan: {plan_path}, ticket: {ticket_path}
172
+ ...
173
+ ```
174
+
175
+ 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
+
177
+ <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.
179
+ </HARD-GATE>
180
+
181
+ **STOP.** Beyond the remote-issue update above, do not invoke any skill. Do not begin implementation.
182
+
183
+ ## Key principles
184
+
185
+ - **Batch asks at checkpoints**: Decide what the gate lets you decide, record it, and collect the surviving asks into the ticket checkpoint and the plan checkpoint
186
+ - **Multiple choice preferred**: Easier to answer when possible
187
+ - **YAGNI ruthlessly**: Cut unnecessary scope from designs
188
+ - **Scale to complexity**: A simple task gets a short design and a short plan
189
+ - **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
191
+
192
+ <!-- include: ../_partials/next-steps-after-plan.md / -->
193
+
194
+ <!-- include: ../_partials/option-format.md / -->
@@ -0,0 +1,41 @@
1
+ ---
2
+ name: development-workflows
3
+ description: Development workflow conventions covering quality gates and agent efficiency
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Development workflows
8
+
9
+ Rules for development processes and quality gates.
10
+
11
+ ## Quality gates
12
+
13
+ ### Code quality requirements
14
+
15
+ - **Always run linting and type-checking before considering code complete** (mandatory)
16
+ - Auto-format code before staging or considering it complete
17
+ - All quality checks must pass before work is finished
18
+
19
+ ## Performance optimization
20
+
21
+ ### Config-first principle
22
+
23
+ **Prefer explicit configuration over dynamic discovery:**
24
+
25
+ - **Fast path**: Read from `.agents/preferences.yaml` or project config
26
+ - **Fallback only**: Use system commands when config is missing
27
+ - **Never both**: If config exists, ignore dynamic discovery
28
+
29
+ **Benefits:**
30
+
31
+ - Token efficiency: Single file read vs multiple tool calls
32
+ - Time savings: ~100ms file read vs ~500-1000ms command
33
+ - Reliability: No command parsing failures
34
+
35
+ ### Function call optimization
36
+
37
+ **Avoid repeated function calls within same task:**
38
+
39
+ - Execute functions once at task start
40
+ - Store and reuse results
41
+ - Document explicitly: "identify once and remember for this task"
@@ -0,0 +1,67 @@
1
+ ---
2
+ name: get-ticket-id
3
+ description: Extract ticket ID from branch name, commit message, or current context
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Get ticket ID
8
+
9
+ Extract a Jira-style ticket ID from the current context.
10
+
11
+ ## Arguments
12
+
13
+ - _(none)_: Extract from current context (branch name, then commit message)
14
+ - `from-branch` or `from-branch:<name>`: Extract from branch name (current if unspecified)
15
+ - `from-commit` or `from-commit:<ref>`: Extract from commit message (HEAD if unspecified)
16
+
17
+ ## Pattern
18
+
19
+ Matches the canonical Jira-style ticket ID shape: case-insensitive, two-or-more letters, hyphen, digits; uppercased on output. Examples: `ABC-123`, `PT-1234`, `mac-130 → MAC-130`. Trailing `.N` sub-ticket and `-description` suffixes are tolerated in input but not part of the ID. See [`_data/ticket-id-extraction.md`](../_data/ticket-id-extraction.md) for the full contract and behavior table; it is the single source of truth shared with the `derive-session-context` TypeScript implementation.
20
+
21
+ Note: Kebab-case words followed by a digit (e.g., `feat-2`, `foo-2`) are matched and uppercased per the contract; branch slugs that incidentally contain such patterns will produce non-empty ticket IDs (`FEAT-2`, `FOO-2`). See the contract for the rationale.
22
+
23
+ Note: `PR-<n>` (e.g., `PR-123`) is a sanctioned identifier for a pull request without a backing ticket. It matches the pattern like any two-letter prefix, so it resolves to `PR-123` and supplies a branch name and artifact directory. The session-context deriver treats it as a non-ticket and does not build a ticket URL for it.
24
+
25
+ ## Implementation
26
+
27
+ ### From branch name
28
+
29
+ The script `{harness_home_dir}/scripts/get-ticket-id.sh` extracts a ticket ID from a branch name. It accepts an optional branch name (defaults to the current branch) and prints the resolved ticket ID, or an empty string when it cannot derive an ID.
30
+
31
+ In branch names, `_` and `/` are interchangeable separators (see `branch-format.md`). The Jira-style match is case-insensitive and unanchored, so it extracts the ID regardless of which separator is used or whether an author/scope prefix appears (e.g., `wt/COMPPLAN-795`, `wthorsen/MAC-130`, `feat/COMPPLAN-795-add-foo`). The result is uppercased before being returned.
32
+
33
+ When the branch name does not contain a Jira-style ID, the script falls back to a **bare issue number** anchored to the start of the branch name (terminated by `/`, `_`, `-`, or end-of-string). The anchor on the fallback prevents false matches against digits embedded in slugs that lack a Jira-style match.
34
+
35
+ When the bare-numeric fallback applies, the script reads `project.ticket_ref_prefix` from `.agents/preferences.yaml` to format the result:
36
+
37
+ - If `ticket_ref_prefix` is `#`: Return the **bare number only**. The `#` is a GitHub display convention and must not appear in file paths or returned values.
38
+ - If `ticket_ref_prefix` is a Jira-style prefix (e.g., `MAC-`): Return `{prefix}{number}` (e.g., `MAC-147`).
39
+ - If `.agents/preferences.yaml` does not configure a `ticket_ref_prefix`: Return the bare number (e.g., `42`).
40
+
41
+ | Branch | `ticket_ref_prefix` | Returned ticket ID |
42
+ | -------------- | ------------------- | ------------------ |
43
+ | `152` | `#` | `152` |
44
+ | `147/feat/foo` | `MAC-` | `MAC-147` |
45
+ | `42` | _(none)_ | `42` |
46
+
47
+ ```bash
48
+ branch_name="${1:-$(git branch --show-current)}"
49
+ {harness_home_dir}/scripts/get-ticket-id.sh "$branch_name"
50
+ ```
51
+
52
+ ### From commit message
53
+
54
+ ```bash
55
+ commit="${1:-HEAD}"
56
+ git log -1 --pretty=format:'%s' "$commit" | grep -oiE '[A-Z]{2,}-[0-9]+' | head -1 | tr '[:lower:]' '[:upper:]'
57
+ ```
58
+
59
+ ### From current context (default)
60
+
61
+ | Branch ticket | Commit ticket | Action |
62
+ | ------------- | ------------- | ------------------------------------------- |
63
+ | Found | Same | Return ticket ID |
64
+ | Found | Different | Use branch ticket; ask developer to confirm |
65
+ | Found | None | Return branch ticket ID |
66
+ | None | Found | Return commit ticket ID |
67
+ | None | None | Error: No ticket ID found |
@@ -0,0 +1,245 @@
1
+ ---
2
+ name: groom-backlog
3
+ description: Sweep a GitHub backlog for obsolete tickets, assess each open ticket through dispatched subagents, apply one disposition policy, and record each outcome as a ticket comment
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Groom backlog
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.
10
+
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
+
13
+ **Announce at start:** "Using groom-backlog to sweep the open tickets of {repository} (run {run id}{, dry run})."
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description | Default |
18
+ | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | -------------- |
19
+ | `--close-not-planned <reason>` | Close the selected tickets as not planned, for `<reason>`, without assessing them. Requires `--scope` or `--older-than`. See step 3. | Off |
20
+ | `--dry-run` | Assess and render the digests without any write to GitHub and without any decision. | Off |
21
+ | `--exclude-label <label>` | Leave out the tickets that have this label, matched exactly. Repeatable. | None |
22
+ | `--limit <N>` | Assess at most `N` tickets, counted after the tickets that this run already assessed. | All |
23
+ | `--model <alias>` | The model of each assessor: `opus`, `sonnet`, or `haiku`. | `opus` |
24
+ | `--older-than <age>` | Keep the tickets last updated more than `<N>d` days or `<N>w` weeks ago. | All |
25
+ | `--page-size <N>` | Escalations per digest page, from 20 to 30. | 25 |
26
+ | `--run <id>` | The run id that the ledger records and the markers contain. A run resumes under its own id. | `{YYYY-MM-DD}` |
27
+ | `--scope <name>` | Keep the tickets that have the label `scope:<name>`; `scope:<name>` also works. Repeatable. | All |
28
+
29
+ `--run` defaults to today's date in UTC. `--dry-run` appends `-dry-run` to the run id, whether it is the default or given explicitly: A later real run then does not skip the tickets that the dry run assessed.
30
+
31
+ GitHub alone is supported, through `gh`. On any other platform, stop at step 1 and report that the skill does not support it.
32
+
33
+ ## Decision policy
34
+
35
+ The helper's `ingest` command classifies each assessment into one class, and you apply that class's action. The classes are tested in this order, and the first match wins.
36
+
37
+ | Class | Action | Comment |
38
+ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
39
+ | `silent-keep` | A `keep` whose verdicts are all baseline, whether or not the ticket is in progress. Keep it open. | Never |
40
+ | `escalate-in-progress` | Any other assessment of a ticket that a detected signal shows to be under way. Present it in a digest, and apply the user's decision. | As for `escalate`, once the user decides |
41
+ | `auto-close-complete` | A high-confidence `close-complete` with a verified reference, or with `complete` progress and evidence. Close as complete. | Always |
42
+ | `auto-close-half-met` | A high-confidence reply under the half-met rule. Close as superseded. | Always, with the `Remainder` section |
43
+ | `escalate` | Every other assessment. Present it in a digest, and apply the user's decision. | On a close, and on a keep with a non-baseline verdict |
44
+
45
+ **The half-met rule.** A ticket whose motivation other work has met, and whose remainder does not have acceptance criteria of its own, closes as superseded with a comment whose `Remainder` section lists each unmet part, so that a reader can reopen it from the comment alone.
46
+
47
+ **Cross-references.** The helper's pass finds candidates by text, and only the assessor's verification makes one evidence: `auto-close-complete` counts a reference only when the assessor marked it verified.
48
+
49
+ **An in-progress ticket is never closed, edited, or commented on unless the user names its digest entry**, whatever its assessment: Its entry always proposes `leave`, and a bulk close leaves it out. The sweep never rewrites the Problem, Context, or Proposed solution of an in-progress ticket, because those sections record what was known when its work began; the helper refuses such a draft. A silent keep neither closes nor comments, so it applies to an in-progress ticket as to any other.
50
+
51
+ **Baseline verdicts.** The silent keep and the comment rule both read the baseline:
52
+
53
+ <!-- include: ../../_partials/ticket-assessment-baseline.md / -->
54
+
55
+ The helper applies the umbrella case in `ingest` and in `comment`.
56
+
57
+ **What each escalation proposes.** The helper's `digest` command proposes one action per entry, and a confirmed page applies it:
58
+
59
+ | Assessment | Proposed action |
60
+ | --------------------------------------------------------- | ---------------------------- |
61
+ | A ticket in progress, whatever its recommendation | `leave` |
62
+ | `update`, `revise`, or `split` | The same, applying the draft |
63
+ | `close-complete` or `close-superseded` at high confidence | The same close |
64
+ | A `keep` | `keep` |
65
+ | Anything else, including a close below high confidence | `leave` |
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.
68
+
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
+
71
+ ## Dry-run boundary
72
+
73
+ `--dry-run` runs steps 1 to 4 and renders the digests of step 6 with their proposals, then stops. It records the policy and every assessment in the ledger under its own run id. It does not record any decision, post any comment, edit, create, or close any ticket, and it reports what each auto class and each bulk close would have done.
74
+
75
+ ## Process
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:
78
+
79
+ ```bash
80
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs {command} --run {run} {flags}
81
+ ```
82
+
83
+ Create a scratch directory once for the run with `mktemp -d "${TMPDIR:-/tmp}/groom-backlog.XXXXXX"`, and write its absolute path in each place below where `{scratch}` appears: The {tool:Write} tool does not expand shell syntax.
84
+
85
+ The ledger is `local/ticket-triage/ledger.jsonl` in the primary worktree, which a run from a linked worktree shares; the helper reports its path. If the sandbox denies a write there, stop, and ask the user to allow that path. Do not move the ledger.
86
+
87
+ ### 1. Preflight
88
+
89
+ 1. Run `gh auth status` and `gh repo view --json nameWithOwner`. If either fails, or the repository is not on GitHub, stop and report why.
90
+ 2. Resolve the run id per [Arguments](#arguments). If `--close-not-planned` is given without `--scope` or `--older-than`, stop and report that a bulk close needs one of them.
91
+ 3. Record the run's policy. Write the record with {tool:Write} to `{scratch}/policy.json`, then pass it on stdin:
92
+
93
+ ```json
94
+ {"kind":"policy","decidedBy":"user","decisions":{"skill":"groom-backlog","model":"{model}","dryRun":{true|false},"pageSize":{N},"scopes":[],"excludeLabels":[],"olderThan":null,"limit":null,"closeNotPlanned":null}}
95
+ ```
96
+
97
+ `closeNotPlanned` is the reason given to `--close-not-planned`, or `null`.
98
+
99
+ ```bash
100
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs record --run {run} < {scratch}/policy.json
101
+ ```
102
+
103
+ ### 2. Collect
104
+
105
+ ```bash
106
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs collect --run {run} --out {scratch}/tickets \
107
+ --scope {name} --exclude-label {label} --older-than {age} --limit {N}
108
+ ```
109
+
110
+ Pass only the selectors that the invocation names. The result contains `sha`, `counts`, `resumed` (the tickets that this run already assessed and that have not changed since), `pendingAutomatic` (the resumed tickets whose auto-close class does not have a decision yet, each with its `class`), `groups`, and `tickets`. Each group contains its `scope` (`null` for the unscoped group), its tickets oldest first with any `inProgress` signal, and its `waves`. Each ticket's input file is at `{scratch}/tickets/{number}.json`.
111
+
112
+ If `counts.total` is 0, go to step 5 when `pendingAutomatic` is not empty, and to step 6 otherwise: A resumed run can still have pending closes and open escalations.
113
+
114
+ ### 3. Close in bulk, under `--close-not-planned`
115
+
116
+ Without `--close-not-planned`, go to step 4: Every selected ticket is assessed.
117
+
118
+ With it, list the selected tickets that do not have an in-progress signal, each with its number and title, and ask one confirmation in the action-items block before any write. On confirmation, for each listed ticket, render the bulk comment, post it, close the ticket, and record the decision, per [Writing to GitHub](#writing-to-github), with `--decision close-not-planned --decided-by bulk --reason "{reason}"`. The in-progress tickets stay open: Dispatch only them in step 4. On refusal, write nothing and stop.
119
+
120
+ Under `--dry-run`, list the tickets that would close, and write nothing.
121
+
122
+ ### 4. Dispatch the assessors
123
+
124
+ Dispatch the waves of every group, in group order; under `--close-not-planned`, only the in-progress tickets. For each wave, send up to four `{tool:Task}` calls with `subagent_type: ticket-assessor` in one message, each with `model` set to `--model`. Dispatch each ticket with this block:
125
+
126
+ ```dispatch
127
+ root: {root}
128
+ ticket: {scratch}/tickets/{number}.json
129
+ sha: {sha}
130
+ ```
131
+
132
+ **The block contains scalars only, and only these keys.** Do not compose prose into it: The assessor reads the ticket file itself, and a sentence written here would bias its judgment toward yours.
133
+
134
+ **Ingest each reply.** Write the returned text with {tool:Write} to `{scratch}/replies/{number}.md`, then:
135
+
136
+ ```bash
137
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs ingest --run {run} --ticket {scratch}/tickets/{number}.json < {scratch}/replies/{number}.md
138
+ ```
139
+
140
+ The result states the ticket's `class`. If the result is `invalid-reply`, dispatch that ticket once more; if the second reply also fails, leave the ticket unassessed, which the next run retries, and name it in the summary.
141
+
142
+ ### 5. Apply the automatic classes
143
+
144
+ Apply the class of each ingested ticket, and of each ticket in `pendingAutomatic` from step 2, per [Decision policy](#decision-policy), per [Writing to GitHub](#writing-to-github), with `--decided-by policy`:
145
+
146
+ - `auto-close-complete`: `--decision close-complete`.
147
+ - `auto-close-half-met`: `--decision close-superseded`.
148
+ - `silent-keep`: Record `--decision keep` alone, without a comment.
149
+
150
+ Under `--dry-run`, report each ticket and the action that its class would take, and write nothing.
151
+
152
+ ### 6. Present the digests
153
+
154
+ ```bash
155
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs digest --run {run} --page-size {N}
156
+ ```
157
+
158
+ Run `digest` once, and walk the pages of that one result: A `leave` stays undecided, so a second `digest` call would present it again.
159
+
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
+
162
+ Under `--dry-run`, present every page, take no decisions, and go to the summary.
163
+
164
+ ### 7. Apply the confirmed actions and summarize
165
+
166
+ For each entry whose confirmed action is not `leave`, per [Writing to GitHub](#writing-to-github), with `--decided-by user`:
167
+
168
+ - **A close** posts the comment and closes the ticket.
169
+ - **`update`, `revise`, or `split`** composes the draft, applies it, posts the comment when the `comment` result has `post: true`, and records the decision. When the entry's reply does not have a draft (the user named the edit on an entry that did not recommend it), or `draft` reports `stale: true`, `missing-draft`, or `frozen-section`, write nothing for that entry and name it in the summary.
170
+ - **`keep`** posts the comment when the `comment` result has `post: true`, and records the decision in either case. The ticket stays open.
171
+ - **`leave`** writes nothing: neither a comment nor a decision record. A resumed run's digest presents the ticket again.
172
+
173
+ Present the next page once the current one is applied.
174
+
175
+ Then summarize the run: the counts per class, the tickets closed, edited, split, kept, and commented on, the entries left, the drafts skipped and why, the tickets whose replies failed validation, and the ledger's path.
176
+
177
+ ## Writing to GitHub
178
+
179
+ Every action on a ticket follows one order: apply the drafted edit when the decision is `update`, `revise`, or `split`, render the comment, post it, close the ticket when the decision is a close, and record the decision last, so that the ledger never records an action that did not happen.
180
+
181
+ 1. **Apply the draft**, for `update`, `revise`, and `split`. Compose it:
182
+
183
+ ```bash
184
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs draft --run {run} --number {number} --out {scratch}/drafts/{number}
185
+ ```
186
+
187
+ When the result has `stale: true`, the ticket changed after the assessor read it: Skip the ticket without any write. Otherwise, for a split, create each child in `children`, in order, and link it to the ticket, reading each child's number from the URL that `gh issue create` prints:
188
+
189
+ ```bash
190
+ body_path="{child path}"
191
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
192
+ gh issue create --title "{child title}" --body-file "$body_path"
193
+ ```
194
+
195
+ ```bash
196
+ gh issue edit {child number} --parent {number}
197
+ ```
198
+
199
+ Then replace the ticket's body:
200
+
201
+ ```bash
202
+ body_path="{body path}"
203
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
204
+ gh issue edit {number} --body-file "$body_path"
205
+ ```
206
+
207
+ 2. **Render the comment** to a file:
208
+
209
+ ```bash
210
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs comment --run {run} --number {number} \
211
+ --decision {decision} --decided-by {policy|user|bulk} --out {scratch}/comments/{number}.md \
212
+ --reason "{reason}" --superseded-by {N} --children {N,N}
213
+ ```
214
+
215
+ 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
+
217
+ The result's `post` states whether the comment is posted. When it is `false`, the helper writes no body: Skip to step 5.
218
+
219
+ 3. **Post it**, per [gh body file](#gh-body-file):
220
+
221
+ ```bash
222
+ body_path="{scratch}/comments/{number}.md"
223
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
224
+ gh issue comment {number} --body-file "$body_path"
225
+ ```
226
+
227
+ 4. **Close it**, for a close: `gh issue close {number} --reason completed` for `close-complete`, and `gh issue close {number} --reason "not planned"` for every other close.
228
+
229
+ 5. **Record the decision.** Write the record with {tool:Write} to `{scratch}/decisions/{number}.json`, then pass it on stdin:
230
+
231
+ ```json
232
+ {"kind":"decision","number":{number},"decision":"{decision}","decidedBy":"{policy|user|bulk}","reason":"{reason}","supersededBy":{N}}
233
+ ```
234
+
235
+ ```bash
236
+ node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs record --run {run} < {scratch}/decisions/{number}.json
237
+ ```
238
+
239
+ Leave out `reason` and `supersededBy` when they do not apply. A decision without a comment, such as a silent keep, takes this step alone.
240
+
241
+ If a `gh` write fails, stop and report which ticket and which write failed. Do not record a decision for it.
242
+
243
+ <!-- include: ../_partials/gh-body-file.md / -->
244
+
245
+ <!-- include: ../_partials/action-items.md / -->