codeassembly-guidance 0.6.0 → 0.8.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 +446 -0
- package/CHANGELOG.md +107 -0
- package/README.md +47 -51
- package/bin/codeassembly-validate-preferences.js +2 -8
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/_partials/plain-speech.md +2 -2
- package/content/_partials/ticket-assessment.md +3 -3
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +6 -0
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
- package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
- package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
- package/content/guidance/shared/AGENTS.md +3 -4
- package/content/scripts/README.md +1 -1
- package/content/scripts/check-branch-currency.mjs +7 -7
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +89 -89
- package/content/scripts/manage-jira-ticket.mjs +162 -160
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +41 -41
- package/content/skills/_data/artifact-conventions.md +3 -3
- package/content/skills/_data/entry-points.md +1 -1
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/reduced-object-relatives.md +15 -0
- package/content/skills/_data/spike-conventions.md +16 -6
- package/content/skills/_data/ticket-evaluation.md +3 -0
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/merge-settled-criterion.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +2 -2
- package/content/skills/_partials/plan-template.md +3 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
- package/content/skills/analyze-performance/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +4 -4
- package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
- package/content/skills/assess-ticket/SKILL.md +3 -1
- package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
- package/content/skills/assess-usability/SKILL.md +4 -4
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +123 -123
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/condense-branch/SKILL.md +18 -36
- package/content/skills/condense-branch/condense-branch.mjs +17 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-devlog/SKILL.md +4 -4
- package/content/skills/create-gh-pr/SKILL.md +9 -11
- package/content/skills/create-pr/SKILL.md +10 -12
- package/content/skills/create-ticket/SKILL.md +22 -15
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/SKILL.md +2 -2
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
- package/content/skills/design-and-plan/SKILL.md +10 -8
- package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
- package/content/skills/implement-plan/SKILL.md +4 -2
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +2 -2
- package/content/skills/investigate-spike/SKILL.md +3 -3
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-gh-progress-items/SKILL.md +36 -0
- package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +40 -19
- package/content/skills/merge-gh-pr/SKILL.md +34 -23
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +64 -31
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +5 -3
- package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
- package/content/skills/refine-plan/SKILL.md +5 -3
- package/content/skills/refine-prototype/SKILL.md +2 -1
- package/content/skills/respond-to-review/SKILL.md +4 -4
- package/content/skills/review-bb-pr/SKILL.md +1 -2
- package/content/skills/review-branch/SKILL.md +19 -14
- package/content/skills/review-criteria/SKILL.md +2 -2
- package/content/skills/review-gh-pr/SKILL.md +1 -2
- package/content/skills/review-pr/SKILL.md +2 -3
- package/content/skills/revise-prose/revise-prose.mjs +109 -109
- package/content/skills/save-artifact/SKILL.md +4 -6
- package/content/skills/save-plan/SKILL.md +4 -2
- package/content/skills/start-ticket/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
- package/content/skills/summarize-change/SKILL.md +20 -9
- package/content/skills/summarize-chat/SKILL.md +2 -2
- package/content/skills/testing-conventions/SKILL.md +2 -2
- package/content/skills/triage-feedback/SKILL.md +6 -2
- package/content/skills/triage-spike-findings/SKILL.md +33 -24
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
- package/content/skills/update-project-guidance/SKILL.md +1 -1
- package/content/skills/wrap-up/SKILL.md +8 -4
- package/content/skills/write-progress-report/SKILL.md +111 -0
- package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
- package/content/subagents/disposition-challenger.md +7 -6
- package/content/subagents/entry-drafter.md +2 -0
- package/content/subagents/usability-assessor.md +3 -2
- package/package.json +13 -12
- package/schemas/preferences.v1.json +82 -8
- package/schemas/work-types.v1.json +1 -1
|
@@ -84,7 +84,11 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
84
84
|
3. **Compose title**: Compose the change string per [`title-voice.md`](../_data/title-voice.md).
|
|
85
85
|
- The change summary's own heading prefixes that string with the ticket reference for identification: `{ticket_ref} {title}`, or just `{title}` when `ticket_ref` is null.
|
|
86
86
|
|
|
87
|
-
4. **Compose `## Why`, and `## How to test` when the change has a surface to exercise**, 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
|
|
87
|
+
4. **Compose `## Why`, `## Notes for reviewers` when a fact passes the reader test, and `## How to test` when the change has a surface to exercise**, 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 the sections composed here with the drafted passages.
|
|
88
|
+
|
|
89
|
+
**The reader test.** The reader of a pull-request description is a reviewer who hasn't read the ticket. Each line of a section composed here must change what the reviewer checks or decides. A line fails the test when it states what the diff already shows, the author's own follow-ups or checklists, a step for the author rather than for a reviewer (such as the merge order), ownership or approval routing that tooling already reports, or the history of how the approach was chosen. The test applies to `## Why`, `## Notes for reviewers`, and `## How to test`; `## What` and `## Details` come from `entry-drafter` and follow its contract instead.
|
|
90
|
+
|
|
91
|
+
Write `## Notes for reviewers` only when a fact passes the test and the other sections do not state it; otherwise omit the section, heading included. Draw the facts from the diff, the commit bodies, and the ticket, and write each as a bullet. Such a fact explains, for example, why a consumer that the reviewer would expect to be affected is not, how the change was tested beyond what CI runs, what must happen for the change to take effect, such as a deploy or a sync, or why a test runs at an expensive tier. Add a divergence from the ticket's proposal only when it changes what a reviewer checks, and state it as the current fact rather than as a departure from the ticket.
|
|
88
92
|
|
|
89
93
|
Write `## How to test` only when the diff changes a surface that a person sees or operates: a page, a UI component, or a command's output. Otherwise omit the section, heading included. Compose it from the diff and the ticket as numbered steps, each stating where to go (the route, the page, or the command, and how to start the app when the repository does not make that obvious), what to do there, and what the reviewer should observe. Cover only what CI does not assert: Never list automated checks, such as formatting, linting, typechecking, or tests.
|
|
90
94
|
|
|
@@ -108,19 +112,20 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
108
112
|
|
|
109
113
|
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`.
|
|
110
114
|
|
|
111
|
-
6. **Audit the lede and the entries.** The first
|
|
115
|
+
6. **Audit the lede and the entries.** The first four 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 the sections that step 4 composed.
|
|
112
116
|
|
|
113
117
|
- **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`.
|
|
114
118
|
- **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.
|
|
119
|
+
- **Durability.** Read each sentence of the lede, each entry's `text`, and each `migration`, subordinate clauses included, as a reader would read it long after the merge, since the merge commit contains them permanently. A statement of the change's delivery state, such as that it has merged, been deployed, or been released, or a condition for the change to take effect, such as "once it is deployed" or "after the next release", fails the passage: `rejection: transient-state`. A condition that names a version or a configuration stays true and passes.
|
|
115
120
|
- **Voice.** A figurative verb, or an invented term when a plain one exists: `rejection: voice`.
|
|
116
121
|
- **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`.
|
|
117
|
-
- **Writing rules.** Run this check over the passages that passed every check above, and over
|
|
122
|
+
- **Writing rules.** Run this check over the passages that passed every check above, and over the sections that step 4 composed, 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, each paragraph of `## Why`, each note of `## Notes for reviewers`, and each step of `## How to test`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
|
|
118
123
|
|
|
119
124
|
```bash
|
|
120
125
|
node {harness_home_dir}/scripts/check-prose.mjs --file "{absolute path of the scratch file}" --json
|
|
121
126
|
```
|
|
122
127
|
|
|
123
|
-
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`.
|
|
128
|
+
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`. When a confirmed violation is in a section that step 4 composed, rewrite it yourself, since this session wrote it. Run the check again over every replaced passage.
|
|
124
129
|
|
|
125
130
|
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.
|
|
126
131
|
|
|
@@ -128,7 +133,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
128
133
|
|
|
129
134
|
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.
|
|
130
135
|
|
|
131
|
-
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
|
|
136
|
+
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 each section that step 4 composed at most twice for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
|
|
132
137
|
|
|
133
138
|
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.
|
|
134
139
|
- **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.
|
|
@@ -206,6 +211,12 @@ The body following the frontmatter has this structure:
|
|
|
206
211
|
Bad: "The retry helper used a fixed backoff schedule with no shared state, so concurrent requests stacked up against the upstream rate limiter."
|
|
207
212
|
Good: "Heavy-upload sessions were intermittently failing as users hit the upstream API's rate limit."}
|
|
208
213
|
|
|
214
|
+
## Notes for reviewers
|
|
215
|
+
|
|
216
|
+
{Only when a fact passes the reader test in step 4.}
|
|
217
|
+
|
|
218
|
+
- `kb sync` does not resolve wikilinks, so the stricter resolution leaves it unaffected.
|
|
219
|
+
|
|
209
220
|
## Details
|
|
210
221
|
|
|
211
222
|
### 🎉 Features
|
|
@@ -238,11 +249,11 @@ entries:
|
|
|
238
249
|
## Guidance
|
|
239
250
|
|
|
240
251
|
- 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.
|
|
241
|
-
- 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, and `## How to test`, when present, is how a reviewer exercises the change by hand
|
|
252
|
+
- 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, `## Notes for reviewers`, when present, is what a reviewer needs that the other sections do not state, `## Details` is every outcome that the change contains, and `## How to test`, when present, is how a reviewer exercises the change by hand
|
|
242
253
|
- Both `## What` and `## Details` come from the drafter, so neither is composed in this session
|
|
243
254
|
- `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
|
|
244
255
|
- Ignore auto-formatter and lint-fix changes
|
|
245
|
-
- `## What` and `## Why` are required; `## How to test`
|
|
256
|
+
- `## What` and `## Why` are required; `## Notes for reviewers` appears only when a fact passes the reader test, and `## How to test` only when the change alters a surface that a person sees or operates, per step 4
|
|
246
257
|
- The rendered `change-record` block is the body's last element, per [the change record](../_data/change-record.md)
|
|
247
258
|
|
|
248
259
|
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
@@ -308,11 +319,11 @@ When used as a PR description, include **from `## What` onward only**; omit the
|
|
|
308
319
|
|
|
309
320
|
### Path resolution
|
|
310
321
|
|
|
311
|
-
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `
|
|
322
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_dir` 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).
|
|
312
323
|
|
|
313
324
|
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
314
325
|
|
|
315
|
-
Ticket directory: `{
|
|
326
|
+
Ticket directory: `{ticket_dir}/`, or the directory that {skill:save-artifact} states when `ticket_dir` is null
|
|
316
327
|
|
|
317
328
|
Artifact type: `change-summary`. Filename format:
|
|
318
329
|
|
|
@@ -77,9 +77,9 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill summarize-chat --
|
|
|
77
77
|
|
|
78
78
|
## Saving
|
|
79
79
|
|
|
80
|
-
Resolve artifact directory by invoking `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `
|
|
80
|
+
Resolve artifact directory by invoking `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `project_artifact_dir` and `artifact_paths` from the manifest JSON emitted on stdout. The chats path is `artifact_paths.chats` (default: `chats`).
|
|
81
81
|
|
|
82
|
-
Full path: `{
|
|
82
|
+
Full path: `{project_artifact_dir}/{chats_path}/`
|
|
83
83
|
|
|
84
84
|
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
85
85
|
|
|
@@ -40,10 +40,10 @@ A test's **tier** is what it starts or builds to observe a behavior. The cheapes
|
|
|
40
40
|
- **Tier placement.** Test each case at the cheapest tier that can observe it. An expensive tier covers only what a cheaper tier cannot observe: that the entry starts, parses its arguments, wires its dependencies, and reports its exit status, with one smoke example per entry or verb. A branch of logic, a message, or a field of output is a case for the cheapest tier, even when the entry is the only caller that exercises it.
|
|
41
41
|
- **Consolidate before adding.** Write a new example only for a behavior that the existing examples cannot be extended to cover. Cases that share setup and action are one table-driven test, as [Test structure](#test-structure) states. When the examples do not mutate a fixture, build it once per file, not once per example.
|
|
42
42
|
- **Delete what is superseded, in the same change.** A higher-tier example is superseded when cheaper coverage observes each of its assertions, apart from the entry wiring that the smoke example covers. A change that adds the cheaper coverage deletes the examples that it supersedes, once the new tests pass the second check in [When tests are required](#when-tests-are-required). A port or a rewrite follows the same rule: The change that contains the port deletes the old suite rather than keeping it to catch regressions.
|
|
43
|
-
- **Justify each expensive addition.** A change that adds an example at an expensive tier states, in its plan or its pull-request description
|
|
43
|
+
- **Justify each expensive addition.** A change that adds an example at an expensive tier states, in its plan or in its pull-request description's `## Notes for reviewers`, why a cheaper tier cannot observe that example. The justification does not belong in a test comment.
|
|
44
44
|
- **Use the cheapest setup that fits.** Give an expensive tier the cheapest setup that fits its time budget, such as an in-process engine when few files need one. Add infrastructure, such as a server, a container, or a shared test package, only after a run of the suite at CI's parallelism shows that the cheaper setup does not fit.
|
|
45
45
|
- **Keep setup cost independent of the number of files.** Design expensive setup so that adding or splitting a test file does not add to it, for example by starting one engine for the suite rather than one per file.
|
|
46
|
-
- **Fix the design, not the timeout.** When a hook, a test, or a tier needs a longer timeout, in the test or in config, treat that as a sign of bad design and make it do less work: smaller data and injected dependencies, as [Test data](#test-data) states, or setup shared across files. A raised timeout hides a cost that grows with each file and with CI load. Raise one only when none of these fixes applies, and state why in the plan or the pull-request description
|
|
46
|
+
- **Fix the design, not the timeout.** When a hook, a test, or a tier needs a longer timeout, in the test or in config, treat that as a sign of bad design and make it do less work: smaller data and injected dependencies, as [Test data](#test-data) states, or setup shared across files. A raised timeout hides a cost that grows with each file and with CI load. Raise one only when none of these fixes applies, and state why in the plan or in the pull-request description's `## Notes for reviewers`, not in a test comment.
|
|
47
47
|
|
|
48
48
|
## Test data
|
|
49
49
|
|
|
@@ -61,8 +61,8 @@ node {harness_home_dir}/skills/triage-feedback/triage-feedback.mjs {command} {fl
|
|
|
61
61
|
|
|
62
62
|
### 1. Preflight
|
|
63
63
|
|
|
64
|
-
1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `
|
|
65
|
-
2. Fix the artifact's path now, because a deferral references it. The directory is `{
|
|
64
|
+
1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `ticket_dir` and `project_artifact_dir`.
|
|
65
|
+
2. Fix the artifact's path now, because a deferral references it. The directory is `{ticket_dir}/` when the manifest's `ticket_dir` is not null, and `{project_artifact_dir}/feedback-triage/` otherwise; the `feedback-triage/` name is hardcoded. The filename is `{YYYYMMDD-HHMMSSZ}_{slug}_feedback-triage.md`, with the current UTC time and a slug per {skill:save-artifact}, or `triage` when nothing else suits.
|
|
66
66
|
3. Create the work directory `{timestamp}_work/` beside the artifact, where `{timestamp}` is the filename's prefix. Every working file goes there.
|
|
67
67
|
4. Run `gh auth status`. When it fails, report that tickets cannot be filed, and continue only when the developer accepts a run that defers or rates.
|
|
68
68
|
|
|
@@ -132,4 +132,8 @@ Run `triage-feedback validate` on the final record, then `triage-feedback render
|
|
|
132
132
|
|
|
133
133
|
Report each filed ticket with its repository, each deferred or rated cluster, each declined cluster, the remainder line, and the artifact's path.
|
|
134
134
|
|
|
135
|
+
When the record names two or more filed tickets, print the list for them after the report, per [implementation-order list](#implementation-order-list). They include a ticket that an earlier run of the same record filed.
|
|
136
|
+
|
|
135
137
|
<!-- include: ../_partials/gh-body-file.md / -->
|
|
138
|
+
|
|
139
|
+
<!-- include: ../_partials/implementation-order-list.md / -->
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: triage-spike-findings
|
|
3
|
-
description: Dispose of the findings that a spike, a usability assessment, a code-health assessment, or a performance analysis left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the
|
|
3
|
+
description: Dispose of the findings that a spike, a usability assessment, a code-health assessment, or a performance analysis left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the graded tickets under an umbrella, and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Triage spike findings
|
|
8
8
|
|
|
9
|
-
Dispose of every item that a findings artifact leaves undisposed: the proposals, groupings, findings, and ideas that the filed tickets and comments did not absorb. You inventory them, recommend a disposition and two grades for each, have a {subagent:disposition-challenger} argue against every recommendation, and then, once the developer approves, create the tickets and post the record. A bundled helper checks
|
|
9
|
+
Dispose of every item that a findings artifact leaves undisposed: the proposals, groupings, findings, and ideas that the filed tickets and comments did not absorb. You inventory them, recommend a disposition and two grades for each, have a {subagent:disposition-challenger} argue against every recommendation, and then, once the developer approves, create the tickets and post the record. A bundled helper checks a GitHub repository's labels, validates the dispositions record, and renders the comments.
|
|
10
10
|
|
|
11
11
|
**Announce at start:** "Using triage-spike-findings to dispose of the findings of {source} on {ticket_ref}."
|
|
12
12
|
|
|
@@ -18,19 +18,19 @@ Dispose of every item that a findings artifact leaves undisposed: the proposals,
|
|
|
18
18
|
|
|
19
19
|
A run triages one [findings batch](../_data/spike-conventions.md#findings-batches) on one triage ticket.
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
The run supports each [triage platform](../_data/spike-conventions.md#triage-platforms), GitHub through `gh`. Step 1 resolves the platform, and every later step reads it from the record's `platform`. Each step states the GitHub path; a sentence that opens with "On Jira" states that step's Jira counterpart.
|
|
22
22
|
|
|
23
23
|
## Grades and dispositions
|
|
24
24
|
|
|
25
25
|
Each item takes a disposition and two grades:
|
|
26
26
|
|
|
27
|
-
- **Disposition**: `ticket` (a child of the umbrella), `comment` (a note on an existing issue, which must be open and must own the file or the behavior), `merge` (folded into another item's ticket; the target is a `ticket` item), or `drop`.
|
|
27
|
+
- **Disposition**: `ticket` (a new ticket, a child of the umbrella), `comment` (a note on an existing issue, which must be open and must own the file or the behavior), `merge` (folded into another item's ticket; the target is a `ticket` item), or `drop`.
|
|
28
28
|
|
|
29
29
|
<!-- include: ../../_partials/finding-grades.md / -->
|
|
30
30
|
|
|
31
|
-
The helper refuses a record that gives a `low` item a ticket. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child.
|
|
31
|
+
The helper refuses a record that gives a `low` item a ticket. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child on GitHub.
|
|
32
32
|
|
|
33
|
-
The labels come from the common preset of `release-kit sync-labels`: the `value:` family, and the `confidence:` family that williamthorsen/node-monorepo-tools#1017 added. A repository whose labels lack either family cannot take the children, because `gh issue create` fails on a label that the repository does not have.
|
|
33
|
+
The labels come from the common preset of `release-kit sync-labels`: the `value:` family, and the `confidence:` family that williamthorsen/node-monorepo-tools#1017 added. A repository whose labels lack either family cannot take the children, because `gh issue create` fails on a label that the repository does not have. On Jira, the run does not read or set any label: Jira does not have the two families, and on some sites labels are one namespace shared by every project. Each child's grade line, which step 6 composes, records its grades in their place.
|
|
34
34
|
|
|
35
35
|
## Process
|
|
36
36
|
|
|
@@ -44,13 +44,14 @@ Resolve `{ticket_dir}` per {skill:save-artifact}, and write every working file u
|
|
|
44
44
|
|
|
45
45
|
### 1. Preflight
|
|
46
46
|
|
|
47
|
-
1.
|
|
48
|
-
2.
|
|
49
|
-
3.
|
|
47
|
+
1. Resolve the platform as {skill:create-ticket} step 3 resolves it: from the integrations that `.agents/preferences.yaml` enables, then from the git remote. The session-context manifest's `scm` names the code host, which does not decide where the tickets live. On a platform that is not a [triage platform](../_data/spike-conventions.md#triage-platforms), stop and report that the skill does not support it.
|
|
48
|
+
2. On GitHub, run `gh auth status` and `gh repo view --json nameWithOwner`. If either fails, stop and report why. Then run the helper's `check-labels`. When `complete` is false, stop: Name each missing label, and state that the common preset of `release-kit sync-labels` supplies both families (the `confidence:` family from williamthorsen/node-monorepo-tools#1017), so the repository takes them by upgrading release-kit and regenerating its label file rather than by creating them by hand.
|
|
49
|
+
3. On Jira, identify the client per {skill?:update-jira-ticket}. When it is `acli`, run that skill's site check against the triage ticket's URL, or against `ticket.base_url` when the URL is not known. Read the triage ticket through the client, and stop when no client can read it.
|
|
50
|
+
4. Create `{ticket_dir}/triage/`, and save the findings there when they came from a URL.
|
|
50
51
|
|
|
51
52
|
### 2. Inventory
|
|
52
53
|
|
|
53
|
-
Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues, found with `gh issue list --search` and read with their comments per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch)
|
|
54
|
+
Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues, found with `gh issue list --search` and read with their comments per [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch). On Jira, search the triage ticket's project with `acli jira workitem search --jql 'project = {project key} AND statusCategory != Done AND text ~ "{terms}"' --json --paginate`, or with the search of the connected client, and read each match with its comments per the same section's Jira fetch. The finding may describe a problem that a merge has since fixed, a decision that the repository records, or work that an open issue already covers.
|
|
54
55
|
|
|
55
56
|
Write `inventory.md` as a table: the item's id (the artifact's own id when it has one), its title, where it appears in the artifact, the verification outcome (holds, partly holds, or does not hold, with the evidence), and, when the findings give the item an evidence key and the paths that it covers, that key and those paths, copied verbatim. Give an item that the artifact does not identify an id of the inventory's own, so that a follow-up triage ticket can name it.
|
|
56
57
|
|
|
@@ -58,7 +59,7 @@ When the inventory holds more items than the batch ceiling, split it into batche
|
|
|
58
59
|
|
|
59
60
|
### 3. Recommend
|
|
60
61
|
|
|
61
|
-
Write `recommendations.md`: one line per item, with its id, title, disposition, confidence, value, and a one-sentence reason. Nothing else goes in the file, because the challenger reads it and a sentence of your reasoning there would bias its judgment toward yours. A `merge` names a `ticket` item as its target; a `comment` names its issue number.
|
|
62
|
+
Write `recommendations.md`: one line per item, with its id, title, disposition, confidence, value, and a one-sentence reason. Nothing else goes in the file, because the challenger reads it and a sentence of your reasoning there would bias its judgment toward yours. A `merge` names a `ticket` item as its target; a `comment` names its issue number, or its key on Jira.
|
|
62
63
|
|
|
63
64
|
### 4. Challenge
|
|
64
65
|
|
|
@@ -66,6 +67,7 @@ Send one {tool:Task} call, `subagent_type: disposition-challenger`, with this bl
|
|
|
66
67
|
|
|
67
68
|
```dispatch
|
|
68
69
|
findings: {ticket_dir}/triage/findings.md
|
|
70
|
+
platform: {the platform from step 1}
|
|
69
71
|
recommendations: {ticket_dir}/triage/recommendations.md
|
|
70
72
|
root: {repository root}
|
|
71
73
|
```
|
|
@@ -74,9 +76,9 @@ root: {repository root}
|
|
|
74
76
|
|
|
75
77
|
Save the reply as `challenge.md`. Then take each item in turn: Defend the recommendation when the argument fails on the evidence, modify it when the argument stands in part, and abandon it when the argument stands. A defense answers the argument on the evidence that the argument names; a defense that rests on other grounds fails. An argument that lowers the grade of a code-health item on the one-time cost of the change fails under the grade definitions above, even when the challenger raises it.
|
|
76
78
|
|
|
77
|
-
Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. Record every such dependency in `blockedBy`, never in `notes`.
|
|
79
|
+
Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. On Jira, a blocker outside the triage is a work item, by key; read its status with `acli jira workitem view {key} --json --fields status`, and omit one whose status category is `done`. Record every such dependency in `blockedBy`, never in `notes`.
|
|
78
80
|
|
|
79
|
-
Write `dispositions.json` in the helper's record shape: `source` (the findings as given), `triageTicket
|
|
81
|
+
Write `dispositions.json` in the helper's record shape: `platform` (`github` or `jira`, from step 1), `source` (the findings as given), `triageTicket` (its number, or its key on Jira), `umbrella: null`, `items`, `challengeSummary` (what the challenge refuted or narrowed and what it did not), and `notes` (the lines of the comment's "Labels and follow-ups" section, "Follow-ups" on Jira, empty when there are none). Each item has `id`, `title`, `disposition`, `confidence`, `value`, `reason`, `target` (the issue of a `comment`, the target id of a `merge`, null otherwise), `ticket: null`, `blockedBy` on a `ticket` item that has blockers (item ids, and issue numbers or keys), `evidence` with `key` and `paths` on an item whose inventory row has them (omitted otherwise), and `challenge` with `argument`, `outcome` (`defended`, `modified`, or `abandoned`), and `note`. When any item has `evidence`, write the output of `git rev-parse HEAD` into the record's `commit`. Run the helper's `validate`, which reports every schema and gate violation at once, a cycle among the blockers included, and fix the record until it passes.
|
|
80
82
|
|
|
81
83
|
### 5. Checkpoint: The dispositions
|
|
82
84
|
|
|
@@ -88,22 +90,22 @@ Present the dispositions as a table (item, disposition, confidence, value, block
|
|
|
88
90
|
|
|
89
91
|
Compose the bodies:
|
|
90
92
|
|
|
91
|
-
- **The umbrella**, when at least one item is a `ticket`: its problem (the follow-up work of the findings), its context (a link to the triage ticket, and the tickets that the findings filed without adopting them, listed and not made children), and "Every child is closed" as its acceptance criterion. It does not take a graded label.
|
|
92
|
-
- **One child per `ticket` item**, in the ticket skeleton that {skill:create-ticket} step 2 states: problem, context, and acceptance criteria, with the title and reason of every `merge` item that targets it folded in. Its labels are `confidence:{grade}` and `value:{grade}`.
|
|
93
|
-
- **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked:
|
|
93
|
+
- **The umbrella**, when at least one item is a `ticket`: its problem (the follow-up work of the findings), its context (a link to the triage ticket, and the tickets that the findings filed without adopting them, listed and not made children), and "Every child is closed" as its acceptance criterion. It does not take a graded label or any blocker, and it does not have a parent.
|
|
94
|
+
- **One child per `ticket` item**, in the ticket skeleton that {skill:create-ticket} step 2 states: problem, context, and acceptance criteria, with the title and reason of every `merge` item that targets it folded in. Its labels are `confidence:{grade}` and `value:{grade}`. On Jira, it does not take any label. Its parent is the umbrella. Its `## Context` links the triage ticket, and that section's last line is its grade line: `Triage grades: confidence {confidence}, value {value}`.
|
|
95
|
+
- **One follow-up triage ticket per later batch**, when the **Batches** table has more than one row: titled `Triage batch {n} of {findings title}`, with a link to the findings artifact, its path written `~/`-relative as in the [closing post](../_data/spike-conventions.md#closing-post), a link to the triage ticket, whose dispositions comment records the earlier round, the batch's items by id and title as its **The batch** input, and `triage-spike-findings` as its next step. Read the triage ticket's parent with `gh issue view {triage ticket} --json parent`, or on Jira with `acli jira workitem view {triage ticket} --json --fields parent`: A follow-up takes that parent when there is one, so that it sits beside its siblings, and no parent otherwise. Each follow-up is blocked by the one before it. The first is not blocked: This round's dispositions are posted before the next round starts. Add one line per follow-up to the record's `notes`, `Batch {n} ({item ids}) is triaged in {follow-up}`, with the follow-up's title in place of `{follow-up}` until step 7 creates it, so that the dispositions comment names every follow-up.
|
|
94
96
|
|
|
95
97
|
Run the helper's `render --preview` to `{ticket_dir}/triage/preview/`, which writes the dispositions comment with `(pending)` where a number is not yet known, and one comment file per issue that a `comment` disposition names.
|
|
96
98
|
|
|
97
|
-
Show everything that step 7 will create or post in one block: every body with its title and labels, the parent relationship and the blockers of each child and each follow-up, every per-issue comment with its issue, and the
|
|
99
|
+
Show everything that step 7 will create or post in one block: every body with its title and labels, the parent relationship and the blockers of each child and each follow-up, every per-issue comment with its issue, the dispositions comment, and, on a run given **The batch**, the close of the triage ticket as completed. Confirm once in the action-items block. This confirmation is the only one: {skill:create-ticket} does not re-confirm a relationship given as an argument.
|
|
98
100
|
|
|
99
101
|
### 7. Write
|
|
100
102
|
|
|
101
103
|
Nothing before this step writes anything remote. On a failed write, stop and report which item failed; every number already recorded stays in `dispositions.json`, so that a re-run of this step creates only what is still null and checks each issue before posting on it.
|
|
102
104
|
|
|
103
|
-
1. When
|
|
104
|
-
2. For each `ticket` item, in the order that `validate` reports as `order` for the approved record, run {skill:create-ticket} with `--parent {umbrella}` and `--label confidence:{grade},value:{grade}`, adding `--blocked-by` with the item's blockers as `#{number}` (the recorded `ticket` of each item id, and each issue number) when it has any, and write the returned number into the item's `ticket` as soon as it is returned. Because `order` places every blocker first, each item id that `--blocked-by` names already has its
|
|
105
|
-
3. For each `ticket` item, read `gh issue view {ticket} --json parent,blockedBy`, and add what is missing in one `gh issue edit {ticket} --parent {umbrella} --add-blocked-by {numbers}` call, omitting a flag that has nothing to add. {skill:create-ticket} sets the parent and the blockers in one call, so a rejected blocker can drop the parent as well, and this read-back is how a failed link is found. On a re-run, it completes the links of the items that an earlier run created.
|
|
106
|
-
4. For each later batch, in batch order, skip the batch when its follow-up ticket is already recorded in the **Batches** table. Otherwise create its follow-up with {skill:create-ticket}, adding `--parent` and `--blocked-by` as step 6 composed them, and as soon as the number is returned, write it into the table and replace the follow-up's title with `#{number}
|
|
105
|
+
1. When `validate` reports the umbrella missing, create it with {skill:create-ticket} and `--umbrella`, which on Jira creates it at the issue type that Jira accepts as its children's parent, and write its number, or its key on Jira, into `umbrella`. The umbrella is missing only while a `ticket` item lacks its ticket, so a re-run of a record whose children were all created without one does not create it.
|
|
106
|
+
2. For each `ticket` item, in the order that `validate` reports as `order` for the approved record, run {skill:create-ticket} with `--parent {umbrella}` and `--label confidence:{grade},value:{grade}`, adding `--blocked-by` with the item's blockers as `#{number}` (the recorded `ticket` of each item id, and each issue number) when it has any, and write the returned number into the item's `ticket` as soon as it is returned. On Jira, pass `--parent {umbrella}` with the umbrella's key, `--blocked-by` with the blockers' keys, never `--label`, and write the returned key into `ticket`. Because `order` places every blocker first, each item id that `--blocked-by` names already has its ticket.
|
|
107
|
+
3. For each `ticket` item, read `gh issue view {ticket} --json parent,blockedBy`, and add what is missing in one `gh issue edit {ticket} --parent {umbrella} --add-blocked-by {numbers}` call, omitting a flag that has nothing to add. {skill:create-ticket} sets the parent and the blockers in one call, so a rejected blocker can drop the parent as well, and this read-back is how a failed link is found. On a re-run, it completes the links of the items that an earlier run created. On Jira, read `acli jira workitem view {ticket} --json --fields parent,issuelinks`, read the blockers as [open blockers](../_data/ticket-source-resolution.md#open-blockers) reads them on Jira, and add each missing one with `acli jira workitem link create --out {ticket} --in {blocker} --type Blocks --yes`. `acli` cannot set a parent after creation: When {skill:create-ticket} reported `parentSkipped` or the read-back does not show the composed parent, add the line `{ticket} does not have its parent {parent}` to `notes`, so that the dispositions comment records it.
|
|
108
|
+
4. For each later batch, in batch order, skip the batch when its follow-up ticket is already recorded in the **Batches** table. Otherwise create its follow-up with {skill:create-ticket}, adding `--parent` and `--blocked-by` as step 6 composed them, and as soon as the number is returned, write it into the table and replace the follow-up's title with `#{number}`, or with its key on Jira, in its `notes` line.
|
|
107
109
|
5. Run the helper's `render` to `{ticket_dir}/triage/rendered/`, without `--preview`.
|
|
108
110
|
6. Post each `comment-{issue}.md` on its issue, and then `dispositions-comment.md` on the triage ticket. Before each post, read the issue's comments with `gh issue view {issue} --json comments`, and skip the post when a comment already opens with the first line of the rendered file:
|
|
109
111
|
|
|
@@ -115,13 +117,18 @@ Nothing before this step writes anything remote. On a failed write, stop and rep
|
|
|
115
117
|
|
|
116
118
|
Keep the URL that `gh issue comment` prints for the dispositions comment; when the post was skipped, keep the `url` of the matching comment instead. Step 8 links it.
|
|
117
119
|
|
|
118
|
-
|
|
120
|
+
On Jira, post through the client that {skill?:update-jira-ticket} names. With `acli`, convert each rendered file to ADF with that skill's `convert-body` call, read `acli jira workitem comment list --key {key} --json --paginate`, which prints one JSON object per page and each comment's `body` as plain text, and skip the post when a body, with its whitespace collapsed, opens with the rendered file's first line without its Markdown markers, such as the `## ` of the dispositions heading. Otherwise, post with `acli jira workitem comment create --key {key} --body-file {ADF path}`. For the dispositions comment, keep `{site}/browse/{triage ticket}?focusedCommentId={id}`, taking the comment's `id` from the comment list, read again after a post.
|
|
121
|
+
|
|
122
|
+
7. On a run given **The batch**, close the triage ticket without a closing post, because its dispositions comment is its record: Read `gh issue view {triage ticket} --json state`, and run `gh issue close {triage ticket} --reason completed` only while the state is `OPEN`. On Jira, run `node {harness_home_dir}/scripts/manage-jira-ticket.mjs close --key {triage ticket}` without `--post`; it transitions the ticket only while its status category is not `done`.
|
|
123
|
+
8. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
|
|
119
124
|
|
|
120
125
|
### 8. Report
|
|
121
126
|
|
|
122
|
-
Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each follow-up triage ticket with its batch, each issue commented on,
|
|
127
|
+
Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each Jira child whose parent was not set, each follow-up triage ticket with its batch, each issue commented on, the close of the triage ticket on a run given **The batch**, and the artifact's path.
|
|
128
|
+
|
|
129
|
+
When the record names two or more tickets among the children and the follow-up triage tickets, print the list for them after the report, per [implementation-order list](#implementation-order-list), leaving out the umbrella. They include a ticket that an earlier run of the same record created.
|
|
123
130
|
|
|
124
|
-
The triage round ends the spike, so offer the [closing post](../_data/spike-conventions.md#closing-post)
|
|
131
|
+
The triage round ends the spike, so offer to close the triage ticket with the [closing post](../_data/spike-conventions.md#closing-post) in the same response's action-items block, showing the post's body, and on consent post it and close the ticket with that section's checks. When the developer declines the offer, the triage ticket stays open. Do not offer it when the run was given **The batch**: A follow-up triage ticket's dispositions comment is its record, and step 7 has closed the ticket. The post contains:
|
|
125
132
|
|
|
126
133
|
- The answer to each question to answer and the recommendation on each decision to enable that the triage ticket's body lists, taken from the findings and the approved dispositions. A body that lists neither leaves the post with the items below alone.
|
|
127
134
|
- The count of items by disposition.
|
|
@@ -130,3 +137,5 @@ The triage round ends the spike, so offer the [closing post](../_data/spike-conv
|
|
|
130
137
|
It does not repeat the dispositions, which the dispositions comment records.
|
|
131
138
|
|
|
132
139
|
<!-- include: ../_partials/gh-body-file.md / -->
|
|
140
|
+
|
|
141
|
+
<!-- include: ../_partials/implementation-order-list.md / -->
|