codeassembly-guidance 0.1.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 (137) hide show
  1. package/.meta/changelog.json +757 -0
  2. package/CHANGELOG.md +181 -0
  3. package/README.md +125 -95
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +2 -2
  6. package/content/_partials/code-style.md +1 -1
  7. package/content/_partials/comment-discipline.md +1 -1
  8. package/content/_partials/plain-speech-calibration.md +4 -0
  9. package/content/_partials/technical-recommendations.md +1 -0
  10. package/content/codeassembly-content.yaml +11 -1
  11. package/content/collections/all.md +2 -2
  12. package/content/collections/atlassian.md +2 -1
  13. package/content/collections/recommended.md +9 -2
  14. package/content/collections/triage.md +3 -67
  15. package/content/collections/williamthorsen.md +2 -1
  16. package/content/guidance/README.md +1 -1
  17. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  18. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  19. package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
  20. package/content/guidance/rulebooks/commit-conventions.md +2 -2
  21. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  22. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  23. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  24. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  25. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  26. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
  27. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  28. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  29. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  30. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  31. package/content/guidance/shared/AGENTS.md +8 -0
  32. package/content/scripts/README.md +5 -2
  33. package/content/scripts/check-branch-currency.mjs +11 -0
  34. package/content/scripts/check-prose.mjs +171 -0
  35. package/content/scripts/describe-change.mjs +97 -97
  36. package/content/scripts/manage-jira-ticket.mjs +99 -94
  37. package/content/scripts/resolve-frontmatter.sh +1 -1
  38. package/content/scripts/resolve-review-run.mjs +9 -9
  39. package/content/scripts/select-lede-exemplars.mjs +87 -87
  40. package/content/scripts/validate-preferences.mjs +146 -0
  41. package/content/skills/_data/artifact-conventions.md +46 -14
  42. package/content/skills/_data/branch-currency.md +36 -0
  43. package/content/skills/_data/change-record.md +2 -2
  44. package/content/skills/_data/design-priorities.md +3 -3
  45. package/content/skills/_data/project-stage.md +32 -0
  46. package/content/skills/_data/recommendation-gradient.md +9 -7
  47. package/content/skills/_data/scope-and-deferral.md +1 -1
  48. package/content/skills/_data/spike-conventions.md +1 -1
  49. package/content/skills/_data/ticket-evaluation.md +2 -2
  50. package/content/skills/_data/ticket-source-resolution.md +36 -3
  51. package/content/skills/_data/title-templates.md +19 -11
  52. package/content/skills/_partials/action-items.md +2 -2
  53. package/content/skills/_partials/commit-title-rendering.md +1 -1
  54. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  55. package/content/skills/_partials/next-steps-after-plan.md +10 -10
  56. package/content/skills/_partials/next-steps-after-review.md +9 -9
  57. package/content/skills/_partials/option-format.md +18 -17
  58. package/content/skills/_partials/plan-template.md +5 -5
  59. package/content/skills/_partials/split-ticket-compose.md +1 -1
  60. package/content/skills/_partials/split-ticket-create.md +1 -1
  61. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  62. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  63. package/content/skills/add-change-record/SKILL.md +2 -2
  64. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  65. package/content/skills/anti-patterns/SKILL.md +1 -1
  66. package/content/skills/assess-usability/SKILL.md +96 -0
  67. package/content/skills/capture-event/SKILL.md +2 -2
  68. package/content/skills/capture-event/capture-event.mjs +89 -89
  69. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  70. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  71. package/content/skills/collaborate/SKILL.md +1 -1
  72. package/content/skills/create-gh-pr/SKILL.md +24 -9
  73. package/content/skills/create-pr/SKILL.md +5 -5
  74. package/content/skills/create-ticket/SKILL.md +61 -16
  75. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  76. package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
  77. package/content/skills/design-and-plan/SKILL.md +13 -10
  78. package/content/skills/groom-backlog/SKILL.md +8 -6
  79. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  80. package/content/skills/implement-plan/SKILL.md +25 -21
  81. package/content/skills/index-prototypes/SKILL.md +85 -30
  82. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  83. package/content/skills/kb-add/SKILL.md +2 -1
  84. package/content/skills/kb-add/kb-add.mjs +128 -128
  85. package/content/skills/kb-curate/SKILL.md +9 -7
  86. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  87. package/content/skills/kb-edit/SKILL.md +3 -3
  88. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  89. package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
  90. package/content/skills/kb-retrieve-events/SKILL.md +1 -1
  91. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
  92. package/content/skills/kb-update-events/SKILL.md +2 -2
  93. package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
  94. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  95. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  96. package/content/skills/merge-pr/SKILL.md +11 -11
  97. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  98. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  99. package/content/skills/plan/SKILL.md +1 -1
  100. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  101. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  102. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  103. package/content/skills/refine-plan/SKILL.md +7 -3
  104. package/content/skills/refine-prototype/SKILL.md +113 -0
  105. package/content/skills/respond-to-review/SKILL.md +1 -1
  106. package/content/skills/review-bb-pr/SKILL.md +1 -1
  107. package/content/skills/review-branch/SKILL.md +4 -2
  108. package/content/skills/review-criteria/SKILL.md +36 -3
  109. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  110. package/content/skills/revise-comments/SKILL.md +38 -5
  111. package/content/skills/revise-prose/SKILL.md +1 -1
  112. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  113. package/content/skills/save-artifact/SKILL.md +2 -0
  114. package/content/skills/streamline-guidance/SKILL.md +1 -1
  115. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  116. package/content/skills/summarize-change/SKILL.md +22 -13
  117. package/content/skills/testing-conventions/SKILL.md +74 -7
  118. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  119. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  120. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  121. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  122. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  123. package/content/skills/update-project-guidance/SKILL.md +2 -2
  124. package/content/subagents/_data/claude.yaml +6 -0
  125. package/content/subagents/_data/rovo.yaml +12 -2
  126. package/content/subagents/canary.md +2 -1
  127. package/content/subagents/disposition-challenger.md +78 -0
  128. package/content/subagents/entry-drafter.md +14 -10
  129. package/content/subagents/handoff-reviewer.md +2 -2
  130. package/content/subagents/plan-reviewer.md +1 -1
  131. package/content/subagents/prose-reviser.md +4 -2
  132. package/content/subagents/ticket-assessor.md +9 -6
  133. package/content/subagents/usability-assessor.md +157 -0
  134. package/package.json +15 -11
  135. package/schemas/preferences.v1.json +29 -2
  136. package/schemas/work-types.v1.json +1 -1
  137. 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). 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.
