codeassembly-guidance 0.0.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,317 @@
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 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
+ - **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. Step 6's writing-rules check reads `## Why` with the drafted passages.
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, after its entry's type and a colon when it is an entry's text}
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. 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
+
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, 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
+
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
+ - **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 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:
116
+
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.
126
+
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.
128
+
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.
130
+
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.
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.
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.
134
+ - **Consolidate the entries:**
135
+
136
+ ```bash
137
+ entries_path="{absolute path from the write step}"
138
+ node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file "$entries_path"
139
+ ```
140
+
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.
142
+
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.
144
+
145
+ 8. **Render `## Details`** from the entries file that step 7 wrote:
146
+
147
+ ```bash
148
+ entries_path="{absolute path from step 7}"
149
+ node {harness_home_dir}/scripts/describe-change.mjs render-details --entries-file "$entries_path" \
150
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('details',''))"
151
+ ```
152
+
153
+ [`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.
154
+
155
+ 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.
156
+
157
+ 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.
158
+
159
+ 10. **Render the `change-record` block** and make it the body's last element:
160
+
161
+ ```bash
162
+ entries_path="{absolute path from step 7}"
163
+ node {harness_home_dir}/scripts/describe-change.mjs render-block \
164
+ --title "{title}" \
165
+ --override-scope "{override_scope}" \
166
+ --override-type "{override_type}" \
167
+ --override-breaking \
168
+ --entries-file "$entries_path" \
169
+ --entries-commit "{the short SHA from step 7}" \
170
+ | python3 -c "import sys,json; print(json.load(sys.stdin).get('block',''))"
171
+ ```
172
+
173
+ 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`.
174
+
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.
176
+
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.
178
+
179
+ 11. **Save** per the [Saving](#saving) section.
180
+
181
+ If expected information is missing, stop and ask the developer.
182
+
183
+ ## Work type test
184
+
185
+ <!-- include: ../../_partials/work-type-choice.md / -->
186
+
187
+ ## Output format
188
+
189
+ 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.
190
+
191
+ The body following the frontmatter has this structure:
192
+
193
+ ````markdown
194
+ # {ticket_ref} {title}
195
+
196
+ ## What
197
+
198
+ {The drafter's lede.}
199
+
200
+ ## Why
201
+
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.
203
+
204
+ Bad: "The retry helper used a fixed backoff schedule with no shared state, so concurrent requests stacked up against the upstream rate limiter."
205
+ Good: "Heavy-upload sessions were intermittently failing as users hit the upstream API's rate limit."}
206
+
207
+ ## Details
208
+
209
+ ### 🎉 Features
210
+
211
+ - Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store. #agents, #kb
212
+ - Adds `visibility` to `.kb/config.yaml`, taking `shared` or `private`. #agents
213
+
214
+ ### 🐛 Bug fixes
215
+
216
+ - 🚨 **Breaking:** Stops `kb check` resolving a bare wikilink against every store. #kb
217
+ - Migration: Qualify each wikilink that names a note outside its own store as `[[store:Note title]]`.
218
+
219
+ ```change-record
220
+ title: Add the store-qualified wikilink
221
+ entries_commit: e5029924
222
+ entries:
223
+ - type: feat
224
+ scopes: [agents, kb]
225
+ text: Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store.
226
+ ```
227
+ ````
228
+
229
+ ## Guidance
230
+
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.
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
233
+ - Both `## What` and `## Details` come from the drafter, so neither is composed in this session
234
+ - `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
235
+ - Ignore auto-formatter and lint-fix changes
236
+ - `## What` and `## Why` are required
237
+ - The rendered `change-record` block is the body's last element, per [the change record](../_data/change-record.md)
238
+ - Never list automated checks (formatting, linting, typechecking, unit tests) in a test plan. They run automatically in CI.
239
+
240
+ <!-- include: ../../_partials/prose-line-breaks.md / -->
241
+
242
+ <!-- include: ../_partials/nested-list-indent.md / -->
243
+
244
+ ## Frontmatter inference
245
+
246
+ 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.
247
+
248
+ The block is structured as:
249
+
250
+ 1. `provenance:` block (canonical nested fields: `skill`, `timestamp`, `baseSha`, `isInteractive`, `model`).
251
+ 2. Top-level canonical fields: `branch`, `commit`, `pr`, `ticket_id`, `ticket_ref`, `run_id`.
252
+ 3. Consumer extensions: `title`, `scope`, `type`, `breaking`, `changes`, `ticket_type`, `override_scope`, `override_type`, `override_breaking`.
253
+
254
+ ### Canonical-field resolution
255
+
256
+ 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`.
257
+
258
+ 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`:
259
+
260
+ ```bash
261
+ consolidation_path="{absolute path of the step-2 consolidation file}"
262
+ changes=()
263
+ if [ -s "$consolidation_path" ]; then
264
+ while IFS= read -r change; do changes+=(--extra-list-item "changes=$change"); done < <(jq -r '.entries[].change' "$consolidation_path")
265
+ fi
266
+ {harness_home_dir}/scripts/resolve-frontmatter.sh \
267
+ --skill summarize-change \
268
+ --interactive true \
269
+ --model "{model_id}" \
270
+ --extra "title={title}" \
271
+ --extra "scope={scope}" \
272
+ --extra "type={type}" \
273
+ --extra "breaking=true" \
274
+ "${changes[@]}" \
275
+ --extra "ticket_type={ticket_type}" \
276
+ --extra "override_scope={override_scope}" \
277
+ --extra "override_type={override_type}" \
278
+ --extra "override_breaking=true"
279
+ ```
280
+
281
+ 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`.
282
+
283
+ Prepend the script's output verbatim to the artifact body.
284
+
285
+ ### Consumer fields
286
+
287
+ - **`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.
288
+ - **`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.
289
+ - **`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.
290
+ - **`ticket_type`**: The step-2 `ticket_type`, absent if it is `null` or unresolved.
291
+ - **`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`.
292
+
293
+ A skill that needs the effective record reads it from [`resolve-effective-record`](../_data/title-templates.md#resolve-effective-record), run on these fields.
294
+
295
+ ## As a PR description
296
+
297
+ When used as a PR description, include **from `## What` onward only**; omit the H1 title and metadata block.
298
+
299
+ ## Saving
300
+
301
+ ### Path resolution
302
+
303
+ 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).
304
+
305
+ Follow [artifact conventions](../_data/artifact-conventions.md).
306
+
307
+ Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
308
+
309
+ Artifact type: `change-summary`. Filename format:
310
+
311
+ ```
312
+ {timestamp}_{slug}_change-summary.md
313
+ ```
314
+
315
+ Example: `20250121-1530Z_auto-share-exception_change-summary.md`
316
+
317
+ <!-- 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}`.