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.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- 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}`.
|