@@ -84,7 +84,7 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
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
 
@@ -108,6 +108,8 @@ Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ti
108
108
 
109
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
110
 
111
+ **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.
112
+
111
113
  ### Phase 4: Generate implementation plan
112
114
 
113
115
  <HARD-GATE>
@@ -134,12 +136,13 @@ Then save both artifacts:
134
136
  - 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
137
  - Target: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
136
138
  - `mkdir -p` the target directory
139
+ - 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
140
 
138
141
  2. Resolve frontmatter fields for both artifacts. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
139
142
 
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.
143
+ 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
144
 
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.
145
+ 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
146
 
144
147
  3. Save both artifacts following `save-artifact` naming conventions:
145
148
  - Ticket: `{YYYYMMDD-HHMMSSZ}_{slug}_ticket.md`
@@ -147,7 +150,7 @@ Then save both artifacts:
147
150
 
148
151
  Prepend the resolved frontmatter to each artifact content before writing.
149
152
 
150
- 4. Report paths and present next steps.
153
+ 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
154
 
152
155
  ```
153
156
  Design and plan complete:
@@ -168,14 +171,14 @@ Next steps:
168
171
 
169
172
  **A2: Next action**
170
173
  1. 🧠 ■□□ Refine plan:
171
- - Clear context and use the `refine-plan` skill with plan: {plan_path}, ticket: {ticket_path}
174
+ - Clear context, then {skill?:refine-plan} with plan: {plan_path}, ticket: {ticket_path}
172
175
  ...
173
176
  ```
174
177
 
175
178
  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
179
 
177
180
  <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.
181
+ 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
182
  </HARD-GATE>
180
183
 
181
184
  **STOP.** Beyond the remote-issue update above, do not invoke any skill. Do not begin implementation.
@@ -187,7 +190,7 @@ Follow the options, output format, and recommendation rules in [next-steps optio
187
190
  - **YAGNI ruthlessly**: Cut unnecessary scope from designs
188
191
  - **Scale to complexity**: A simple task gets a short design and a short plan
189
192
  - **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
193
+ - **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
194
 
192
195
  <!-- include: ../_partials/next-steps-after-plan.md / -->
193
196
 
@@ -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