codeassembly-guidance 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +757 -0
- package/CHANGELOG.md +181 -0
- package/README.md +125 -95
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +2 -2
- package/content/_partials/code-style.md +1 -1
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +11 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
- package/content/guidance/rulebooks/commit-conventions.md +2 -2
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/shared/AGENTS.md +8 -0
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +97 -97
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/artifact-conventions.md +46 -14
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/design-priorities.md +3 -3
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +1 -1
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +19 -11
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +10 -10
- package/content/skills/_partials/next-steps-after-review.md +9 -9
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +5 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/capture-event/SKILL.md +2 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +24 -9
- package/content/skills/create-pr/SKILL.md +5 -5
- package/content/skills/create-ticket/SKILL.md +61 -16
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
- package/content/skills/design-and-plan/SKILL.md +13 -10
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +25 -21
- package/content/skills/index-prototypes/SKILL.md +85 -30
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +2 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +3 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
- package/content/skills/kb-retrieve-events/SKILL.md +1 -1
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
- package/content/skills/kb-update-events/SKILL.md +2 -2
- package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +4 -2
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +2 -0
- package/content/skills/streamline-guidance/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +22 -13
- package/content/skills/testing-conventions/SKILL.md +74 -7
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +2 -2
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +15 -11
- package/schemas/preferences.v1.json +29 -2
- package/schemas/work-types.v1.json +1 -1
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -78,13 +78,13 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
78
78
|
|
|
79
79
|
Omit each flag whose field is absent, and pass `--breaking` and `--override-breaking` only if that field is `true`. The effective type is the output's `effective_record.type`; [`resolve-effective-record`](../_data/title-templates.md#resolve-effective-record) states the output. If the call fails, relay its error and continue without an effective type.
|
|
80
80
|
|
|
81
|
-
- **Type the change from the diff.** Apply [Work type test](#work-type-test) to the diff and resolve the type from that, whatever the consolidated record and `ticket_type` name. Agreement between the two is not evidence: The commits are often typed from the ticket's label, so one misclassification
|
|
81
|
+
- **Type the change from the diff.** Apply [Work type test](#work-type-test) to the diff and resolve the type from that, whatever the consolidated record and `ticket_type` name. Agreement between the two is not evidence: The commits are often typed from the ticket's label, so one misclassification appears in both. When the test's type differs from the effective type, set `override_type` to it and re-run `resolve-effective-record`. A type that the developer passed as `--type` stands: Leave `override_type` as given, and state the test's disagreement in one line. Decide the type here and state it in one line with its reason. Decide a close call by applying the test further and picking, never by asking: The pull-request body and the pre-merge commit show the resolved type before anything publishes. Resolve here rather than later, since the lede's tier in step 5 follows the type. The frontmatter records `override_type` beside the consolidated `type` and `ticket_type`.
|
|
82
82
|
- **Check the breaking policy.** Report each `policy-violation` in the last run's `defects`, such as the one that a `refactor` override on a breaking consolidated record produces, and change nothing.
|
|
83
83
|
|
|
84
84
|
3. **Compose title**: Compose the change string per [`title-voice.md`](../_data/title-voice.md).
|
|
85
85
|
- The change summary's own heading prefixes that string with the ticket reference for identification: `{ticket_ref} {title}`, or just `{title}` when `ticket_ref` is null.
|
|
86
86
|
|
|
87
|
-
4. **Compose `## Why`** per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8.
|
|
87
|
+
4. **Compose `## Why`** per the output format below. `## What` and `## Details` both come from what step 5 draws, so neither exists until step 8. Step 6's writing-rules check reads `## Why` with the drafted passages.
|
|
88
88
|
|
|
89
89
|
5. **Draft the lede and the entries via `entry-drafter`**: Resolve the tier by looking up the effective type from step 2 in [work-types.json](../_data/work-types.json); if there is none, use `internal`. Then dispatch the `{subagent:entry-drafter}` subagent via the {tool:Task} tool with this block:
|
|
90
90
|
|
|
@@ -99,28 +99,37 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
99
99
|
**A redispatch includes the passages that failed, in a fence below the block.** Step 6 decides which:
|
|
100
100
|
|
|
101
101
|
```rejected
|
|
102
|
-
- {the first passage that failed}
|
|
102
|
+
- {the first passage that failed, after its entry's type and a colon when it is an entry's text}
|
|
103
103
|
```
|
|
104
104
|
|
|
105
|
-
Copy each passage character for character from the draft from which it came, one per line, and send only the passages that failed: The drafter cannot change a passage that it never sees, which keeps one that passed from coming back changed. Send the lede the same way if it is what failed. The fence contains the lede, an entry's `text`, or an entry's `migration`, so the drafter returns one replacement passage per passage sent, in the order sent; put each in the place of the passage that it replaces and keep every other field of that entry, so that a replaced `text` keeps the entry's `migration` and a replaced `migration` keeps its `text`. Take the lede and every other entry from the draft unchanged. If the return contains a different number of passages than you sent, none of them can be placed: Redispatch with `rejection: unmatched-return`, which counts against the two redispatches that step 6 allows and exits as step 6 does.
|
|
105
|
+
Copy each passage character for character from the draft from which it came, one per line, and send only the passages that failed: The drafter cannot change a passage that it never sees, which keeps one that passed from coming back changed. Send the lede the same way if it is what failed. Put an entry's `text` after the entry's `type` as step 6 left it, as `{type}: {passage}`, whatever the rejection code; send the lede and a `migration` bare, since neither takes a type's form. The supplied type overrides the type implied by the commit log, and it is the only way that the drafter's fresh context learns a type corrected by step 6. The fence contains the lede, an entry's `text`, or an entry's `migration`, so the drafter returns one replacement passage per passage sent, in the order sent; put each in the place of the passage that it replaces and keep every other field of that entry, so that a replaced `text` keeps the entry's `migration` and a replaced `migration` keeps its `text`. Take the lede and every other entry from the draft unchanged. If the return contains a different number of passages than you sent, none of them can be placed: Redispatch with `rejection: unmatched-return`, which counts against the two redispatches that step 6 allows and exits as step 6 does.
|
|
106
106
|
|
|
107
107
|
On a first dispatch, take the drafter's `## Lede` section as it stands; step 9 makes it `## What`, and later steps do not rewrite it. A redispatch returns every replacement under `## Entries` and does not return a `## Lede` section at all, so the lede that it keeps is whichever text the placement above left in the lede's place. Parse the `## Entries` fence as YAML. Each entry declares `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry calls for one. Read the `## Report` for any source that the drafter could not access. Step 6 checks each entry's `type`.
|
|
108
108
|
|
|
109
|
-
6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected.
|
|
109
|
+
6. **Audit the lede and the entries.** The first three checks apply to the lede, to each entry's `text`, and to each entry's `migration` alike, except as the subject check states, and each names the rejection code that its failure raises, for which a redispatch is the repair rather than an edit of your own. The type check applies to each entry, and raises its code against the entry's `text` alone. `scopes` and `breaking` are not prose and are never rejected; `type` is corrected by the type check and never rejected. The writing-rules check runs last, and it also reads `## Why`.
|
|
110
110
|
|
|
111
|
-
- **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
|
|
111
|
+
- **Verification.** Read the lede, each entry's `text`, and each `migration` against the diff from step 2. Strike a claim that the diff contradicts, and correct one that it states differently. Never add: A fact omitted from the draft was left out by the reader of the change, and supplying it here restores the weighting that the fresh-context dispatch removed. The drafter read the diff, so this check no longer supplies the draft's grounding; it catches a sentence claiming more than the diff supports, such as one that only the commit log, the ticket, or this session supports, which the diff does not contradict and which is not one to strike: `rejection: unsupported-claim`.
|
|
112
112
|
- **Subject.** Read the lede's each sentence, and each entry's `text`, with "This pull request" in front of it. If that sentence is false, the verb names what the system does rather than what the change did: `rejection: subject`. This check fails most often on a change that adds something which itself acts, such as a command, a check, a rule, or a hook, because the added thing's behavior is true, interesting, and reads as a correct entry while standing in for the change. A `migration` is exempt: It is an imperative addressed to the consumer, not a sentence whose subject is the pull request.
|
|
113
113
|
- **Voice.** A figurative verb, or an invented term when a plain one exists: `rejection: voice`.
|
|
114
|
-
- **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination by a test
|
|
114
|
+
- **Type.** Apply [Work type test](#work-type-test) to the entry's outcome. When the test's type differs from the drafted `type`, or the drafted `type` does not name a key in [work-types.json](../_data/work-types.json), set `type` to the test's result and state the correction in one line with its reason. A type is a determination that you make by applying a test, not prose, so the correction is never a redispatch and never an ask. The entry's `text` is prose: When it is still written in the form that the replaced type takes, such as a `fix` entry's opening on an entry now typed `feat`, that passage fails: `rejection: type-mismatch`.
|
|
115
|
+
- **Writing rules.** Run this check over the passages that passed every check above, and over `## Why`, so that a redispatch names one code. Write them to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `prose-check-{timestamp}.md`, as bare paragraphs separated by blank lines, without headings or list markers: the lede, each entry's `text` and each `migration` as paragraphs of their own, and each paragraph of `## Why`. Write it with a file-writing tool rather than a shell heredoc, as step 7 does. Then run:
|
|
115
116
|
|
|
116
|
-
|
|
117
|
+
```bash
|
|
118
|
+
node {harness_home_dir}/scripts/check-prose.mjs --file "{absolute path of the scratch file}" --json
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
The helper runs every `revise-prose` detector over the file, reading it as Markdown, and prints one JSON document, `{ file, rules, candidates }`, in which each candidate names its `rule` and the `sentence` that contains the site. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or when it cannot read the file. Read exit 1 as candidates found, not as a failure. Map each candidate to its passage by its `sentence`, and to every passage containing that sentence when more than one does. Judge each against the rule that it names, as your plain-speech and writing guidance states that rule; a watchlist word used in the sense that names its relation, such as a promise that holds, is not a violation. State a candidate judged legitimate in one line with its reason. A confirmed violation in the lede, an entry's `text`, or a `migration` fails that passage: `rejection: writing-rule`. Rewrite a confirmed violation in `## Why` yourself, since this session wrote it. Run the check again over every replaced passage.
|
|
122
|
+
|
|
123
|
+
If the helper is unavailable or the call fails, relay its error, say that the summary was saved without the writing-rules check, and continue.
|
|
124
|
+
|
|
125
|
+
Striking and correcting a sentence, and correcting an entry's `type`, are the whole of your authority over the drafted passages. Every other failure is a redispatch, never an edit. Do not rewrite the prose yourself: The draft came from a fresh context for the same reason this audit is mechanical, and rewriting it here restores the weighting that the dispatch removed.
|
|
117
126
|
|
|
118
127
|
Repeat step 5 with `rejection:` set to the code that the failed check names, and with the passages that failed in the `rejected` fence that step describes.
|
|
119
128
|
|
|
120
|
-
Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer.
|
|
129
|
+
Redispatch at most twice. After a second redispatch fails, the passages still failing are the ones that you last sent. Present those to the developer with the code, and ask for a replacement or for an explicit acceptance of each passage as it stands; place the answer, then continue to step 7 with the verified entries. If you could never place a return, show the developer each passage as the fence contained it. Take a passage rejected by the audit past step 6 only after asking the developer. Rewrite `## Why` at most twice for the writing-rules check; a confirmed violation that remains after the second rewrite goes to the developer the same way.
|
|
121
130
|
|
|
122
131
|
7. **Consolidate the change's record from the entries.** Do this before step 8, and before the frontmatter call: Step 8 reads the entries file that this step writes, and the title and the labels read the record that it produces.
|
|
123
|
-
- **Write the verified entries** to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `entries-{timestamp}.yaml`. The file is a top-level YAML list of mappings, one per entry, each declaring `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry has one, as the drafter returned them, with the corrections that step 6 made. Write each `text` and `migration` double-quoted, and quote any value that
|
|
132
|
+
- **Write the verified entries** to a scratch file, created per the path rules of [gh body file](#gh-body-file) and named `entries-{timestamp}.yaml`. The file is a top-level YAML list of mappings, one per entry, each declaring `type`, `scopes`, `breaking`, and `text`, and `migration` when the entry has one, as the drafter returned them, with the corrections that step 6 made. Write each `text` and `migration` double-quoted, and quote any value that the drafter returned unquoted: Unquoted, a space followed by `#` opens a YAML comment, and the parse drops the rest of the text. Write it with a file-writing tool rather than a shell heredoc: `text` and `migration` are arbitrary prose containing backticks and quotes. Keep its path; steps 8 and 10 read the same file.
|
|
124
133
|
- **Record the derivation commit**: `git rev-parse --short HEAD`. It is the commit at which the entries were read, and `resolve-merge` compares it against the pull request's head to tell a fresh block from a stale one.
|
|
125
134
|
- **Consolidate the entries:**
|
|
126
135
|
|
|
@@ -165,7 +174,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
165
174
|
|
|
166
175
|
[`render-block`](../_data/title-templates.md#render-block) states the output, which is JSON; the last command decodes it and prints the `block` field. Render and decode in one Bash invocation, and write the printed block verbatim below `## Details`, separated by one blank line. Never copy the block out of the raw JSON: `text` is arbitrary prose, and JSON escapes its quotes and backslashes a second time.
|
|
167
176
|
|
|
168
|
-
`create-pr` copies this block into the pull-request body rather than rendering one of its own, so
|
|
177
|
+
`create-pr` copies this block into the pull-request body rather than rendering one of its own, so if the body is saved without one, the pull request does not contain one either. If the helper is unavailable or the call fails, relay its error, say that the summary does not contain a block, and save the body without one.
|
|
169
178
|
|
|
170
179
|
11. **Save** per the [Saving](#saving) section.
|
|
171
180
|
|
|
@@ -190,7 +199,7 @@ The body following the frontmatter has this structure:
|
|
|
190
199
|
|
|
191
200
|
## Why
|
|
192
201
|
|
|
193
|
-
{1-3 sentences
|
|
202
|
+
{1-3 sentences stating the _purpose_ that the change serves in this repository: the consequence that it produces or removes, for users, the codebase, or future work. Frame it in terms of that consequence, not mechanism, how the need arose, or how the work is staged across pull requests.
|
|
194
203
|
|
|
195
204
|
Bad: "The retry helper used a fixed backoff schedule with no shared state, so concurrent requests stacked up against the upstream rate limiter."
|
|
196
205
|
Good: "Heavy-upload sessions were intermittently failing as users hit the upstream API's rate limit."}
|
|
@@ -220,7 +229,7 @@ entries:
|
|
|
220
229
|
## Guidance
|
|
221
230
|
|
|
222
231
|
- When `ticket_ref` is null (the branch does not have a ticket), omit the `{ticket_ref} ` portion of the heading and the title so that they read naturally without it.
|
|
223
|
-
- The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the
|
|
232
|
+
- The change summary follows **newspaper style**, progressive disclosure from most to least essential: `## What` is the lede, `## Why` is the purpose that the change serves, `## Details` is every outcome that the change contains
|
|
224
233
|
- Both `## What` and `## Details` come from the drafter, so neither is composed in this session
|
|
225
234
|
- `## What` contains none of the `## Details` bullets: The two sections cover the change at different lengths rather than repeating one list
|
|
226
235
|
- Ignore auto-formatter and lint-fix changes
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: testing-conventions
|
|
3
|
-
description:
|
|
3
|
+
description: What a test is for, how to name and structure it, and how it calls git and other external programs. Consult before writing or changing a test.
|
|
4
4
|
user-invocable: false
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -14,11 +14,11 @@ Before writing a test, ask what would go uncaught if it did not exist. Three ans
|
|
|
14
14
|
|
|
15
15
|
- **A change that someone would have to make on purpose.** Rewording a message, editing a config, adding a member to a list: Each is a decision, and review already guards decisions. A test is justified when it catches an accident, a change made without intending to touch this outcome, such as a route added without its guard or a refactor that drops a case. A scenario constructed so that the test has something to catch is not an accident.
|
|
16
16
|
- **Nothing that this repository authored.** Machine state, the user's environment, and a dependency's behavior are not under test, and enabling a dependency's feature does not make that feature's behavior ours. If the right response to red would be a bug report upstream, the test is not ours.
|
|
17
|
-
- **A difference that costs nothing until noticed.** A relaxed lint rule, a setting that drifts from its best value, a directory that departs from convention:
|
|
17
|
+
- **A difference that costs nothing until noticed.** A relaxed lint rule, a setting that drifts from its best value, a directory that departs from convention: Maintaining a standing test takes more effort than noticing the difference would. A caught failure has to be worse than noticing it: a wrong answer returned, a task that a user cannot finish, data lost or exposed.
|
|
18
18
|
|
|
19
19
|
Then ask where the expected result comes from. A specification, a format, or a rule that someone could state without opening the code makes it an expectation. If pasting in whatever the code now produces would make the test pass again, the test pins a value, whatever its name says. When a test compares two sets, derive the expected one from its source; a set typed into the test drifts.
|
|
20
20
|
|
|
21
|
-
Three cases recur. Configuration is verified by the tool that reads it, which the build and lint gates run; if an accident is real and the tool is silent, prevent it at the tool rather than detect it in a test. Wording is asserted only when the text is the sole thing that distinguishes two code paths that exist, and then by a durable fragment. A process that this repository does not author is replaced by a
|
|
21
|
+
Three cases recur. Configuration is verified by the tool that reads it, which the build and lint gates run; if an accident is real and the tool is silent, prevent it at the tool rather than detect it in a test. Wording is asserted only when the text is the sole thing that distinguishes two code paths that exist, and then by a durable fragment. A process that this repository does not author is called through an adapter and replaced by a fake, as [External programs](#external-programs) states.
|
|
22
22
|
|
|
23
23
|
If a rule above forbids a test and the case seems exceptional, stop before writing it, state the case in one sentence, and wait.
|
|
24
24
|
|
|
@@ -33,6 +33,51 @@ A test that guards a behavior still has to clear two checks:
|
|
|
33
33
|
|
|
34
34
|
If a change needs coverage and these sections rule out every candidate test, it is merged without one; say which answer ruled the candidate out.
|
|
35
35
|
|
|
36
|
+
## Where a test goes
|
|
37
|
+
|
|
38
|
+
A test's **tier** is what it starts or builds to observe a behavior. The cheapest tier calls the code in the test's own process. An **expensive tier** spawns an entry point as a process, starts a runtime or an engine such as a database, or builds a full fixture. An engine counts as expensive whether it runs in the test's process or in another. A project's own tier names may classify tests on another axis, such as what they reach, and a test takes its label from the project's definition; nmr's, for example, labels a test that runs an embedded engine `tool`. The rules below concern cost.
|
|
39
|
+
|
|
40
|
+
- **Tier placement.** Test each case at the cheapest tier that can observe it. An expensive tier covers only what a cheaper tier cannot observe: that the entry starts, parses its arguments, wires its dependencies, and reports its exit status, with one smoke example per entry or verb. A branch of logic, a message, or a field of output is a case for the cheapest tier, even when the entry is the only caller that exercises it.
|
|
41
|
+
- **Consolidate before adding.** Write a new example only for a behavior that the existing examples cannot be extended to cover. Cases that share setup and action are one table-driven test, as [Test structure](#test-structure) states. When the examples do not mutate a fixture, build it once per file, not once per example.
|
|
42
|
+
- **Delete what is superseded, in the same change.** A higher-tier example is superseded when cheaper coverage observes each of its assertions, apart from the entry wiring that the smoke example covers. A change that adds the cheaper coverage deletes the examples that it supersedes, once the new tests pass the second check in [When tests are required](#when-tests-are-required). A port or a rewrite follows the same rule: The change that contains the port deletes the old suite rather than keeping it to catch regressions.
|
|
43
|
+
- **Justify each expensive addition.** A change that adds an example at an expensive tier states, in its plan or its pull-request description, why a cheaper tier cannot observe that example. The justification does not belong in a test comment.
|
|
44
|
+
- **Use the cheapest setup that fits.** Give an expensive tier the cheapest setup that fits its time budget, such as an in-process engine when few files need one. Add infrastructure, such as a server, a container, or a shared test package, only after a run of the suite at CI's parallelism shows that the cheaper setup does not fit.
|
|
45
|
+
- **Keep setup cost independent of the number of files.** Design expensive setup so that adding or splitting a test file does not add to it, for example by starting one engine for the suite rather than one per file.
|
|
46
|
+
- **Fix the design, not the timeout.** When a hook, a test, or a tier needs a longer timeout, in the test or in config, treat that as a sign of bad design and make it do less work: smaller data and injected dependencies, as [Test data](#test-data) states, or setup shared across files. A raised timeout hides a cost that grows with each file and with CI load. Raise one only when none of these fixes applies, and state why in the plan or the pull-request description, not in a test comment.
|
|
47
|
+
|
|
48
|
+
## Test data
|
|
49
|
+
|
|
50
|
+
- **Use the smallest data that proves the behavior.** A test renders or builds only the records that its assertion needs. Production data, such as a full catalog, appears only in a smoke test whose subject is that data.
|
|
51
|
+
- **Make data that a test cannot replace injectable.** When the code under test reads data or a dependency from a module-level singleton, fix the code: Take the value as a parameter, or read it from a context or provider whose default is the real value. Do not test against the real data, and do not mock this repository's module by its path, which keeps the singleton and ties the test to a file layout.
|
|
52
|
+
|
|
53
|
+
```tsx
|
|
54
|
+
// ❌ Avoid: The component reads the singleton, so every test renders the full catalog
|
|
55
|
+
function ScopePicker() {
|
|
56
|
+
return <ul>{scopeCatalog.map((scope) => <li key={scope.id}>{scope.label}</li>)}</ul>;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
// ✅ Good: The context defaults to the real catalog, and the test supplies two scopes
|
|
60
|
+
const ScopeCatalogContext = createContext(scopeCatalog);
|
|
61
|
+
|
|
62
|
+
function ScopePicker() {
|
|
63
|
+
const catalog = useContext(ScopeCatalogContext);
|
|
64
|
+
return <ul>{catalog.map((scope) => <li key={scope.id}>{scope.label}</li>)}</ul>;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
it('renders one item per scope', () => {
|
|
68
|
+
const scopes = [
|
|
69
|
+
{ id: 'read', label: 'Read' },
|
|
70
|
+
{ id: 'write', label: 'Write' },
|
|
71
|
+
];
|
|
72
|
+
render(
|
|
73
|
+
<ScopeCatalogContext.Provider value={scopes}>
|
|
74
|
+
<ScopePicker />
|
|
75
|
+
</ScopeCatalogContext.Provider>,
|
|
76
|
+
);
|
|
77
|
+
expect(screen.getAllByRole('listitem')).toHaveLength(2);
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
36
81
|
## Do not test that removed things stay removed
|
|
37
82
|
|
|
38
83
|
This is the commonest test that guards a decision. When a change removes code, text, or behavior, never add a permanent test asserting the removed thing is absent (a `not.toContain` guard against a deleted string, `expect(isEventType('input.received')).toBe(false)` against a removed variant). The assertion encodes history, not contract: It can fail only if someone reverts that exact line, so it does not guard any regression class, and such assertions accumulate without limit. The positive assertion describing the replacement behavior is the real guard.
|
|
@@ -98,7 +143,7 @@ This is the same signal-buried-in-noise failure mode that [comment discipline](#
|
|
|
98
143
|
|
|
99
144
|
### Rules
|
|
100
145
|
|
|
101
|
-
1. **Test bodies should be mostly variation and assertion, not setup.** Any prop, fixture, or boilerplate identical across N adjacent tests is noise. Factor it into a
|
|
146
|
+
1. **Test bodies should be mostly variation and assertion, not setup.** Any prop, fixture, or boilerplate identical across N adjacent tests is noise. Factor it into a helper that supplies defaults, or collapse the tests into a single parameterized test in which the variation reads as a table.
|
|
102
147
|
2. **Use `it.each` when N adjacent tests differ only in a small set of inputs and the body is structurally identical.** Use a named helper when the variation is bigger, when shared setup should move into a helper signature, or when assertion shapes differ per case.
|
|
103
148
|
3. **Test the rule, not the data.** Prefer counts, predicates, and structural assertions (`expect(getVisibleChipCount()).toBe(N)`, `expect(queryPillElement()).toBeInTheDocument()`) over enumerating specific fixture labels in every row. Assert specific data flow _once_, in a focused test, not per row of a table.
|
|
104
149
|
|
|
@@ -122,14 +167,15 @@ The smell is shared _setup with one variable_, not shared _shape with different
|
|
|
122
167
|
|
|
123
168
|
A test file runs in one test worker, and a file that keeps its fixtures makes an append cheaper than a split, so a file grows until it is the slowest unit in the suite. Before adding tests to a file that the addition would leave past the ceiling, split the file by aspect, then add the tests to the file that their aspect names.
|
|
124
169
|
|
|
125
|
-
- **Ceiling.** The `max-lines` setting that the project's lint configuration applies to test files.
|
|
170
|
+
- **Ceiling.** The `max-lines` setting that the project's lint configuration applies to test files. When the lint does not set one, 500 lines, counting every line.
|
|
126
171
|
- **Aspect.** A group of the subject's behaviors that shares setup and reads without the rest of the file. Each split file contains one aspect.
|
|
127
172
|
- **Naming.** Each split file keeps the subject's name and adds the aspect after it, followed by any segment that the project's naming requires: `sync.test.ts` becomes `sync.retirement.test.ts`, and `sync.tool.test.ts` becomes `sync.retirement.tool.test.ts`.
|
|
128
|
-
- **
|
|
173
|
+
- **Setup.** A split does not add expensive setup. When the file starts an engine or another expensive fixture of its own, share that setup across files first, as [Where a test goes](#where-a-test-goes) states, then split.
|
|
174
|
+
- **Fixtures.** Move the fixture builders that the split files share out of the test files, into a module in a `test-utils/` directory beside the tests (beside `__tests__/` when the tests live in one, never inside it), so that a new aspect file needs only one import.
|
|
129
175
|
|
|
130
176
|
## Keep passing tests quiet
|
|
131
177
|
|
|
132
|
-
A passing test prints nothing beyond the runner's report. Output that the code under test writes to the console, stdout, or stderr during a passing run
|
|
178
|
+
A passing test prints nothing beyond the runner's report. Output that the code under test writes to the console, stdout, or stderr during a passing run appears between the results, and it hides the warning or stack trace that matters when a run fails.
|
|
133
179
|
|
|
134
180
|
When the code under test writes output, intercept it in the test that triggers it, and restore it when that test ends:
|
|
135
181
|
|
|
@@ -158,6 +204,27 @@ jest.mock('@atlaskit/component', () => ({
|
|
|
158
204
|
}));
|
|
159
205
|
```
|
|
160
206
|
|
|
207
|
+
### External programs
|
|
208
|
+
|
|
209
|
+
A test that runs an external program to produce its inputs verifies the program rather than this code, and it depends on the copy installed on the machine that runs it: its version, its config, and its background processes. A `git commit` in a test repository, for example, can start a background maintenance run that is still writing into `.git/` when the test removes the directory.
|
|
210
|
+
|
|
211
|
+
- Code calls an external program whose behavior is not the subject of the test, such as git, through a small adapter that the code receives as a dependency.
|
|
212
|
+
- Tests of that code pass a fake adapter that returns fixed answers.
|
|
213
|
+
- Only the adapter's own test runs the real program, and it checks that the adapter parses the program's output as the code expects.
|
|
214
|
+
- A test does not create a repository, or any other state of a real program, to produce an input that a fake could return.
|
|
215
|
+
|
|
216
|
+
A test whose subject is the program's effect on real state, such as a command that initializes a repository, runs the program because that effect is the behavior under test.
|
|
217
|
+
|
|
218
|
+
The `typescript-testing-conventions` skill shows the TypeScript shape.
|
|
219
|
+
|
|
220
|
+
### Code that uses a database
|
|
221
|
+
|
|
222
|
+
A database is a program like any other in [External programs](#external-programs): A test starts one only when its subject is SQL.
|
|
223
|
+
|
|
224
|
+
- Logic that only passes through SQL, such as assembling a view, gating a command, or ordering and reporting, is tested at the cheapest tier against a fake client that returns fixed rows and errors, such as a SQLSTATE. Mock at the boundary of the module containing the SQL when that is simpler than faking the client.
|
|
225
|
+
- The database tests worth writing cover what the schema does not already state: that the migrations apply, transactional bookkeeping, upserts and idempotence, and queries.
|
|
226
|
+
- Do not write a test per constraint, such as inserting a duplicate row to expect the error. The test that the migrations apply covers the schema.
|
|
227
|
+
|
|
161
228
|
## Additional patterns
|
|
162
229
|
|
|
163
230
|
### Omit "should" from test names
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: triage-spike-findings
|
|
3
|
+
description: Dispose of the findings that a spike or a usability assessment 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 labelled 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
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Triage spike findings
|
|
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 the repository's labels, validates the dispositions record, and renders the comments.
|
|
10
|
+
|
|
11
|
+
**Announce at start:** "Using triage-spike-findings to dispose of the findings of {source} on {ticket_ref}."
|
|
12
|
+
|
|
13
|
+
## Inputs
|
|
14
|
+
|
|
15
|
+
- **The findings artifact**: A spike's findings or a `usability-findings` artifact, by local path or by artifact URL. Read a URL with the Artifact tool and save the content to `{ticket_dir}/triage/findings.md`, so that the challenger can read it from a path; on a harness without that tool, the input is a local path.
|
|
16
|
+
- **The triage ticket**: The ticket on which the dispositions are posted and under which the working files are kept, resolved per [ticket source resolution](../_data/ticket-source-resolution.md); when none is given, the session's ticket. The umbrella is created as a separate ticket, so the triage ticket may be the spike's own ticket.
|
|
17
|
+
|
|
18
|
+
GitHub alone is supported, through `gh`. When the session-context manifest's `scm` is not `github`, stop at preflight and report that the skill does not support the platform.
|
|
19
|
+
|
|
20
|
+
## Grades and dispositions
|
|
21
|
+
|
|
22
|
+
Each item takes a disposition and two grades:
|
|
23
|
+
|
|
24
|
+
- **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`.
|
|
25
|
+
- **Confidence** states advisability: `high` is clearly worth doing, `medium` is worth doing but arguable, `low` is not worth a ticket now. A borderline item takes the lower grade. Only an item graded `high` or `medium` gets a ticket; the helper refuses a record that gives a `low` item one.
|
|
26
|
+
- **Value** states how much the item matters: `must-have`, `should-have`, `nice-to-have`, `questionable`. Value never decides whether an item gets a ticket; it is recorded on every item and labels every child.
|
|
27
|
+
|
|
28
|
+
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.
|
|
29
|
+
|
|
30
|
+
## Process
|
|
31
|
+
|
|
32
|
+
Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`, except when a step below says otherwise. Invoke the helper as:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
node {harness_home_dir}/skills/triage-spike-findings/triage-spike-findings.mjs {command} {flags}
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Resolve `{ticket_dir}` per {skill:save-artifact}, and write every working file under `{ticket_dir}/triage/`.
|
|
39
|
+
|
|
40
|
+
### 1. Preflight
|
|
41
|
+
|
|
42
|
+
1. Run `gh auth status` and `gh repo view --json nameWithOwner`. If either fails, or `scm` is not `github`, stop and report why.
|
|
43
|
+
2. 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.
|
|
44
|
+
3. Create `{ticket_dir}/triage/`, and save the findings there when they came from a URL.
|
|
45
|
+
|
|
46
|
+
### 2. Inventory
|
|
47
|
+
|
|
48
|
+
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 (`gh issue list --search`, `gh issue view`): 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.
|
|
49
|
+
|
|
50
|
+
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, and the verification outcome (holds, partly holds, or does not hold, with the evidence).
|
|
51
|
+
|
|
52
|
+
### 3. Recommend
|
|
53
|
+
|
|
54
|
+
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.
|
|
55
|
+
|
|
56
|
+
### 4. Challenge
|
|
57
|
+
|
|
58
|
+
Send one {tool:Task} call, `subagent_type: disposition-challenger`, with this block and nothing else composed into it. `findings` is the copy saved in step 1, or the local path that was given:
|
|
59
|
+
|
|
60
|
+
```dispatch
|
|
61
|
+
findings: {ticket_dir}/triage/findings.md
|
|
62
|
+
recommendations: {ticket_dir}/triage/recommendations.md
|
|
63
|
+
root: {repository root}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
**A reply that lacks the `Phase: disposition-challenge` line is a challenger stopped by its turn limit.** Resume it once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. When the resumed challenger still does not return a report, do not dispatch again: Record the challenge as not returned, treat every item as unchallenged, and say so in the record's `challengeSummary`.
|
|
67
|
+
|
|
68
|
+
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.
|
|
69
|
+
|
|
70
|
+
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`.
|
|
71
|
+
|
|
72
|
+
Write `dispositions.json` in the helper's record shape: `source` (the findings as given), `triageTicket`, `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, empty when there are none). Each item has `id`, `title`, `disposition`, `confidence`, `value`, `reason`, `target` (the issue number 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), and `challenge` with `argument`, `outcome` (`defended`, `modified`, or `abandoned`), and `note`. 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.
|
|
73
|
+
|
|
74
|
+
### 5. Checkpoint: The dispositions
|
|
75
|
+
|
|
76
|
+
Present the dispositions as a table (item, disposition, confidence, value, blocked by, reason, challenge outcome), in the order that `validate` reports as `order`, which places every blocker before the items that it blocks, and the challenge summary, and ask in the action-items block for approval. Revise the record until the developer approves it; re-run `validate` after each change.
|
|
77
|
+
|
|
78
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
79
|
+
|
|
80
|
+
### 6. Compose and confirm
|
|
81
|
+
|
|
82
|
+
Compose the bodies:
|
|
83
|
+
|
|
84
|
+
- **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.
|
|
85
|
+
- **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}`.
|
|
86
|
+
|
|
87
|
+
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.
|
|
88
|
+
|
|
89
|
+
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, every per-issue comment with its issue, and the dispositions comment. 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.
|
|
90
|
+
|
|
91
|
+
### 7. Write
|
|
92
|
+
|
|
93
|
+
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.
|
|
94
|
+
|
|
95
|
+
1. When at least one item is a `ticket` and `umbrella` is null, create the umbrella with {skill:create-ticket}, and write its number into `umbrella`.
|
|
96
|
+
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 number.
|
|
97
|
+
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.
|
|
98
|
+
4. Run the helper's `render` to `{ticket_dir}/triage/rendered/`, without `--preview`.
|
|
99
|
+
5. 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:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
body_path="{ticket_dir}/triage/rendered/comment-{issue}.md"
|
|
103
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
104
|
+
gh issue comment {issue} --body-file "$body_path"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
6. Save `dispositions-comment.md`, with frontmatter, as the ticket-level `dispositions` artifact per {skill:save-artifact}.
|
|
108
|
+
|
|
109
|
+
### 8. Report
|
|
110
|
+
|
|
111
|
+
Report the umbrella when one was created, each child with its grades and blockers in the order in which step 7 created them, each issue commented on, and the artifact's path. The triage ticket stays open: Closing it is the developer's call, once they have read the record.
|
|
112
|
+
|
|
113
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|