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
|
@@ -31,10 +31,14 @@ Before every {tool:Task} call and after every phase completion, output a status
|
|
|
31
31
|
1. Read the plan file. If not found, report an error and stop.
|
|
32
32
|
2. Parse YAML frontmatter from the plan content. If a `provenance` block is present, store it as `{input-provenance}`. If the plan does not have frontmatter or a `provenance` block, set `{input-provenance}` to empty.
|
|
33
33
|
3. Resolve the ticket source:
|
|
34
|
-
- GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body {url}` via Bash to fetch content.
|
|
34
|
+
- GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body,blockedBy {url}` via Bash to fetch content.
|
|
35
35
|
- File path -> Read the file.
|
|
36
|
+
- Jira URL or key -> Fetch per the Jira entry in [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch).
|
|
36
37
|
- Other URL -> Fetch the URL content.
|
|
37
|
-
|
|
38
|
+
|
|
39
|
+
Then report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop the review.
|
|
40
|
+
|
|
41
|
+
4. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `branch_name`, `default_branch`, `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout. Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths in the plan's **Files:** lists, before the review starts.
|
|
38
42
|
5. Resolve artifact directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
39
43
|
6. `mkdir -p {artifact_dir}`
|
|
40
44
|
|
|
@@ -157,7 +161,7 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash.
|
|
|
157
161
|
|
|
158
162
|
The `provenance:` block is **not** populated from the script. Construct it manually per the case branches below.
|
|
159
163
|
|
|
160
|
-
**Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not
|
|
164
|
+
**Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not copied from `{input-provenance}`. This is correct: The output is a new artifact at a new point in time on a potentially different branch. The `provenance:` block's camelCase convention (`baseSha`, `isInteractive`, `refinedBy`) is preserved as-is on both read and write; the keys are not renamed. Provenance fields copied from the input are `skill`, `baseSha`, `isInteractive`, and `iteration` (per the case branches).
|
|
161
165
|
|
|
162
166
|
**When `{input-provenance}` is non-empty:**
|
|
163
167
|
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: refine-prototype
|
|
3
|
+
description: Refine one prototype page at sketch speed, between the verdict on a round and the end vision, or sketch a variant of a built product the same way. Transfers the kept and adapted ideas of the round to the base, applies the developer's commands in batches while the page reloads in their browser, snapshots each accepted version into the ticket's prototype set with its id on the page, and records every accepted change in a refinement log that the end vision reads. Use when the developer wants to refine, combine, or vary prototypes before a ticket is written.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
supported-harnesses: [claude]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Refine prototype
|
|
9
|
+
|
|
10
|
+
Work one prototype page the way a designer works a sketch: The developer gives commands, you apply them to the page, their browser shows the result, and nothing else runs. The development gates are off on purpose. A sketch is the reference for the ticket that follows, never the implementation, and it is fast because it skips what a change to the product needs.
|
|
11
|
+
|
|
12
|
+
The page is in the ticket's prototype set, per {skill:index-prototypes}, and each snapshot adds the accepted version to the set under its id: The snapshot replaces the slug's card on the index under the new id, and the manifest and the refinement log keep the earlier versions.
|
|
13
|
+
|
|
14
|
+
## Inputs
|
|
15
|
+
|
|
16
|
+
- **The set**: its manifest and verdicts, the latest `idea-decisions` artifact in the ticket directory, and any `refinement-log` artifact there.
|
|
17
|
+
- **The base**: the prototype that the developer names by its number, or the winner when they name none. When the base is a built product rather than a page, the base is one region of it, reconstructed as a page from a screenshot and the design doc. It takes a new slug, and its band and description name what it was built from.
|
|
18
|
+
- **The developer's commands**, in their words: "Move the rail under the matrix", "Tighten the row spacing", "Split Start from into two tabs", "Take the scope text area from 4".
|
|
19
|
+
|
|
20
|
+
## Rules of the sketch
|
|
21
|
+
|
|
22
|
+
Off:
|
|
23
|
+
|
|
24
|
+
- Tests, lint, formatters, type checks, and every `nmr` command.
|
|
25
|
+
- Commits, branches, and edits to the ticket, the design doc, or any file outside the set directory, the scratch directory, and the artifact directory.
|
|
26
|
+
- The brainstorming, planning, test-driven, review, and verification skills. A sketch does not have a plan or a review.
|
|
27
|
+
- Questions that a render answers. When a command admits two renderings, render both and let the developer pick.
|
|
28
|
+
|
|
29
|
+
On:
|
|
30
|
+
|
|
31
|
+
- The page is self-contained and opens from `file://`, with its demo chrome in a band whose every part is inside an element that has `data-demo`, as the brief that built it required.
|
|
32
|
+
- The band's first line is the page's id and title, `{number}.{version} {title}`, so that the developer reads which version they have open without returning to the index.
|
|
33
|
+
- {rulebook:accessibility-conventions} is the floor: Check contrast and size when a command changes a colour or a text size.
|
|
34
|
+
- A new string on the product surface follows {rulebook:ui-copy-conventions}.
|
|
35
|
+
- One working file. A batch edits it in place; a fork is written next to it and is deleted once the developer picks.
|
|
36
|
+
|
|
37
|
+
## Process
|
|
38
|
+
|
|
39
|
+
### 1. Resolve the set and the base
|
|
40
|
+
|
|
41
|
+
Resolve the set directory and the scratch directory per {skill:index-prototypes} step 1, read back the verdicts per its "Read back the verdicts", and read the latest `idea-decisions` and `refinement-log` artifacts in the ticket directory. Name the base to the developer as `{id} {title}`.
|
|
42
|
+
|
|
43
|
+
A refinement keeps the base's slug, and its first snapshot takes the slug's next version. Resolve the id before the first edit:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs resolve-ids \
|
|
47
|
+
--set-dir "{set_dir}" \
|
|
48
|
+
--slugs {slug}
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Copy the base's latest source to `{scratch_dir}/{slug}-v{n}.html`, the working file, and set the band's first line to the new id. A base reconstructed from a built product takes a new slug and starts at version 1, and its band's first line names the source after the id, such as `6.1 Start from as tabs, from the api-tokens page`.
|
|
52
|
+
|
|
53
|
+
### 2. Serve the working file
|
|
54
|
+
|
|
55
|
+
Start a reloading server on the scratch directory in the background, and give the developer the working file's URL once:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
pnpm dlx vite --host 127.0.0.1 "{scratch_dir}"
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Read the host and port from the server's `Local:` line; when `pnpm` is absent, run `npx --yes vite` the same way. The developer keeps `{local_url}/{slug}-v{n}.html` open, and the server reloads it on every save. Capture screenshots from the same server with the Playwright MCP, per {skill:index-prototypes} step 3, at width 1280 and at width 390.
|
|
62
|
+
|
|
63
|
+
### 3. Propose the transplants
|
|
64
|
+
|
|
65
|
+
The verdict picked the base; it did not pick the base's ideas over the others. From the `idea-decisions` table, list every row whose decision is `keep` and whose sources do not include the base, and every row whose decision is `adapt`, and propose them as the first batch in one action-items block, ordered so that a structural change comes before the changes that depend on it. The developer trims or reorders the list.
|
|
66
|
+
|
|
67
|
+
A transplant moves the mechanism, not the look: Read the source prototype's file, and copy the markup, the styles, and the script that make the idea work, fitted to the base. Rebuilding an idea from its screenshot is a defect, because a screenshot does not show what the mechanism does.
|
|
68
|
+
|
|
69
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
70
|
+
|
|
71
|
+
### 4. Apply the batches
|
|
72
|
+
|
|
73
|
+
Each turn, take every command in the developer's message as one batch:
|
|
74
|
+
|
|
75
|
+
1. Apply every command to the working file.
|
|
76
|
+
2. Take the screenshots, and look at them before replying. An overlap, a cut-off, text under the size floor, or a contrast failure that a command caused is reported with the batch, not left for the developer to find.
|
|
77
|
+
3. For a command that admits two renderings, write each as `{scratch_dir}/{slug}-v{n}-{letter}.html`, screenshot both, and leave the working file as it was before that command. The developer picks by letter; the next batch applies the pick and deletes the forks.
|
|
78
|
+
4. Append each applied command to the session's log, under the id of the version that it will enter, with the developer's reason when they gave one and the source id when it was a transplant.
|
|
79
|
+
5. Reply with one line per command (applied, forked with its letters and their URLs, or refused with the reason), and nothing else. The developer looks at the browser, not at a description of it.
|
|
80
|
+
|
|
81
|
+
Propose a new number when a batch replaces the layout or the model to the point that the earlier version's verdicts and notes no longer describe the page. On yes, the working file takes a new slug and the id that `resolve-ids` gives it, and its band names the version from which it came. The old slug keeps its last snapshot.
|
|
82
|
+
|
|
83
|
+
### 5. Snapshot
|
|
84
|
+
|
|
85
|
+
Snapshot when the developer asks for one, in any words ("snapshot", "keep this", "version it"), and at the end of the session before stopping. A snapshot creates a version: Until then the working file is unregistered, and a session that stops without one loses the work since the last.
|
|
86
|
+
|
|
87
|
+
1. Copy the working file to `{set_dir}/{slug}-v{n}.html`.
|
|
88
|
+
2. Publish it with the Artifact tool: to the slug's existing artifact URL when the manifest's latest entry for the slug has one, so that the index card's link stays current, or as a new artifact for a new slug.
|
|
89
|
+
3. Capture its screenshots per {skill:index-prototypes} step 3, and register it per its step 4 with `--number {number}`, `--source`, the set's note labels (copied from the latest entry, with any change that the batches made to them), and, for a new slug, a `--description` that names the version from which it came.
|
|
90
|
+
4. Update the set's summary per {skill:index-prototypes} step 5, naming the version in `changes`, then render and republish the index per its step 6.
|
|
91
|
+
5. The next batch opens the next version: Copy the snapshot to `{scratch_dir}/{slug}-v{n+1}.html` and set the band's id.
|
|
92
|
+
|
|
93
|
+
### 6. Close
|
|
94
|
+
|
|
95
|
+
When the developer says that the refinement is done:
|
|
96
|
+
|
|
97
|
+
1. Snapshot whatever has changed since the last one.
|
|
98
|
+
2. When the ticket or the design doc names a component library, dispatch one reader with {tool:Task} (`subagent_type: general-purpose`, model `sonnet`) to list every element of the final page that the library does not supply, each with the nearest thing that the library has. The decisions on those belong to the end vision, not to this skill.
|
|
99
|
+
3. Save the log per [The refinement log](#the-refinement-log).
|
|
100
|
+
4. Stop the server, and give the developer the index link, the final id, and the log's path.
|
|
101
|
+
|
|
102
|
+
The end vision writes the design doc from the log and the `idea-decisions` artifact. This skill edits neither.
|
|
103
|
+
|
|
104
|
+
## The refinement log
|
|
105
|
+
|
|
106
|
+
Save it with {skill:save-artifact} as a ticket-level `refinement-log` artifact:
|
|
107
|
+
|
|
108
|
+
- `## Base`: the base's id and title, and the index URL.
|
|
109
|
+
- `## Snapshots`: one `### {id}` per snapshot in order, each listing its accepted changes, one line per change, with the developer's reason when they gave one and `from {id}` on a transplant.
|
|
110
|
+
- `## Open forks`: forks shown and not picked, each with its letters and what differed.
|
|
111
|
+
- `## Library check`: the reader's list from step 6, when it ran.
|
|
112
|
+
|
|
113
|
+
A later session starts a new log from the latest snapshot; it does not edit this one.
|
|
@@ -155,7 +155,7 @@ The disposition conflates two decisions: whether the change belongs (substance),
|
|
|
155
155
|
|
|
156
156
|
## Writing code after a review
|
|
157
157
|
|
|
158
|
-
Implementing an ACCEPTed finding puts you mid-conversation with the reviewer, which is when
|
|
158
|
+
Implementing an ACCEPTed finding puts you mid-conversation with the reviewer, which is when comments start to repeat the reviewer's wording. A comment must not narrate the change, retell the reviewer's concern, or cite a finding or acceptance-criterion ID.
|
|
159
159
|
|
|
160
160
|
**Before** (narrates the review, cites a finding and an acceptance criterion):
|
|
161
161
|
|
|
@@ -36,7 +36,7 @@ On HEAD mismatch, do not return; exit non-zero with the mismatch error. `review-
|
|
|
36
36
|
|
|
37
37
|
## Bitbucket access
|
|
38
38
|
|
|
39
|
-
|
|
39
|
+
Make every Bitbucket call below with the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). That document specifies the tool, the coordinates, the field vocabulary, and the not-connected stop; this skill states only what it does with them.
|
|
40
40
|
|
|
41
41
|
## Process
|
|
42
42
|
|
|
@@ -169,6 +169,8 @@ The body following the frontmatter has this structure:
|
|
|
169
169
|
|
|
170
170
|
## Technical assessment
|
|
171
171
|
|
|
172
|
+
{Why the change is correct and adequately tested. For a change to a visible component, what the browser check in {rulebook:accessibility-conventions} found, or that it did not run and which elements it would have covered.}
|
|
173
|
+
|
|
172
174
|
## Conclusion
|
|
173
175
|
|
|
174
176
|
Score: X/10
|
|
@@ -179,7 +181,7 @@ Score: X/10
|
|
|
179
181
|
|
|
180
182
|
### {source.label}
|
|
181
183
|
|
|
182
|
-
{The label is `{source_type}: {short identifier}`, for example, `ticket: #553` or `pr_description: PR #1024`. Use the source's natural identifier so a reader can tell at a glance which specification a row evaluates against.}
|
|
184
|
+
{The label is `{source_type}: {short identifier}`, for example, `ticket: #553` or `pr_description: PR #1024`. Use the source's natural identifier so that a reader can tell at a glance which specification a row evaluates against.}
|
|
183
185
|
|
|
184
186
|
**Source:** {Render the source's `provenance` and `last_updated` (echoed verbatim; `last_updated` is already ISO 8601) so that the reader knows what contract this section measured against, e.g. `remote issue (last updated 2026-06-07T01:56:34Z)`, ``local snapshot `20260606-090337Z_..._ticket.md` (last updated 2026-06-06T09:03:37Z)``, or `local source (last updated …)` for an explicit file/plain-text `--ticket` that has no snapshot filename. Omit the "last updated" clause when `last_updated` is null.}
|
|
185
187
|
|
|
@@ -260,7 +262,7 @@ None.
|
|
|
260
262
|
|
|
261
263
|
## Technical assessment
|
|
262
264
|
|
|
263
|
-
{Why the change is correct and adequately tested.}
|
|
265
|
+
{Why the change is correct and adequately tested. For a change to a visible component, what the browser check in {rulebook:accessibility-conventions} found, or that it did not run and which elements it would have covered.}
|
|
264
266
|
|
|
265
267
|
## Conclusion
|
|
266
268
|
|
|
@@ -16,9 +16,10 @@ Evaluation criteria for code review. Apply proportionally: Match depth to risk.
|
|
|
16
16
|
|
|
17
17
|
- **Correctness**: Logic errors, unhandled error paths, data loss risks
|
|
18
18
|
- **Data changes**: A change that removes or renames data that deployed code still reads, or that depends on a migration run before merge (see {rulebook:shared-data-conventions})
|
|
19
|
+
- **Interfaces**: A change that defines or changes colour tokens, text styles, or a page or UI component (see {rulebook:accessibility-conventions}). For each new or changed interactive element, ask whether it shows that it is interactive, by the states that the rulebook names, and check it in a browser as the rulebook requires rather than by reading the diff alone
|
|
19
20
|
- **Conventions**: Adherence to codebase patterns and project standards
|
|
20
21
|
- **Edge cases**: Boundary conditions, empty collections, zero values, undefined states
|
|
21
|
-
- **Test coverage**: Adequate tests for new functionality; tests that verify behavior and
|
|
22
|
+
- **Test coverage**: Adequate tests for new functionality; tests that verify behavior and are worth keeping, not just coverage
|
|
22
23
|
- **Clarity**: Naming, documentation, and instructions convey unambiguous intent
|
|
23
24
|
- **Contracts**: Documented behaviors match implementations; implicit assumptions are explicit
|
|
24
25
|
- **Type safety**: Type issues that affect correctness or maintainability
|
|
@@ -67,7 +68,7 @@ Comment text that you propose for a source file (a replacement doc comment, a su
|
|
|
67
68
|
|
|
68
69
|
"Add a comment explaining X" is a finding only when X is a constraint that the code cannot show. Do not request a comment that the discipline would delete.
|
|
69
70
|
|
|
70
|
-
## Do not recommend a test that
|
|
71
|
+
## Do not recommend a test that is not worth keeping
|
|
71
72
|
|
|
72
73
|
Every test that you recommend clears the bar in the `testing-conventions` skill, which states the filters and the authoring-side rule. A recommendation that fails a filter is withdrawn rather than reworded, and absence of a test is not by itself a finding.
|
|
73
74
|
|
|
@@ -75,12 +76,44 @@ The commonest instance is a test asserting that deleted code, text, or behavior
|
|
|
75
76
|
|
|
76
77
|
## Grown test files
|
|
77
78
|
|
|
78
|
-
A test file that the change adds to and leaves past the ceiling in the `testing-conventions` skill is a Warning, and its proposed change is a split by aspect as that skill describes. The diff does not show a file's length, so measure each test file that the change adds to.
|
|
79
|
+
A test file that the change adds to and leaves past the ceiling in the `testing-conventions` skill is a Warning, and its proposed change is a split by aspect as that skill describes. When the file starts expensive setup of its own, such as a database engine, the proposed change shares that setup before the split, so that the split does not add to it. The diff does not show a file's length, so measure each test file that the change adds to. If the project's lint applies `max-lines` to test files, the lint is the guard, and this is not a finding. A file past the ceiling that the change does not add to is Legacy.
|
|
80
|
+
|
|
81
|
+
## Test placement
|
|
82
|
+
|
|
83
|
+
Two defects against the placement rules in the `testing-conventions` skill are Warnings:
|
|
84
|
+
|
|
85
|
+
- **A misplaced expensive example.** The change adds an example at an expensive tier, and a cheaper tier could observe it. The proposed change moves the case to the cheaper tier. If the change's plan or pull-request description explains why a cheaper tier cannot observe the case, it is not a finding.
|
|
86
|
+
- **A kept superseded suite.** The change adds cheaper coverage but keeps the higher-tier examples that the new coverage supersedes. The proposed change deletes those examples. To find them, read each process-spawning or full-fixture example that exercises the logic which the change's new tests cover, and compare its assertions with the new tests.
|
|
87
|
+
|
|
88
|
+
The same defects in tests that the change neither adds nor supersedes are Legacy.
|
|
89
|
+
|
|
90
|
+
## Database tests and setup cost
|
|
91
|
+
|
|
92
|
+
Three defects against the database and setup rules in the `testing-conventions` skill are Warnings:
|
|
93
|
+
|
|
94
|
+
- **A database for a test whose subject is not SQL.** The proposed change tests the logic against a fake client or a mock at the boundary of the module containing the SQL.
|
|
95
|
+
- **A test per constraint.** The proposed change deletes it; the test that the migrations apply covers the schema.
|
|
96
|
+
- **A split that adds per-file setup.** The change adds or splits a test file, and each file starts its own expensive setup. The proposed change shares that setup across the files.
|
|
97
|
+
|
|
98
|
+
The same defects in tests that the change does not add, split, or modify are Legacy.
|
|
99
|
+
|
|
100
|
+
## Test data and timeouts
|
|
101
|
+
|
|
102
|
+
Two defects against the test-data and timeout rules in the `testing-conventions` skill are Warnings:
|
|
103
|
+
|
|
104
|
+
- **A raised timeout.** The change raises a hook's, a test's, or a tier's timeout, in a test or in config. The proposed change reduces the work by the fixes that the skill names. A reason stated in the plan or the pull-request description does not exempt the raise: Check the reason against those fixes, and report the finding when one of them still applies.
|
|
105
|
+
- **A test that renders or builds production-scale data.** The proposed change passes the smallest data that proves the behavior, and makes the data injectable when the code under test reads it from a module-level singleton, even when the singleton is in code that the change does not touch. The diff does not show the data's size, so read what the code under test imports.
|
|
106
|
+
|
|
107
|
+
The same defects in tests and config that the change does not add or modify are Legacy.
|
|
79
108
|
|
|
80
109
|
## Noisy tests
|
|
81
110
|
|
|
82
111
|
A test that the change adds and that writes output on a passing run is a Suggestion, and its proposed change is the interception that the `testing-conventions` skill describes. The diff does not show runtime output: Read the test run's output when one is available, and otherwise read for logging calls on the paths that the test exercises. A noisy test that the change does not add is Legacy.
|
|
83
112
|
|
|
113
|
+
## Always-loaded context
|
|
114
|
+
|
|
115
|
+
A change that adds to what every session loads is a Warning unless nearly every session needs the content, and a ticket that asks for the change does not exempt it. Such a change makes a rulebook ambient, adds an ambient rulebook to a collection or a `codeassembly.yaml` declaration, or grows an `AGENTS.md`, a `CLAUDE.md`, or another file loaded at session start. The proposed change is `skill` or `hook` delivery, or a move of the content into a skill. A skill's or subagent's description is not a finding: Every session needs it to discover what it describes.
|
|
116
|
+
|
|
84
117
|
## Finding references
|
|
85
118
|
|
|
86
119
|
Conventions for how findings reference files and code locations.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var
|
|
4
|
-
`)
|
|
5
|
-
`)}
|
|
6
|
-
`)}
|
|
7
|
-
`)
|
|
8
|
-
`)
|
|
3
|
+
var y=Object.defineProperty;var n=(r,e)=>y(r,"name",{value:e,configurable:!0});import u from"node:process";function f(r){return r instanceof Error||Object.prototype.toString.call(r)==="[object Error]"}n(f,"isError");function s(r){try{return f(r)&&typeof r.message=="string"&&r.message!==""?r.message:String(r)}catch{return"[unstringifiable value]"}}n(s,"describeError");import{realpathSync as a}from"node:fs";import m from"node:process";import{fileURLToPath as k}from"node:url";function l(r,e){let t=m.argv[1];if(t===void 0)return!1;try{return a(k(r))===a(t)}catch(o){return m.stderr.write(`${e}: warning: could not determine entry point: ${s(o)}
|
|
4
|
+
`),!0}}n(l,"isEntryPoint");async function d(r){let e=[];for await(let t of r){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");e.push(t)}return Buffer.concat(e).toString("utf8")}n(d,"readAll");function c(r){return w(r)&&!Array.isArray(r)}n(c,"isRecord");function w(r){return typeof r=="object"&&r!==null}n(w,"isObject");var h=/\b(?:closes|fixes|resolves):?\s+#(\d+)\b|(?<![\w/#&])#(\d+)\b/iu;function b(r){if(!c(r))throw new Error("input must be a JSON object");let{body:e,closingIssuesReferences:t}=r;if(e!=null&&typeof e!="string")throw new Error("body must be a string");if(t!==void 0&&!Array.isArray(t))throw new Error("closingIssuesReferences must be an array");let o=(t??[]).map(i=>{if(!c(i)||typeof i.number!="number"||!Number.isSafeInteger(i.number))throw new Error("each closingIssuesReferences entry must have an integer number");return i.number});return{body:e??"",closingIssueNumbers:o}}n(b,"parsePrTicketInput");function p(r){let[e]=r.closingIssueNumbers;if(e!==void 0)return{number:e,source:"closing-reference"};let t=h.exec(E(r.body));if(t===null)return{number:null,source:"none"};let[,o,i=""]=t;return o!==void 0?{number:Number(o),source:"body-keyword"}:{number:Number(i),source:"body-bare"}}n(p,"selectPrTicket");function g(r){return r.replaceAll(/[^\n]/gu," ")}n(g,"blank");function E(r){return N(x(r))}n(E,"maskCode");function x(r){let e;return r.split(`
|
|
5
|
+
`).map(t=>{let o=/^ {0,3}(`{3,}|~{3,})/u.exec(t)?.[1];if(e===void 0){if(o===void 0)return t;e={char:o.charAt(0),length:o.length}}else o!==void 0&&o.charAt(0)===e.char&&o.length>=e.length&&t.trim()===o&&(e=void 0);return g(t)}).join(`
|
|
6
|
+
`)}n(x,"maskFencedBlocks");function N(r){return r.replaceAll(/(?<!`)(`+)(?!`)(?:(?!\n[ \t]*\n)[\s\S])*?(?<!`)\1(?!`)/gu,e=>g(e))}n(N,"maskInlineCode");async function I(){try{let r=u.argv.slice(2);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}`);let e=b(JSON.parse(await d(u.stdin)));u.stdout.write(`${JSON.stringify(p(e))}
|
|
7
|
+
`)}catch(r){u.stderr.write(`select-pr-ticket: ${s(r)}
|
|
8
|
+
`),u.exit(1)}}n(I,"main");l(import.meta.url,"select-pr-ticket")&&await I();
|
|
@@ -1,12 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: revise-comments
|
|
3
|
-
description: Revise comments in target files per the comment-discipline rules, editing in place
|
|
3
|
+
description: Revise comments in target files per the comment-discipline rules, adding missing code descriptions and fixing drifted ones, editing in place
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# Revise comments
|
|
8
8
|
|
|
9
|
-
Apply the comment-discipline audit to a target file set, editing comments in place. The default workflow is `{skill:revise-comments}` after a feature is implemented; explicit paths support cleaning up legacy code.
|
|
9
|
+
Apply the comment-discipline audit to a target file set, editing comments in place: Keep, delete, or rewrite each comment, add a description to each declaration that lacks one, and rewrite each description that misstates its code. The default workflow is `{skill:revise-comments}` after a feature is implemented; explicit paths support cleaning up legacy code.
|
|
10
10
|
|
|
11
11
|
If the `revise-prose` sweep is wanted on the same files, run this skill first: It decides whether a comment exists at all, and it may delete the very comment that the prose sweep would otherwise polish.
|
|
12
12
|
|
|
@@ -26,9 +26,9 @@ If the `revise-prose` sweep is wanted on the same files, run this skill first: I
|
|
|
26
26
|
git diff --name-only "{default_branch}...HEAD"
|
|
27
27
|
```
|
|
28
28
|
|
|
29
|
-
2. **Apply the audit per file.** Read each target file. Put every comment through the tests below. Decide one of
|
|
29
|
+
2. **Apply the audit per file.** Read each target file. Put every comment through the tests below, and every declaration through [Description coverage and accuracy](#description-coverage-and-accuracy). Decide one of four actions: kept, deleted, rewritten, or added. In normal mode, apply edits in place via the Edit tool. In `--dry-run` mode, record the proposed action without editing.
|
|
30
30
|
|
|
31
|
-
3. **Audit the diff** per [Diff audit](#diff-audit), over the edits just applied. A re-worded comment is the reach sweep's central case: It can invalidate a sibling doc, a README, or a test title that echoed the phrasing that it replaced. Such a file is outside the resolved target set, so the hard gate in [Target file set](#target-file-set) applies
|
|
31
|
+
3. **Audit the diff** per [Diff audit](#diff-audit), over the edits just applied. A re-worded comment is the reach sweep's central case: It can invalidate a sibling doc, a README, or a test title that echoed the phrasing that it replaced. Such a file is outside the resolved target set, so the hard gate in [Target file set](#target-file-set) applies: Report the hit to the user alongside the summary rather than repair it. Because `--dry-run` does not apply any edits, the step is skipped under that flag.
|
|
32
32
|
|
|
33
33
|
4. **Emit the summary.** After processing all targets, emit one table per file with non-trivial decisions.
|
|
34
34
|
|
|
@@ -38,6 +38,15 @@ If the `revise-prose` sweep is wanted on the same files, run this skill first: I
|
|
|
38
38
|
|
|
39
39
|
<!-- include: ../../_partials/diff-audit-checklist.md / -->
|
|
40
40
|
|
|
41
|
+
## Description coverage and accuracy
|
|
42
|
+
|
|
43
|
+
Because the baseline above requires a description, this skill acts on declarations as well as on the comments that they have:
|
|
44
|
+
|
|
45
|
+
- **Coverage.** Add a description (`added`) to each function, method, class, and component that lacks one, helpers in test files included. Skip an anonymous callback passed inline, which is not a declaration. Do not add one to a constant or a type, for which the baseline makes a description optional.
|
|
46
|
+
- **Accuracy.** Compare each description with the code that it describes, and rewrite one that misstates what the code does or is. Length alone is not a reason to rewrite an accurate description.
|
|
47
|
+
- **Never deleted.** Rewrite a declaration's description that fails one of the four tests; never delete it, because the baseline requires one.
|
|
48
|
+
- **Form.** Write an added or rewritten description in the doc-comment form that the file already uses, or else in the language's standard form, such as JSDoc in TypeScript.
|
|
49
|
+
|
|
41
50
|
## File-level carve-outs
|
|
42
51
|
|
|
43
52
|
The carve-outs above apply to comments. Two file-level rules decide which lines this skill may touch at all:
|
|
@@ -52,6 +61,7 @@ The default is to act. Pause and ask the user when one of these holds:
|
|
|
52
61
|
- A test comment could plausibly be non-obvious setup, but the test name already conveys the setup intent.
|
|
53
62
|
- An `eslint-disable` rationale is at the boundary between tight and over-scoped.
|
|
54
63
|
- A file header describes potentially load-bearing architecture (composition order, threading model, invariants across functions), so it may state a constraint that the code cannot show.
|
|
64
|
+
- A description and its code disagree, and the code could be the part that is wrong, such as when the declaration's name agrees with the description. Rewriting the description would record the defect as intended behavior, and this skill never edits code.
|
|
55
65
|
|
|
56
66
|
## Summary format
|
|
57
67
|
|
|
@@ -69,7 +79,9 @@ src/lib/payload.ts
|
|
|
69
79
|
| 6 | kept | n/a | why-inline |
|
|
70
80
|
```
|
|
71
81
|
|
|
72
|
-
|
|
82
|
+
`Test` names the test that decided the action: one of the four, `accuracy`, `baseline` for an added description, or `n/a`. For `added`, `Line` is the declaration's line.
|
|
83
|
+
|
|
84
|
+
Line numbers refer to the pre-edit file, so check each row against `git diff` output before emitting the table: The `Action` column reports what the diff shows, not what was intended. For a comment failing more than one test, report the first that it fails.
|
|
73
85
|
|
|
74
86
|
## Worked example
|
|
75
87
|
|
|
@@ -87,6 +99,15 @@ export function buildPayload(input: Input): Payload {
|
|
|
87
99
|
const items = Array.isArray(input.value) ? input.value : [input.value];
|
|
88
100
|
return { items };
|
|
89
101
|
}
|
|
102
|
+
|
|
103
|
+
/** Returns the first item, or undefined when the payload is empty. */
|
|
104
|
+
export function lastItem(payload: Payload): Item | undefined {
|
|
105
|
+
return payload.items.at(-1);
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
export function isEmptyPayload(payload: Payload): boolean {
|
|
109
|
+
return payload.items.length === 0;
|
|
110
|
+
}
|
|
90
111
|
```
|
|
91
112
|
|
|
92
113
|
**After:**
|
|
@@ -98,6 +119,16 @@ export function buildPayload(input: Input): Payload {
|
|
|
98
119
|
const items = Array.isArray(input.value) ? input.value : [input.value];
|
|
99
120
|
return { items };
|
|
100
121
|
}
|
|
122
|
+
|
|
123
|
+
/** Returns the last item, or undefined when the payload is empty. */
|
|
124
|
+
export function lastItem(payload: Payload): Item | undefined {
|
|
125
|
+
return payload.items.at(-1);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
/** Reports whether the payload has no items. */
|
|
129
|
+
export function isEmptyPayload(payload: Payload): boolean {
|
|
130
|
+
return payload.items.length === 0;
|
|
131
|
+
}
|
|
101
132
|
```
|
|
102
133
|
|
|
103
134
|
**Summary emitted:**
|
|
@@ -112,4 +143,6 @@ src/lib/payload.ts
|
|
|
112
143
|
| 2 | deleted | stranger | PR reference |
|
|
113
144
|
| 4 | rewritten | stranger | "we discussed" |
|
|
114
145
|
| 6 | kept | n/a | why-inline |
|
|
146
|
+
| 11 | rewritten | accuracy | says first; code returns last |
|
|
147
|
+
| 16 | added | baseline | no description |
|
|
115
148
|
```
|
|
@@ -122,7 +122,7 @@ rules: {rule-id}, {rule-id}
|
|
|
122
122
|
EOF
|
|
123
123
|
```
|
|
124
124
|
|
|
125
|
-
`sweptAt` is today's ISO calendar date. `roots` lists the invocation's narrowing paths, or `["."]` for a whole-repository sweep. `units` names every unit from step 1 at its current version. `rules` names every rule that step 2 passed with a version, `plain-speech` included, with its unit and its sweep version; the helper records for each whether it
|
|
125
|
+
`sweptAt` is today's ISO calendar date. `roots` lists the invocation's narrowing paths, or `["."]` for a whole-repository sweep. `units` names every unit from step 1 at its current version. `rules` names every rule that step 2 passed with a version, `plain-speech` included, with its unit and its sweep version; the helper records for each whether it has a detector for the rule.
|
|
126
126
|
|
|
127
127
|
`rejections` contains every subagent rejection plus every questionable rejected in step 5.1, by you or by the user, each containing `rule`, `file`, `phrase` as the text reads after this run's edits, and `ground`. A rejected questionable's `ground` is the reason recorded for its rejection. Leave out a rejection under a rule that `rules` does not name, which is a rule without a sweep version: Nothing records such a rule, and the helper refuses the fold.
|
|
128
128
|
|