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
@@ -78,13 +78,13 @@ Both are optional, and each is recorded as an override beside the consolidated r
78
78
 
79
79
  Omit each flag whose field is absent, and pass `--breaking` and `--override-breaking` only if that field is `true`. The effective type is the output's `effective_record.type`; [`resolve-effective-record`](../_data/title-templates.md#resolve-effective-record) states the output. If the call fails, relay its error and continue without an effective type.
80
80
 
81
- - **Type the change from the diff.** Apply [Work type test](#work-type-test) to the diff and resolve the type from that, whatever the consolidated record and `ticket_type` name. Agreement between the two is not evidence: The commits are often typed from the ticket's label, so one misclassification reaches both. When the test's type differs from the effective type, set `override_type` to it and re-run `resolve-effective-record`. A type that the developer passed as `--type` stands: Leave `override_type` as given, and state the test's disagreement in one line. Decide the type here and state it in one line with its reason. Decide a close call by applying the test further and picking, never by asking: The pull-request body and the pre-merge commit show the resolved type before anything publishes. Resolve here rather than later, since the lede's tier in step 5 follows the type. The frontmatter records `override_type` beside the consolidated `type` and `ticket_type`.
81
+ - **Type the change from the diff.** Apply [Work type test](#work-type-test) to the diff and resolve the type from that, whatever the consolidated record and `ticket_type` name. Agreement between the two is not evidence: The commits are often typed from the ticket's label, so one misclassification appears in both. When the test's type differs from the effective type, set `override_type` to it and re-run `resolve-effective-record`. A type that the developer passed as `--type` stands: Leave `override_type` as given, and state the test's disagreement in one line. Decide the type here and state it in one line with its reason. Decide a close call by applying the test further and picking, never by asking: The pull-request body and the pre-merge commit show the resolved type before anything publishes. Resolve here rather than later, since the lede's tier in step 5 follows the type. The frontmatter records `override_type` beside the consolidated `type` and `ticket_type`.
82
82
  - **Check the breaking policy.** Report each `policy-violation` in the last run's `defects`, such as the one that a `refactor` override on a breaking consolidated record produces, and change nothing.
83
83
 
84
84
  3. **Compose title**: Compose the change string per [`title-voice.md`](../_data/title-voice.md).
85
85
  - The change summary's own heading prefixes that string with the ticket reference for identification: `{ticket_ref} {title}`, or just `{title}` when `ticket_ref` is null.
86
86
 
87
- 4. **Compose `## Why`** per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8.
87
+ 4. **Compose `## Why`** per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8. Step 6's writing-rules check reads `## Why` with the drafted passages.
88
88
 
89
89
  5. **Draft the lede and the entries via `entry-drafter`**: Resolve the tier by looking up the effective type from step 2 in [work-types.json](../_data/work-types.json); if there is none, use `internal`. Then dispatch the `{subagent:entry-drafter}` subagent via the {tool:Task} tool with this block:
90
90
 
@@ -99,28 +99,37 @@ Both are optional, and each is recorded as an override beside the consolidated r
99
99
  **A redispatch includes the passages that failed, in a fence below the block.** Step 6 decides which:
100
100
 
101
101
  ```rejected
102
- - {the first passage that failed}
102
+ - {the first passage that failed, after its entry's type and a colon when it is an entry's text}
103
103
  ```
104
104
 
105
- Copy each passage character for character from the draft from which it came, one per line, and send only the passages that failed: The drafter cannot change a passage that it never sees, which keeps one that passed from coming back changed. Send the lede the same way if it is what failed. The fence contains the lede, an entry's `text`, or an entry's `migration`, so the drafter returns one replacement passage per passage sent, in the order sent; put each in the place of the passage that it replaces and keep every other field of that entry, so that a replaced `text` keeps the entry's `migration` and a replaced `migration` keeps its `text`. Take the lede and every other entry from the draft unchanged. If the return contains a different number of passages than you sent, none of them can be placed: Redispatch with `rejection: unmatched-return`, which counts against the two redispatches that step 6 allows and exits as step 6 does.
105
+ Copy each passage character for character from the draft from which it came, one per line, and send only the passages that failed: The drafter cannot change a passage that it never sees, which keeps one that passed from coming back changed. Send the lede the same way if it is what failed. Put an entry's `text` after the entry's `type` as step 6 left it, as `{type}: {passage}`, whatever the rejection code; send the lede and a `migration` bare, since neither takes a type's form. The supplied type overrides the type implied by the commit log, and it is the only way that the drafter's fresh context learns a type corrected by step 6. The fence contains the lede, an entry's `text`, or an entry's `migration`, so the drafter returns one replacement passage per passage sent, in the order sent; put each in the place of the passage that it replaces and keep every other field of that entry, so that a replaced `text` keeps the entry's `migration` and a replaced `migration` keeps its `text`. Take the lede and every other entry from the draft unchanged. If the return contains a different number of passages than you sent, none of them can be placed: Redispatch with `rejection: unmatched-return`, which counts against the two redispatches that step 6 allows and exits as step 6 does.
106
106
 
107
107
  On a first dispatch, take the drafter's `## Lede` section as it stands; step 9 makes it `## What`, and later steps do not rewrite it. A redispatch returns every replacement under `## Entries` and does not return a `## Lede` section at all, so the lede that it keeps is whichever text the placement above left in the lede's place. Parse the `## Entries` fence as YAML. Each entry declares `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry calls for one. Read the `## Report` for any source that the drafter could not access. Step 6 checks each entry's `type`.
108
108
 
109
- 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected.
109
+ 6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads `## Why`.
110
110
 
111
- - **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
111
+ - **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, such as one that only the commit log, the ticket, or this session supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
112
112
  - **Subject.** Read the lede's each sentence, and each entry's `text`, with "This pull request" in front of it. If that sentence is false, the verb names what the system does rather than what the change did: `rejection: subject`. This check fails most often on a change that adds something which itself acts, such as a command, a check, a rule, or a hook, because the added thing's behavior is true, interesting, and reads as a correct entry while standing in for the change. A `migration` is exempt: It is an imperative addressed to the consumer, not a sentence whose subject is the pull request.
113
113
  - **Voice.** A figurative verb, or an invented term when a plain one exists: `rejection: voice`.
114
- - **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination by a test that you hold, not prose, so the correction is never a redispatch and never an ask.
114
+ - **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination that you make by applying a test, not prose, so the correction is never a redispatch and never an ask. The entry's `text` is prose: When it is still written in the form that the replaced type takes, such as a `fix` entry's opening on an entry now typed `feat`, that passage fails: `rejection: type-mismatch`.
115
+ - **Writing rules.** Run this check over the passages that passed every check above, and over `## Why`, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, and each paragraph of `## Why`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
115
116
 
116
- Striking and correcting a sentence, and correcting an entry's `type`, are the whole of your authority. Every other failure is a redispatch, never an edit. Do not rewrite the prose yourself: The draft came from a fresh context for the same reason this audit is mechanical, and rewriting it here restores the weighting that the dispatch removed.
117
+ ```bash
118
+ node {harness_home_dir}/scripts/check-prose.mjs --file "{absolute path of the scratch file}" --json
119
+ ```
120
+
121
+ The helper runs every `revise-prose` detector over the file, reading it as Markdown, and prints one JSON document, `{ file, rules, candidates }`, in which each candidate names its `rule` and the `sentence` that contains the site. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or when it cannot read the file. Read exit 1 as candidates found, not as a failure. Map each candidate to its passage by its `sentence`, and to every passage containing that sentence when more than one does. Judge each against the rule that it names, as your plain-speech and writing guidance states that rule; a watchlist word used in the sense that names its relation, such as a promise that holds, is not a violation. State a candidate judged legitimate in one line with its reason. A confirmed violation in the lede, an entry's `text`, or a `migration` fails that passage: `rejection: writing-rule`. Rewrite a confirmed violation in `## Why` yourself, since this session wrote it. Run the check again over every replaced passage.
122
+
123
+ If the helper is unavailable or the call fails, relay its error, say that the summary was saved without the writing-rules check, and continue.
124
+
125
+ Striking and correcting a sentence, and correcting an entry's `type`, are the whole of your authority over the drafted passages. Every other failure is a redispatch, never an edit. Do not rewrite the prose yourself: The draft came from a fresh context for the same reason this audit is mechanical, and rewriting it here restores the weighting that the dispatch removed.
117
126
 
118
127
  Repeat step 5 with `rejection:` set to the code that the failed check names, and with the passages that failed in the `rejected` fence that step describes.
119
128
 
120
- Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer.
129
+ Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer. Rewrite `## Why` at most twice for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
121
130
 
122
131
  7. **Consolidate the change's record from the entries.** Do this before step 8, and before the frontmatter call: Step 8 reads the entries file that this step writes, and the title and the labels read the record that it produces.
123
- - **Write the verified entries** to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `entries-{timestamp}.yaml`. The file is a top-level YAML list of mappings, one per entry, each declaring `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry has one, as the drafter returned them, with the corrections that step 6 made. Write each `text` and `migration` double-quoted, and quote any value that reached you unquoted: Unquoted, a space followed by `#` opens a YAML comment, and the parse drops the rest of the text. Write it with a file-writing tool rather than a shell heredoc: `text` and `migration` are arbitrary prose containing backticks and quotes. Keep its path; steps 8 and 10 read the same file.
132
+ - **Write the verified entries** to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `entries-{timestamp}.yaml`. The file is a top-level YAML list of mappings, one per entry, each declaring `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry has one, as the drafter returned them, with the corrections that step 6 made. Write each `text` and `migration` double-quoted, and quote any value that the drafter returned unquoted: Unquoted, a space followed by `#` opens a YAML comment, and the parse drops the rest of the text. Write it with a file-writing tool rather than a shell heredoc: `text` and `migration` are arbitrary prose containing backticks and quotes. Keep its path; steps 8 and 10 read the same file.
124
133
  - **Record the derivation commit**: `git rev-parse --short HEAD`. It is the commit at which the entries were read, and `resolve-merge` compares it against the pull request's head to tell a fresh block from a stale one.
125
134
  - **Consolidate the entries:**
126
135
 
@@ -129,7 +138,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
129
138
  node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file "$entries_path"
130
139
  ```
131
140
 
132
- [`consolidate-entries`](../_data/title-templates.md#consolidate-entries) states the output. Its `consolidated_record` is what the frontmatter's `scope`, `type`, and `breaking` record, each absent when it is `null` and `breaking` only when it is `true`. If the call fails, relay its error and leave all three out.
141
+ [`consolidate-entries`](../_data/title-templates.md#consolidate-entries) states the output. Its `consolidated_record` is what the frontmatter's `scope`, `type`, and `breaking` record, each absent when it is `null` and `breaking` only when it is `true`. If the call fails, relay its error and leave all three out. Report each entry in `defects` to the developer, naming the entry by its `text`, then continue; change nothing.
133
142
 
134
143
  - **Re-resolve the effective record** by running `resolve-effective-record` again, on this consolidated record and the overrides resolved in step 2. The first run in step 2 used the commit-derived record, which this one supersedes, and the title and the labels downstream read the effective record. Report each `policy-violation` in `defects` and change nothing.
135
144
 
@@ -165,7 +174,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
165
174
 
166
175
  [`render-block`](../_data/title-templates.md#render-block) states the output, which is JSON; the last command decodes it and prints the `block` field. Render and decode in one Bash invocation, and write the printed block verbatim below `## Details`, separated by one blank line. Never copy the block out of the raw JSON: `text` is arbitrary prose, and JSON escapes its quotes and backslashes a second time.
167
176
 
168
- `create-pr` copies this block into the pull-request body rather than rendering one of its own, so a body saved without one reaches the pull request without one. If the helper is unavailable or the call fails, relay its error, say that the summary does not contain a block, and save the body without one.
177
+ `create-pr` copies this block into the pull-request body rather than rendering one of its own, so if the body is saved without one, the pull request does not contain one either. If the helper is unavailable or the call fails, relay its error, say that the summary does not contain a block, and save the body without one.
169
178
 
170
179
  11. **Save** per the [Saving](#saving) section.
171
180
 
@@ -190,7 +199,7 @@ The body following the frontmatter has this structure:
190
199
 
191
200
  ## Why
192
201
 
193
- {1-3 sentences describing the _motivation_: what was wrong, what was missing, or what new capability is needed. Frame in terms of consequences (for users, the codebase, future work), not mechanism.
202
+ {1-3 sentences stating the _purpose_ that the change serves in this repository: the consequence that it produces or removes, for users, the codebase, or future work. Frame it in terms of that consequence, not mechanism, how the need arose, or how the work is staged across pull requests.
194
203
 
195
204
  Bad: "The retry helper used a fixed backoff schedule with no shared state, so concurrent requests stacked up against the upstream rate limiter."
196
205
  Good: "Heavy-upload sessions were intermittently failing as users hit the upstream API's rate limit."}
@@ -220,7 +229,7 @@ entries:
220
229
  ## Guidance
221
230
 
222
231
  - When `ticket_ref` is null (the branch does not have a ticket), omit the `{ticket_ref} ` portion of the heading and the title so that they read naturally without it.
223
- - The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the context (motivation and background), `## Details` is every outcome that the change contains
232
+ - The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the purpose that the change serves, `## Details` is every outcome that the change contains
224
233
  - Both `## What` and `## Details` come from the drafter, so neither is composed in this session
225
234
  - `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
226
235
  - Ignore auto-formatter and lint-fix changes
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: testing-conventions
3
- description: Test naming conventions and behavioral testing patterns for projects with test suites
3
+ description: What a test is for, how to name and structure it, and how it calls git and other external programs. Consult before writing or changing a test.
4
4
  user-invocable: false
5
5
  ---
6
6
 
@@ -14,11 +14,11 @@ Before writing a test, ask what would go uncaught if it did not exist. Three ans
14
14
 
15
15
  - **A change that someone would have to make on purpose.** Rewording a message, editing a config, adding a member to a list: Each is a decision, and review already guards decisions. A test is justified when it catches an accident, a change made without intending to touch this outcome, such as a route added without its guard or a refactor that drops a case. A scenario constructed so that the test has something to catch is not an accident.
16
16
  - **Nothing that this repository authored.** Machine state, the user's environment, and a dependency's behavior are not under test, and enabling a dependency's feature does not make that feature's behavior ours. If the right response to red would be a bug report upstream, the test is not ours.
17
- - **A difference that costs nothing until noticed.** A relaxed lint rule, a setting that drifts from its best value, a directory that departs from convention: A standing test costs more than the moment that it saves. A caught failure has to cost more than noticing it: a wrong answer returned, a task that a user cannot finish, data lost or exposed.
17
+ - **A difference that costs nothing until noticed.** A relaxed lint rule, a setting that drifts from its best value, a directory that departs from convention: Maintaining a standing test takes more effort than noticing the difference would. A caught failure has to be worse than noticing it: a wrong answer returned, a task that a user cannot finish, data lost or exposed.
18
18
 
19
19
  Then ask where the expected result comes from. A specification, a format, or a rule that someone could state without opening the code makes it an expectation. If pasting in whatever the code now produces would make the test pass again, the test pins a value, whatever its name says. When a test compares two sets, derive the expected one from its source; a set typed into the test drifts.
20
20
 
21
- Three cases recur. Configuration is verified by the tool that reads it, which the build and lint gates run; if an accident is real and the tool is silent, prevent it at the tool rather than detect it in a test. Wording is asserted only when the text is the sole thing that distinguishes two code paths that exist, and then by a durable fragment. A process that this repository does not author is replaced by a stub.
21
+ Three cases recur. Configuration is verified by the tool that reads it, which the build and lint gates run; if an accident is real and the tool is silent, prevent it at the tool rather than detect it in a test. Wording is asserted only when the text is the sole thing that distinguishes two code paths that exist, and then by a durable fragment. A process that this repository does not author is called through an adapter and replaced by a fake, as [External programs](#external-programs) states.
22
22
 
23
23
  If a rule above forbids a test and the case seems exceptional, stop before writing it, state the case in one sentence, and wait.
24
24
 
@@ -33,6 +33,51 @@ A test that guards a behavior still has to clear two checks:
33
33
 
34
34
  If a change needs coverage and these sections rule out every candidate test, it is merged without one; say which answer ruled the candidate out.
35
35
 
36
+ ## Where a test goes
37
+
38
+ A test's **tier** is what it starts or builds to observe a behavior. The cheapest tier calls the code in the test's own process. An **expensive tier** spawns an entry point as a process, starts a runtime or an engine such as a database, or builds a full fixture. An engine counts as expensive whether it runs in the test's process or in another. A project's own tier names may classify tests on another axis, such as what they reach, and a test takes its label from the project's definition; nmr's, for example, labels a test that runs an embedded engine `tool`. The rules below concern cost.
39
+
40
+ - **Tier placement.** Test each case at the cheapest tier that can observe it. An expensive tier covers only what a cheaper tier cannot observe: that the entry starts, parses its arguments, wires its dependencies, and reports its exit status, with one smoke example per entry or verb. A branch of logic, a message, or a field of output is a case for the cheapest tier, even when the entry is the only caller that exercises it.
41
+ - **Consolidate before adding.** Write a new example only for a behavior that the existing examples cannot be extended to cover. Cases that share setup and action are one table-driven test, as [Test structure](#test-structure) states. When the examples do not mutate a fixture, build it once per file, not once per example.
42
+ - **Delete what is superseded, in the same change.** A higher-tier example is superseded when cheaper coverage observes each of its assertions, apart from the entry wiring that the smoke example covers. A change that adds the cheaper coverage deletes the examples that it supersedes, once the new tests pass the second check in [When tests are required](#when-tests-are-required). A port or a rewrite follows the same rule: The change that contains the port deletes the old suite rather than keeping it to catch regressions.
43
+ - **Justify each expensive addition.** A change that adds an example at an expensive tier states, in its plan or its pull-request description, why a cheaper tier cannot observe that example. The justification does not belong in a test comment.
44
+ - **Use the cheapest setup that fits.** Give an expensive tier the cheapest setup that fits its time budget, such as an in-process engine when few files need one. Add infrastructure, such as a server, a container, or a shared test package, only after a run of the suite at CI's parallelism shows that the cheaper setup does not fit.
45
+ - **Keep setup cost independent of the number of files.** Design expensive setup so that adding or splitting a test file does not add to it, for example by starting one engine for the suite rather than one per file.
46
+ - **Fix the design, not the timeout.** When a hook, a test, or a tier needs a longer timeout, in the test or in config, treat that as a sign of bad design and make it do less work: smaller data and injected dependencies, as [Test data](#test-data) states, or setup shared across files. A raised timeout hides a cost that grows with each file and with CI load. Raise one only when none of these fixes applies, and state why in the plan or the pull-request description, not in a test comment.
47
+
48
+ ## Test data
49
+
50
+ - **Use the smallest data that proves the behavior.** A test renders or builds only the records that its assertion needs. Production data, such as a full catalog, appears only in a smoke test whose subject is that data.
51
+ - **Make data that a test cannot replace injectable.** When the code under test reads data or a dependency from a module-level singleton, fix the code: Take the value as a parameter, or read it from a context or provider whose default is the real value. Do not test against the real data, and do not mock this repository's module by its path, which keeps the singleton and ties the test to a file layout.
52
+
53
+ ```tsx
54
+ // ❌ Avoid: The component reads the singleton, so every test renders the full catalog
55
+ function ScopePicker() {
56
+ return <ul>{scopeCatalog.map((scope) => <li key={scope.id}>{scope.label}</li>)}</ul>;
57
+ }
58
+
59
+ // ✅ Good: The context defaults to the real catalog, and the test supplies two scopes
60
+ const ScopeCatalogContext = createContext(scopeCatalog);
61
+
62
+ function ScopePicker() {
63
+ const catalog = useContext(ScopeCatalogContext);
64
+ return <ul>{catalog.map((scope) => <li key={scope.id}>{scope.label}</li>)}</ul>;
65
+ }
66
+
67
+ it('renders one item per scope', () => {
68
+ const scopes = [
69
+ { id: 'read', label: 'Read' },
70
+ { id: 'write', label: 'Write' },
71
+ ];
72
+ render(
73
+ <ScopeCatalogContext.Provider value={scopes}>
74
+ <ScopePicker />
75
+ </ScopeCatalogContext.Provider>,
76
+ );
77
+ expect(screen.getAllByRole('listitem')).toHaveLength(2);
78
+ });
79
+ ```
80
+
36
81
  ## Do not test that removed things stay removed
37
82
 
38
83
  This is the commonest test that guards a decision. When a change removes code, text, or behavior, never add a permanent test asserting the removed thing is absent (a `not.toContain` guard against a deleted string, `expect(isEventType('input.received')).toBe(false)` against a removed variant). The assertion encodes history, not contract: It can fail only if someone reverts that exact line, so it does not guard any regression class, and such assertions accumulate without limit. The positive assertion describing the replacement behavior is the real guard.
@@ -98,7 +143,7 @@ This is the same signal-buried-in-noise failure mode that [comment discipline](#
98
143
 
99
144
  ### Rules
100
145
 
101
- 1. **Test bodies should be mostly variation and assertion, not setup.** Any prop, fixture, or boilerplate identical across N adjacent tests is noise. Factor it into a default-bearing helper, or collapse the tests into a single parameterized test in which the variation reads as a table.
146
+ 1. **Test bodies should be mostly variation and assertion, not setup.** Any prop, fixture, or boilerplate identical across N adjacent tests is noise. Factor it into a helper that supplies defaults, or collapse the tests into a single parameterized test in which the variation reads as a table.
102
147
  2. **Use `it.each` when N adjacent tests differ only in a small set of inputs and the body is structurally identical.** Use a named helper when the variation is bigger, when shared setup should move into a helper signature, or when assertion shapes differ per case.
103
148
  3. **Test the rule, not the data.** Prefer counts, predicates, and structural assertions (`expect(getVisibleChipCount()).toBe(N)`, `expect(queryPillElement()).toBeInTheDocument()`) over enumerating specific fixture labels in every row. Assert specific data flow _once_, in a focused test, not per row of a table.
104
149
 
@@ -112,7 +157,13 @@ The smell is shared _setup with one variable_, not shared _shape with different
112
157
 
113
158
  ### Audit before save
114
159
 
115
- <!-- include: ../../_partials/test-structure-audit-checklist.md / -->
160
+ Before saving a spec file, scan adjacent tests for shared-setup runs.
161
+
162
+ - **Parameterize** with `it.each` when the variation is small and the test body is structurally identical.
163
+ - **Extract a named helper** when the variation is bigger, when shared setup belongs behind a helper signature, or when assertion shapes differ per case.
164
+ - **Check the assertions, too.** When the rule is a count or predicate, specific-fixture-label assertions should not repeat per row. Assert specific data flow _once_ in a focused test; assert structurally for the rest.
165
+
166
+ Three or more `it` blocks with identical setup and a single varying input is the most common failure mode in interactive sessions. That material belongs behind a helper or a parameterized table, not in N copies of the same shape.
116
167
 
117
168
  ## Test organization
118
169
 
@@ -122,14 +173,15 @@ The smell is shared _setup with one variable_, not shared _shape with different
122
173
 
123
174
  A test file runs in one test worker, and a file that keeps its fixtures makes an append cheaper than a split, so a file grows until it is the slowest unit in the suite. Before adding tests to a file that the addition would leave past the ceiling, split the file by aspect, then add the tests to the file that their aspect names.
124
175
 
125
- - **Ceiling.** The `max-lines` setting that the project's lint configuration applies to test files. Where the lint does not set one, 500 lines, counting every line.
176
+ - **Ceiling.** The `max-lines` setting that the project's lint configuration applies to test files. When the lint does not set one, 500 lines, counting every line.
126
177
  - **Aspect.** A group of the subject's behaviors that shares setup and reads without the rest of the file. Each split file contains one aspect.
127
178
  - **Naming.** Each split file keeps the subject's name and adds the aspect after it, followed by any segment that the project's naming requires: `sync.test.ts` becomes `sync.retirement.test.ts`, and `sync.tool.test.ts` becomes `sync.retirement.tool.test.ts`.
128
- - **Fixtures.** Move the fixture builders that the split files share out of the test files, into a module in a `test-utils/` directory beside the tests (beside `__tests__/` when the tests live in one, never inside it), so that a new aspect file costs one import.
179
+ - **Setup.** A split does not add expensive setup. When the file starts an engine or another expensive fixture of its own, share that setup across files first, as [Where a test goes](#where-a-test-goes) states, then split.
180
+ - **Fixtures.** Move the fixture builders that the split files share out of the test files, into a module in a `test-utils/` directory beside the tests (beside `__tests__/` when the tests live in one, never inside it), so that a new aspect file needs only one import.
129
181
 
130
182
  ## Keep passing tests quiet
131
183
 
132
- A passing test prints nothing beyond the runner's report. Output that the code under test writes to the console, stdout, or stderr during a passing run sits between the results, and it hides the warning or stack trace that matters when a run fails.
184
+ A passing test prints nothing beyond the runner's report. Output that the code under test writes to the console, stdout, or stderr during a passing run appears between the results, and it hides the warning or stack trace that matters when a run fails.
133
185
 
134
186
  When the code under test writes output, intercept it in the test that triggers it, and restore it when that test ends:
135
187
 
@@ -158,6 +210,27 @@ jest.mock('@atlaskit/component', () => ({
158
210
  }));
159
211
  ```
160
212
 
213
+ ### External programs
214
+
215
+ A test that runs an external program to produce its inputs verifies the program rather than this code, and it depends on the copy installed on the machine that runs it: its version, its config, and its background processes. A `git commit` in a test repository, for example, can start a background maintenance run that is still writing into `.git/` when the test removes the directory.
216
+
217
+ - Code calls an external program whose behavior is not the subject of the test, such as git, through a small adapter that the code receives as a dependency.
218
+ - Tests of that code pass a fake adapter that returns fixed answers.
219
+ - Only the adapter's own test runs the real program, and it checks that the adapter parses the program's output as the code expects.
220
+ - A test does not create a repository, or any other state of a real program, to produce an input that a fake could return.
221
+
222
+ A test whose subject is the program's effect on real state, such as a command that initializes a repository, runs the program because that effect is the behavior under test.
223
+
224
+ The `typescript-testing-conventions` skill shows the TypeScript shape.
225
+
226
+ ### Code that uses a database
227
+
228
+ A database is a program like any other in [External programs](#external-programs): A test starts one only when its subject is SQL.
229
+
230
+ - Logic that only passes through SQL, such as assembling a view, gating a command, or ordering and reporting, is tested at the cheapest tier against a fake client that returns fixed rows and errors, such as a SQLSTATE. Mock at the boundary of the module containing the SQL when that is simpler than faking the client.
231
+ - The database tests worth writing cover what the schema does not already state: that the migrations apply, transactional bookkeeping, upserts and idempotence, and queries.
232
+ - Do not write a test per constraint, such as inserting a duplicate row to expect the error. The test that the migrations apply covers the schema.
233
+
161
234
  ## Additional patterns
162
235
 
163
236
  ### Omit "should" from test names
@@ -0,0 +1,150 @@
1
+ ---
2
+ name: triage-feedback
3
+ description: Surface the few feedback lessons worth acting on. Clusters the open feedback events by the lesson that they teach, shows each cluster's recurrence, impact, and recency, has a subagent without session context challenge every priority, and then, once the developer approves, files tickets, defers clusters, or changes impact ratings, recording every disposition in a triage artifact. Use when captured feedback has accumulated and the developer wants to know which lessons deserve a guidance change.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Triage feedback
8
+
9
+ Surface the feedback lessons worth acting on. You inventory the open `feedback` events, have a {subagent:lesson-clusterer} group them by lesson, assign each cluster a priority, have a {subagent:feedback-triage-challenger} argue against every priority, and then, once the developer approves, apply the dispositions and record them. Two bundled helpers do the mechanical work: `lesson-clusters` inventories the events and computes each cluster's signals, and `triage-feedback` validates the triage record and renders the artifact.
10
+
11
+ **Announce at start:** "Using triage-feedback to surface the feedback lessons worth acting on."
12
+
13
+ <HARD-GATE>
14
+ Never edit a guidance artifact: a skill, a subagent, a rulebook, a partial, a guidance file, or a helper. A lesson reaches guidance through the ticket that this skill files, and a later change acts on it.
15
+ </HARD-GATE>
16
+
17
+ ## Arguments
18
+
19
+ | Argument | Effect | Default |
20
+ | ------------------- | ---------------------------------------------------------------------------------------- | ----------- |
21
+ | `--limit <n>` | The number of clusters to surface. | 5 |
22
+ | `--store <name>` | The event store: a registry name, `@default`, or `@feedback`. | `@feedback` |
23
+ | `--defer-days <n>` | The days for which a deferred cluster stays out; overrides `triage_feedback.defer_days`. | 30 |
24
+ | `--resume <record>` | Resume a run that stopped during step 7, from its `record.json`. | |
25
+
26
+ With `--resume`, read the record, run `validate` on it, and go to step 7: `validate` reports as `pending` the clusters whose writes are not finished.
27
+
28
+ ## Signals, priorities, and dispositions
29
+
30
+ The `clusters` command computes three signals for each cluster, and the skill shows them separately, never as one score: **recurrence** (the number of events), **impact** (the count of events at each rating, unrated included), and **recency** (the latest capture).
31
+
32
+ A priority states whether the lesson is worth acting on now: `high` (act now), `medium` (worth acting on, but arguable), or `low` (not yet). A borderline cluster takes the lower priority. Each priority has a one-sentence reason that cites the signals.
33
+
34
+ Each surfaced cluster takes one disposition:
35
+
36
+ - `ticket-existing`: a ticket to change the guidance artifact that should have taught the lesson.
37
+ - `ticket-new`: a ticket to create a guidance artifact for a lesson that no artifact covers.
38
+ - `ticket-undecided`: a ticket whose target {skill?:refine-guidance} places.
39
+ - `comment`: a comment on an open issue that already covers the lesson, so that the issue gains the cluster's evidence rather than a duplicate ticket.
40
+ - `impact`: a new impact rating on the cluster's events, for a cluster whose ratings misstate it.
41
+ - `defer`: set aside until the deferral interval passes or the cluster gains a new event.
42
+
43
+ A ticket disposition names the repository that owns its target:
44
+
45
+ - An artifact with a `<!-- codeassembly-` marker, or one in the CodeAssembly guidance library, belongs to the CodeAssembly repository, whose name the marker's provenance or the library's `Source:` line states.
46
+ - A project's `.agents/content` artifact belongs to that project's repository: Take it from the events' `repo` field, and confirm it with `gh repo view {repo} --json nameWithOwner`.
47
+ - A new or undecided target belongs to the current repository.
48
+
49
+ ## Process
50
+
51
+ `<store>` below is the `--store` argument, `@feedback` when it is omitted. 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 helpers as:
52
+
53
+ ```bash
54
+ node {harness_home_dir}/skills/lesson-clusters/lesson-clusters.mjs {command} {flags}
55
+ node {harness_home_dir}/skills/triage-feedback/triage-feedback.mjs {command} {flags}
56
+ ```
57
+
58
+ ### 1. Preflight
59
+
60
+ 1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `artifact_base_dir`, `project_slug`, and `ticket_id`.
61
+ 2. Fix the artifact's path now, because a deferral references it. The directory is `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` when `ticket_id` is set, and `{artifact_base_dir}/projects/{project_slug}/feedback-triage/` otherwise; the `feedback-triage/` name is hardcoded. The filename is `{YYYYMMDD-HHMMSSZ}_{slug}_feedback-triage.md`, with the current UTC time and a slug per {skill:save-artifact}, or `triage` when nothing else suits.
62
+ 3. Create the work directory `{timestamp}_work/` beside the artifact, where `{timestamp}` is the filename's prefix. Every working file goes there.
63
+ 4. Run `gh auth status`. When it fails, report that tickets cannot be filed, and continue only when the developer accepts a run that defers or rates.
64
+
65
+ ### 2. Cluster
66
+
67
+ An inventory is clustered in batches, because one clusterer cannot place every event of a large store. Each batch is clustered on its own, and when there is more than one, a merge pass groups the batch clusters that teach the same lesson.
68
+
69
+ 1. Run `lesson-clusters inventory --store <store> --out {work}/inventory.json`. Report each `skipped` file, and stop when `pool` and `deferred` are both zero: Nothing awaits triage.
70
+ 2. Run `lesson-clusters batch --inventory {work}/inventory.json --out {work}/batches`. Its `batches` list gives each batch's `path` and the `map` path to which its clusterer writes.
71
+ 3. Send one {tool:Task} call per batch, all in one message, `subagent_type: lesson-clusterer`, each with this block and nothing else composed into it:
72
+
73
+ ```dispatch
74
+ inventory: {batch path}
75
+ output: {batch map path}
76
+ ```
77
+
78
+ 4. When there is one batch, its map is the event map: Go to the last sub-step with `--map {work}/batches/map-01.json`.
79
+ 5. Run `lesson-clusters lessons --batches {work}/batches --out {work}/lessons.json`. On `invalid-map`, resume the clusterer of each batch that the `violations` name once, sending it that batch's violations and asking it to correct its map; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. Run `lessons` again, and on a second failure, stop and report the violations.
80
+ 6. Send one more {tool:Task} call, `subagent_type: lesson-clusterer`, for the merge pass:
81
+
82
+ ```dispatch
83
+ inventory: {work}/lessons.json
84
+ output: {work}/merge.json
85
+ ```
86
+
87
+ 7. Run `lesson-clusters combine --batches {work}/batches --lessons {work}/lessons.json --map {work}/merge.json --out {work}/map.json`. On `invalid-map`, resume the merge clusterer once with the violations, run `combine` again, and on a second failure, stop and report them.
88
+ 8. Run `lesson-clusters clusters --inventory {work}/inventory.json --map {work}/map.json --limit {limit} --out {work}/clusters.json`, adding `--defer-days {n}` when it was given. `clusters.json` lists the candidates, the clusters that the triage ranks: each signal nominates its own top clusters, four times `--limit` of them, so that a single critical event or a recent spike is considered beside the clusters that recur most. `unranked` counts the clusters that no signal nominated.
89
+
90
+ ### 3. Recommend
91
+
92
+ Read `clusters.json`. Assign every candidate a priority and a reason, then order the clusters by priority, recurrence, and latest capture; the first `--limit` clusters are surfaced. For each surfaced cluster, suggest a disposition, and for a ticket disposition, find the target: Search the guidance for the artifact that states or should state the lesson, and decide its repository by the rules above. Then search that repository's open issues with `gh issue list --repo {repo} --search`; when one already covers the lesson, suggest `comment` on it instead.
93
+
94
+ Write `{work}/recommendations.md`: one line per cluster, with its id, priority, disposition, target, target repository, and a one-sentence reason. Write a line for every candidate, not only the surfaced ones, because the challenger argues against every priority. Nothing else goes in the file, because the challenger reads it and a sentence of your reasoning there would bias its judgment toward yours.
95
+
96
+ ### 4. Challenge
97
+
98
+ Send one {tool:Task} call, `subagent_type: feedback-triage-challenger`, with this block and nothing else composed into it:
99
+
100
+ ```dispatch
101
+ clusters: {work}/clusters.json
102
+ recommendations: {work}/recommendations.md
103
+ root: {repository root}
104
+ ```
105
+
106
+ **A reply that lacks the `Phase: feedback-triage-challenge` line is a challenger stopped by its turn limit.** Resume it once, asking only for its report. When the resumed challenger still does not return a report, do not dispatch again: Record every challenge with the outcome `not-returned`.
107
+
108
+ Save the reply as `{work}/challenge.md`. Then take each cluster in turn: Defend the priority and the disposition when the argument fails on the evidence, modify them when the argument stands in part, and abandon the priority, by lowering it, when the argument stands. A changed priority can change which clusters are surfaced; re-apply the order and the limit.
109
+
110
+ Write `{work}/record.json` in the helper's record shape: `store` (the store name that the inventory reports), `limit`, `artifactPath` (the artifact's path with the home directory written as `~`), `clusters` (the candidates), `unranked` (as `clusters.json` reports it), and `remainder` (`clusters` and `events`, the count of clusters not surfaced, unranked ones included, and of their events, and `excluded`, the number of clusters in the `excluded` list of `clusters.json`). Each cluster carries the fields of `clusters.json` plus `priority`, `reason`, `challenge` (`argument`, `outcome`, `originalPriority` when the outcome changed the priority, and `note`), and `surfaced`. A surfaced cluster also carries `suggested` (`kind`, then `target` and `repo` for a ticket kind, with `target: null` for `ticket-undecided`, `issue` (the issue URL) for `comment`, or `level` for `impact`) and `result: null`. Run `triage-feedback validate --file {work}/record.json`, which reports every violation at once, and fix the record until it passes.
111
+
112
+ ### 5. Checkpoint: The dispositions
113
+
114
+ Present the surfaced clusters as one table: cluster, lesson, recurrence, impact, latest capture, priority, reason, challenge outcome, and disposition. Below it, state the remainder in one line: "{clusters} more clusters, {events} events, remain in the pool; {excluded} deferred clusters are excluded." Ask in the action-items block for one approval of every disposition.
115
+
116
+ The developer may change a row in the reply. Record the change in the record, setting `decision: modified` and keeping the suggestion that it replaced in `originalSuggested`; re-run `validate`, and present only the changed rows again before writing. On approval, set `decision` on every surfaced cluster: `approved`, `modified`, or `declined`. This approval covers every ticket that step 7 files, so {skill:create-ticket} does not confirm again.
117
+
118
+ <!-- include: ../_partials/action-items.md / -->
119
+
120
+ ### 6. Compose
121
+
122
+ For each ticket disposition, compose the body in the ticket skeleton that {skill:create-ticket} step 2 states. The problem states the lesson; the context lists the event ids under the store name, with the signals; the proposed solution names the target, or states "Target: undecided; `refine-guidance` places it."; the acceptance criteria state the behavior that the lesson asks for.
123
+
124
+ For each `comment` disposition, compose a comment that opens with the line `Feedback triage: {cluster id}`, states the lesson, and lists the event ids under the store name, with the signals.
125
+
126
+ ### 7. Write
127
+
128
+ Nothing before this step writes to a tracker or a store. Process each approved or modified cluster in surfacing order, and write its `result` into the record as soon as each write returns, so that a `--resume` run repeats only what is missing. On a failed write, stop and report which cluster failed.
129
+
130
+ - **A ticket disposition**: When `result.ticket` is not yet set, create the ticket with {skill:create-ticket}, adding `--repo {repo}` when the target's repository differs from the current one, and record its URL as `result.ticket`, with `marked: false`. Then mark the events with {skill:kb-update-events}: `--store <store> --add-addressed-by={ticket URL}` and the event ids. Set `marked: true`.
131
+ - **`comment`**: When `result.comment` is not yet set, read the issue's comments with `gh issue view {issue} --json comments`, and post the comment only when none already opens with its first line; record the comment's URL as `result.comment`, with `marked: false`. Then mark the events with {skill:kb-update-events}: `--store <store> --add-addressed-by={issue URL}` and the event ids. Set `marked: true`.
132
+
133
+ ```bash
134
+ body_path="{absolute path of the composed comment}"
135
+ [ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
136
+ gh issue comment {issue} --body-file "$body_path"
137
+ ```
138
+
139
+ - **`defer`**: Run {skill:kb-update-events} with `--store <store> --add-tag deferred` and the event ids, then with `--add-addressed-by={artifactPath}`. Set `result` to `{ "marked": true }`.
140
+ - **`impact`**: Run {skill:kb-update-events} with `--store <store> --set-impact {level}` and the event ids. Set `result` to `{ "marked": true }`.
141
+
142
+ Each {skill:kb-update-events} result reports each event; treat any event whose result has `ok: false` as a failed write. A declined cluster does not write anything.
143
+
144
+ ### 8. Record and report
145
+
146
+ Run `triage-feedback validate` on the final record, then `triage-feedback render --file {work}/record.json --out {work}/artifact.md`. Save the rendered body, with frontmatter, at the artifact path fixed in step 1, per {skill:save-artifact}.
147
+
148
+ Report each filed ticket with its repository, each deferred or rated cluster, each declined cluster, the remainder line, and the artifact's path.
149
+
150
+ <!-- include: ../_partials/gh-body-file.md / -->