codeassembly-guidance 0.0.0 → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,308 @@
1
+ ---
2
+ name: summarize-change
3
+ description: Analyze changes and generate structured summary for PR preparation
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Summarize change
8
+
9
+ Analyze the current branch's changes since diverging from the default branch.
10
+
11
+ The change's consolidated record is derived from the change entries and recorded per [the change record](../_data/change-record.md). The body ends with the rendered `change-record` block, which records the entries in the pull request.
12
+
13
+ ## Arguments
14
+
15
+ | Flag | Effect |
16
+ | ----------------- | ----------------------------------------------------------------------------------- |
17
+ | `--scope {scope}` | Overrides the consolidated scope. |
18
+ | `--type {type}` | Overrides the consolidated work type. A `!` on it (`feat!`) adds the breaking mark. |
19
+
20
+ Both are optional, and each is recorded as an override beside the consolidated record rather than in place of it.
21
+
22
+ ## Process
23
+
24
+ 1. **Gather context**:
25
+ - Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `default_branch`, `ticket_id`, `ticket_ref`, and `scm` from the manifest JSON emitted on stdout; consult [work-types.json](../_data/work-types.json).
26
+
27
+ 2. **Analyze changes**:
28
+
29
+ ```bash
30
+ git diff {default_branch}...HEAD
31
+ ```
32
+
33
+ Check commit messages for additional context. Then consolidate the branch, in this order:
34
+ - **Fetch the ticket's labels** when `scm` is `github` and `ticket_id` is non-null:
35
+
36
+ ```bash
37
+ gh issue view {ticket_id} --json labels --jq '.labels[].name'
38
+ ```
39
+
40
+ Otherwise, do not pass any labels. If the fetch fails, continue without labels and say so; `ticket_type` is then absent.
41
+
42
+ - **Consolidate the range** into a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `consolidation-{timestamp}.json`:
43
+
44
+ ```bash
45
+ consolidation_path="{absolute path from the scratch-directory step}"
46
+ node {harness_home_dir}/scripts/describe-change.mjs consolidate-branch --base {default_branch} \
47
+ > "$consolidation_path" && cat "$consolidation_path"
48
+ ```
49
+
50
+ [`consolidate-branch`](../_data/title-templates.md#consolidate-branch) states the output. The frontmatter call reads `changes` back from this file, so keep its path.
51
+
52
+ This consolidation serves `changes`, the unmatched and violation report below, and the tier that step 5 seeds the drafter with. It is not what the frontmatter's `scope`, `type`, and `breaking` record: Step 7 consolidates those from the change entries, which do not exist yet.
53
+
54
+ If the call fails, as it does when `commit.title_format` is empty, it leaves the file empty. Relay its error and continue without a consolidated record: `changes` is left out, and step 7 consolidates the record from the entries as it does on any run.
55
+
56
+ - **Resolve the ticket's type** if the fetch returned labels, passing one `--ticket-label` per label. If there are none, skip the call; `ticket_type` is then absent.
57
+
58
+ ```bash
59
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-ticket-type \
60
+ --ticket-label "{label}"
61
+ ```
62
+
63
+ Read `ticket_type` from the output, leaving it absent if it is `null`; [`resolve-ticket-type`](../_data/title-templates.md#resolve-ticket-type) states when it is. If the call fails, relay its error and continue with `ticket_type` absent.
64
+
65
+ - **Report** each `unmatched` subject and each `violations` entry to the developer, then continue. If every field of `consolidated_record` is `null`, say that the branch does not yield any commit entries and continue; the tier that step 5 seeds falls back to `internal`.
66
+ - **Resolve the overrides.** `--scope` sets `override_scope`. `--type` sets `override_type`, and a `!` on it sets `override_breaking` rather than staying on the type. Record an override as given, even if it equals the consolidated record.
67
+ - **Resolve the effective record** from the consolidated record and the overrides:
68
+
69
+ ```bash
70
+ node {harness_home_dir}/scripts/describe-change.mjs resolve-effective-record \
71
+ --scope "{scope}" \
72
+ --type "{type}" \
73
+ --breaking \
74
+ --override-scope "{override_scope}" \
75
+ --override-type "{override_type}" \
76
+ --override-breaking
77
+ ```
78
+
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
+
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`.
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
+
84
+ 3. **Compose title**: Compose the change string per [`title-voice.md`](../_data/title-voice.md).
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
+
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.
88
+
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
+
91
+ ```dispatch
92
+ type: {resolved type}
93
+ tier: {resolved tier}
94
+ ticket-source: {ticket URL or reference}
95
+ ```
96
+
97
+ **The block contains scalars only, and only these keys.** Omit `type` and `ticket-source` if they are unresolved; add `rejection: {code}` only on a redispatch. Do not compose prose into it: The drafter gathers every fact itself, and a sentence written here would introduce this session's weighting into the draft, which is the failure that the fresh context exists to avoid. A content test fails the build on a line that is not a `key: value` scalar and on a key outside this set, so a new flag is added deliberately rather than by a passing test.
98
+
99
+ **A redispatch includes the passages that failed, in a fence below the block.** Step 6 decides which:
100
+
101
+ ```rejected
102
+ - {the first passage that failed}
103
+ ```
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.
106
+
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
+
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.
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`.
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
+ - **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.
115
+
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
+
118
+ 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
+
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.
121
+
122
+ 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.
124
+ - **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
+ - **Consolidate the entries:**
126
+
127
+ ```bash
128
+ entries_path="{absolute path from the write step}"
129
+ node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file "$entries_path"
130
+ ```
131
+
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.
133
+
134
+ - **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
+
136
+ 8. **Render `## Details`** from the entries file that step 7 wrote:
137
+
138
+ ```bash
139
+ entries_path="{absolute path from step 7}"
140
+ node {harness_home_dir}/scripts/describe-change.mjs render-details --entries-file "$entries_path" \
141
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('details',''))"
142
+ ```
143
+
144
+ [`render-details`](../_data/title-templates.md#render-details) states the output and how it is rendered. Render and decode in one Bash invocation, as step 10 does, and write the printed body verbatim under `## Details`, composing nothing into it. Write the section only when the body is not empty, which is on every change that yields an entry.
145
+
146
+ If the helper is unavailable or the call fails, relay its error, say that the summary does not contain `## Details`, and save the body without it. Never render the section by hand: Hand-rendered headings drift from the taxonomy.
147
+
148
+ 9. **Compose `## What`** from the drafter's lede: the `## Lede` section as step 6 left it. Write nothing of your own into it, and do not take any sentence from the entries: The lede was written in a fresh context for the reader who meets the change without them, and a sentence added here adds this session's weighting to the pull request and the merge commit.
149
+
150
+ 10. **Render the `change-record` block** and make it the body's last element:
151
+
152
+ ```bash
153
+ entries_path="{absolute path from step 7}"
154
+ node {harness_home_dir}/scripts/describe-change.mjs render-block \
155
+ --title "{title}" \
156
+ --override-scope "{override_scope}" \
157
+ --override-type "{override_type}" \
158
+ --override-breaking \
159
+ --entries-file "$entries_path" \
160
+ --entries-commit "{the short SHA from step 7}" \
161
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('block',''))"
162
+ ```
163
+
164
+ Pass the overrides resolved in step 2, never the effective record: `resolve-merge` ranks the entries and applies the overrides itself. Omit each override flag whose field is absent, and pass `--override-breaking` only if that field is `true`.
165
+
166
+ [`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
+
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.
169
+
170
+ 11. **Save** per the [Saving](#saving) section.
171
+
172
+ If expected information is missing, stop and ask the developer.
173
+
174
+ ## Work type test
175
+
176
+ <!-- include: ../../_partials/work-type-choice.md / -->
177
+
178
+ ## Output format
179
+
180
+ The artifact begins with a single YAML frontmatter block that unifies canonical fields from the canonical schema with change-summary-specific consumer fields; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter) and the consumer-field extensions in [Change-summary frontmatter](../_data/artifact-conventions.md#change-summary-frontmatter). Ordering: `provenance:` first, then top-level canonical fields, then consumer fields. `commit:` and `ticket_id:` appear exactly once each. Field-resolution steps are stated in the [Canonical-field resolution](#canonical-field-resolution) section below.
181
+
182
+ The body following the frontmatter has this structure:
183
+
184
+ ````markdown
185
+ # {ticket_ref} {title}
186
+
187
+ ## What
188
+
189
+ {The drafter's lede.}
190
+
191
+ ## Why
192
+
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.
194
+
195
+ Bad: "The retry helper used a fixed backoff schedule with no shared state, so concurrent requests stacked up against the upstream rate limiter."
196
+ Good: "Heavy-upload sessions were intermittently failing as users hit the upstream API's rate limit."}
197
+
198
+ ## Details
199
+
200
+ ### 🎉 Features
201
+
202
+ - Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store. #agents, #kb
203
+ - Adds `visibility` to `.kb/config.yaml`, taking `shared` or `private`. #agents
204
+
205
+ ### 🐛 Bug fixes
206
+
207
+ - 🚨 **Breaking:** Stops `kb check` resolving a bare wikilink against every store. #kb
208
+ - Migration: Qualify each wikilink that names a note outside its own store as `[[store:Note title]]`.
209
+
210
+ ```change-record
211
+ title: Add the store-qualified wikilink
212
+ entries_commit: e5029924
213
+ entries:
214
+ - type: feat
215
+ scopes: [agents, kb]
216
+ text: Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store.
217
+ ```
218
+ ````
219
+
220
+ ## Guidance
221
+
222
+ - 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
224
+ - Both `## What` and `## Details` come from the drafter, so neither is composed in this session
225
+ - `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
226
+ - Ignore auto-formatter and lint-fix changes
227
+ - `## What` and `## Why` are required
228
+ - The rendered `change-record` block is the body's last element, per [the change record](../_data/change-record.md)
229
+ - Never list automated checks (formatting, linting, typechecking, unit tests) in a test plan. They run automatically in CI.
230
+
231
+ <!-- include: ../../_partials/prose-line-breaks.md / -->
232
+
233
+ <!-- include: ../_partials/nested-list-indent.md / -->
234
+
235
+ ## Frontmatter inference
236
+
237
+ The single YAML frontmatter block contains both canonical identity fields from the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) and change-summary-specific consumer fields read by downstream PR-creation skills (`create-pr`, `create-gh-pr`, `create-bitbucket-pr`). `commit:` and `ticket_id:` appear exactly once and serve a dual role: canonical identity fields that downstream consumers may also read.
238
+
239
+ The block is structured as:
240
+
241
+ 1. `provenance:` block (canonical nested fields: `skill`, `timestamp`, `baseSha`, `isInteractive`, `model`).
242
+ 2. Top-level canonical fields: `branch`, `commit`, `pr`, `ticket_id`, `ticket_ref`, `run_id`.
243
+ 3. Consumer extensions: `title`, `scope`, `type`, `breaking`, `changes`, `ticket_type`, `override_scope`, `override_type`, `override_breaking`.
244
+
245
+ ### Canonical-field resolution
246
+
247
+ Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`. Resolve the consumer extensions per [Consumer fields](#consumer-fields) below. Run this after step 7, which resolves the consolidated record's `scope`, `type`, and `breaking`.
248
+
249
+ Run via Bash, writing each resolved scalar into the call as literal text and dropping the whole flag for a field that is absent. `changes` is read from the step-2 consolidation file inside the same call, so that an entry is never retyped into a command, in which a backtick, `$`, or `"` would be expanded or would end the argument. A file that a failed consolidation left empty does not yield any `changes`:
250
+
251
+ ```bash
252
+ consolidation_path="{absolute path of the step-2 consolidation file}"
253
+ changes=()
254
+ if [ -s "$consolidation_path" ]; then
255
+ while IFS= read -r change; do changes+=(--extra-list-item "changes=$change"); done < <(jq -r '.entries[].change' "$consolidation_path")
256
+ fi
257
+ {harness_home_dir}/scripts/resolve-frontmatter.sh \
258
+ --skill summarize-change \
259
+ --interactive true \
260
+ --model "{model_id}" \
261
+ --extra "title={title}" \
262
+ --extra "scope={scope}" \
263
+ --extra "type={type}" \
264
+ --extra "breaking=true" \
265
+ "${changes[@]}" \
266
+ --extra "ticket_type={ticket_type}" \
267
+ --extra "override_scope={override_scope}" \
268
+ --extra "override_type={override_type}" \
269
+ --extra "override_breaking=true"
270
+ ```
271
+
272
+ Dropping a flag keeps an absent field out of the emitted frontmatter. `--extra "breaking=true"` and `--extra "override_breaking=true"` appear only if that field is `true`.
273
+
274
+ Prepend the script's output verbatim to the artifact body.
275
+
276
+ ### Consumer fields
277
+
278
+ - **`title`**: The bare title without the `ticket_ref` prefix. If `ticket_ref` is `#409` and the heading is `#409 Rationalize PR creation skills`, the title is `Rationalize PR creation skills`. When `ticket_ref` is null, the title is the entire heading text.
279
+ - **`scope`**, **`type`**, and **`breaking`**: The step-7 `consolidated_record`, consolidated from the change entries, each absent if it is `null` and `breaking` only if it is `true`. They record the consolidated record and never an override.
280
+ - **`changes`**: Each commit entry's `change`, oldest first, read from the step-2 consolidation file. It is the commit-derived list, which the change entries do not replace: The two answer different questions, and a reviewer reads `changes` to see what the branch's commits declared.
281
+ - **`ticket_type`**: The step-2 `ticket_type`, absent if it is `null` or unresolved.
282
+ - **`override_scope`**, **`override_type`**, and **`override_breaking`**: The overrides resolved in step 2, each absent if unset, and `override_breaking` only if it is `true`.
283
+
284
+ A skill that needs the effective record reads it from [`resolve-effective-record`](../_data/title-templates.md#resolve-effective-record), run on these fields.
285
+
286
+ ## As a PR description
287
+
288
+ When used as a PR description, include **from `## What` onward only**; omit the H1 title and metadata block.
289
+
290
+ ## Saving
291
+
292
+ ### Path resolution
293
+
294
+ Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir`, `project_slug`, and `ticket_id` from the manifest JSON emitted on stdout (the same invocation in step 1 already populated the manifest file, so this is a fast-path read).
295
+
296
+ Follow [artifact conventions](../_data/artifact-conventions.md).
297
+
298
+ Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
299
+
300
+ Artifact type: `change-summary`. Filename format:
301
+
302
+ ```
303
+ {timestamp}_{slug}_change-summary.md
304
+ ```
305
+
306
+ Example: `20250121-1530Z_auto-share-exception_change-summary.md`
307
+
308
+ <!-- include: ../_partials/gh-body-file.md / -->
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: summarize-chat
3
+ description: Create a summary of the current conversation for distribution
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Summarize chat
8
+
9
+ Create a distributable summary of the current conversation.
10
+
11
+ ## Include
12
+
13
+ - Problems discussed
14
+ - Approaches considered
15
+ - Solutions attempted
16
+ - Final successful solution (if any)
17
+ - Other significant findings
18
+ - Links to useful references
19
+
20
+ ## Privacy
21
+
22
+ Replace `/Users/{username}/` with `~/` in file paths. Remove similar personal information.
23
+
24
+ ## Output format
25
+
26
+ The artifact begins with YAML frontmatter conforming to the canonical schema; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter) and the field-resolution steps in the [Frontmatter resolution](#frontmatter-resolution) section below.
27
+
28
+ The body following the frontmatter has this structure:
29
+
30
+ ```markdown
31
+ # {Descriptive title}
32
+
33
+ ## Problem
34
+
35
+ {What was being solved}
36
+
37
+ ## Approaches considered
38
+
39
+ {Options that were discussed}
40
+
41
+ ## Solution
42
+
43
+ {What worked - use ✅ or ❌ icons}
44
+
45
+ ## Key learnings
46
+
47
+ {Important insights - use 💡 icon}
48
+
49
+ ## References
50
+
51
+ {Useful links discovered}
52
+ ```
53
+
54
+ ## Icons
55
+
56
+ Use these to mark significant sections:
57
+
58
+ - ❌ failure
59
+ - ✅ success
60
+ - 💡 important learning: the canonical Insight icon defined in [knowledge items](../_data/artifact-conventions.md#knowledge-items)
61
+ - 🐞 buggy behavior
62
+ - 🚀 performance gain
63
+
64
+ ## Formatting
65
+
66
+ - Use proper Markdown
67
+ - Compose tight from the start ([concision principle](../_data/concision.md)): A summary is a distillation, not a transcript
68
+ - Focus on the most important findings
69
+
70
+ ## Frontmatter resolution
71
+
72
+ The artifact's frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
73
+
74
+ Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`.
75
+
76
+ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill summarize-chat --interactive true --model "{model_id}"` via Bash. Prepend the output verbatim to the artifact body.
77
+
78
+ ## Saving
79
+
80
+ Resolve artifact directory by invoking `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir`, `project_slug`, and `artifact_paths` from the manifest JSON emitted on stdout. The chats path is `artifact_paths.chats` (default: `chats`).
81
+
82
+ Full path: `{artifact_base_dir}/projects/{project_slug}/{chats_path}/`
83
+
84
+ Follow [artifact conventions](../_data/artifact-conventions.md).
85
+
86
+ Artifact type: `chat-summary`. Filename format:
87
+
88
+ ```
89
+ {YYYYMMDD}-{HHMMSS}Z_{descriptive-title}.md
90
+ ```
91
+
92
+ Example: `20250718-200926Z_fix-rating-change-does-not-trigger-flag-refresh.md`
93
+
94
+ ## Completion
95
+
96
+ Report the file path when done. That's all the user needs to know.
97
+
98
+ ## See also
99
+
100
+ For comprehensive post-session housekeeping (creating tickets for deferred items, documenting discoveries, generating devlogs in addition to chat summaries), use `{skill:wrap-up}`.