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
|
@@ -12,7 +12,7 @@
|
|
|
12
12
|
|
|
13
13
|
Present all three options as a numbered list per [option format](#option-format). Each option has a strength marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker. Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific plan presents a tradeoff that survives the option-format tests bearing on which option fits (e.g., "the schema change ships and is verifiable before the reader that consumes it," "every task follows the sibling table's established pattern"). Generic option properties ("structured review pass," "longer wall time") are noise and must be omitted. Include all known paths (plan, ticket) in each option line; omit paths that are not available in the current context. Use `~/`-relative paths when possible and absolute paths otherwise. Every line subordinate to an option (invocation guidance as much as a pro or con) is a nested list item, never a whitespace-indented continuation.
|
|
14
14
|
|
|
15
|
-
**The ticket and plan are the complete handoff.** Every option assumes that a fresh session acts on the saved artifacts alone, whether or not one does, so nothing that only this session
|
|
15
|
+
**The ticket and plan are the complete handoff.** Every option assumes that a fresh session acts on the saved artifacts alone, whether or not one does, so nothing that only this session knows distinguishes one option from another. A pro or con never cites the conversation, session-held context, or what is "already in context", and neither does the invocation guidance of any option, the spike's 🔬 Investigate included. When a fact that an option needs exists only in the session, the artifact is incomplete: Add the fact to the ticket or the plan before rendering the menu, rather than citing the session.
|
|
16
16
|
|
|
17
17
|
**One `➕` line is mandatory rather than omitted.** When Refine plan is the selected option, it must include a `➕` line naming the specific unsettled decision that the pass would raise (rule 1). The line names an open decision, never a reassurance about work already done: "a refine pass is the cheap way to find out whether I missed something" is the shape that this requirement exists to forbid. When Split the ticket is the selected option, it must include a `➕` line naming the plan's size and the pieces (rule 2). Selecting either without its line is a defect: If the line cannot be written, the rule did not match and the cascade continues.
|
|
18
18
|
|
|
@@ -20,20 +20,20 @@ Present all three options as a numbered list per [option format](#option-format)
|
|
|
20
20
|
|
|
21
21
|
Options that invoke a skill include context-clearing guidance:
|
|
22
22
|
|
|
23
|
-
- **Refine plan**: Prepend "Clear context
|
|
23
|
+
- **Refine plan**: Prepend "Clear context, then..." because the plan artifact is self-contained; prior conversation wastes tokens and can introduce bias.
|
|
24
24
|
- **Split the ticket**: No "Clear context" prefix, and no pasted invocation line; the split runs in this session because the library doesn't have a skill for it, and it cuts the pieces from the saved plan. See [Splitting the ticket](#splitting-the-ticket).
|
|
25
|
-
- **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session or the other harness, in which the skill re-resolves the plan and ticket from the environment.
|
|
25
|
+
- **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session, or into the other harness with its own skill sigil, in which the skill re-resolves the plan and ticket from the environment.
|
|
26
26
|
|
|
27
27
|
Example (rendered for the default case, in which the recommendation rules below select Implement):
|
|
28
28
|
|
|
29
29
|
```
|
|
30
30
|
Next steps:
|
|
31
31
|
1. 🧠 ■□□ Refine plan:
|
|
32
|
-
- Clear context
|
|
32
|
+
- Clear context, then {skill?:refine-plan} with plan: {plan_path}, ticket: {ticket_source}
|
|
33
33
|
2. ✂️ ■□□ Split the ticket:
|
|
34
34
|
- Selection runs the split in this session
|
|
35
35
|
3. 🚀 ■■□ Implement:
|
|
36
|
-
-
|
|
36
|
+
- {skill?:implement-plan} with plan: {plan_path}, ticket: {ticket_source}
|
|
37
37
|
```
|
|
38
38
|
|
|
39
39
|
Skill names for each option:
|
|
@@ -64,9 +64,9 @@ Select the recommended option by checking these rules in order and stopping at t
|
|
|
64
64
|
|
|
65
65
|
When rule 1 matches, the rendered option must name that decision on a `➕` line. Being unable to write the line means rule 1 did not match.
|
|
66
66
|
|
|
67
|
-
2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it
|
|
67
|
+
2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either.
|
|
68
68
|
|
|
69
|
-
A piece
|
|
69
|
+
A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`.
|
|
70
70
|
|
|
71
71
|
Structural properties (new module boundaries, changed interfaces, several packages) make a plan _more likely_ to be too large. They are evidence to weigh, and none of them matches rule 2 on its own.
|
|
72
72
|
|
|
@@ -74,11 +74,11 @@ Select the recommended option by checking these rules in order and stopping at t
|
|
|
74
74
|
|
|
75
75
|
3. **Implement**: All other cases (default), whatever the number of modules or packages that the plan touches. `implement-plan`'s closing menu re-decides the review depth from the realized diff, and it offers a split when the diff proves too large for one review pass, so a plan sent here is not committed to a single pull request.
|
|
76
76
|
|
|
77
|
-
When the work is trivial enough that a review pass would catch nothing meaningful ([complexity levels 1–2](../_data/complexity-classification.md): a typo fix, an unused-import removal, a single-file mechanical rename), add a `➕` line noting that the follow-up review can be skipped at `implement-plan`'s closing menu.
|
|
77
|
+
When the work is trivial enough that a review pass would catch nothing meaningful ([complexity levels 1–2](../_data/complexity-classification.md): a typo fix, an unused-import removal, a single-file mechanical rename), add a `➕` line noting that the follow-up review can be skipped at `implement-plan`'s closing menu. Because that menu decides the review from the diff that the implementation actually produced, a plan-time triviality read is a hint to it rather than a commitment.
|
|
78
78
|
|
|
79
79
|
#### Marker strengths
|
|
80
80
|
|
|
81
|
-
The selected option's marker follows how cleanly its rule matched: ■■■ when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, ■■□ when the fit is good but an alternative stays defensible, ■□□ when little separates the options.
|
|
81
|
+
The selected option's marker follows how cleanly its rule matched: ■■■ when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, ■■□ when the fit is good but an alternative stays defensible, ■□□ when little separates the options. Because rule 3 is the cascade's fallthrough rather than a positive match, its marker follows how squarely rules 1 and 2 failed: ■■■ when neither came close, ■■□ when one stayed defensible. The unselected options take ■□□ by default, and □□□ when one has a clear drawback in the current context.
|
|
82
82
|
|
|
83
83
|
Each skill supplies its own recommendation context (e.g., whether the plan was developed interactively, whether a review just completed). That context applies to rule 1's settled/unsettled test.
|
|
84
84
|
|
|
@@ -96,4 +96,4 @@ Each skill supplies its own recommendation context (e.g., whether the plan was d
|
|
|
96
96
|
|
|
97
97
|
<!-- include: split-launch-prompts.md / -->
|
|
98
98
|
|
|
99
|
-
See [`scope-and-deferral.md`](../_data/scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) is about work that comes up alongside the plan; rule 2 is about the plan's own work, and its seam test comes from the ticketing preferences: A piece
|
|
99
|
+
See [`scope-and-deferral.md`](../_data/scope-and-deferral.md) for the related decision on whether a finding warrants its own ticket. That decision (do now / batch later / separate ticket) is about work that comes up alongside the plan; rule 2 is about the plan's own work, and its seam test comes from the ticketing preferences: A piece gets its own ticket when it can be merged and verified on its own.
|
|
@@ -87,7 +87,7 @@ When the recommendation rules do not indicate a preference, omit markers from bo
|
|
|
87
87
|
#### Recommendation rules
|
|
88
88
|
|
|
89
89
|
1. **Recommend "Update the acceptance criteria"**: The implementation's direction is deliberate and sound, so the criteria as written would lead a later reader to judge correct code wrong.
|
|
90
|
-
2. **Recommend "Leave as-is"**: The review raised a finding on the conflicting behavior. The code is
|
|
90
|
+
2. **Recommend "Leave as-is"**: The review raised a finding on the conflicting behavior. The code is in question, and revising the contract to match it would hide the finding.
|
|
91
91
|
3. **No recommendation** (omit markers from both options): The reviewer cannot tell whether the criteria or the implementation is the wrong one. The user decides.
|
|
92
92
|
|
|
93
93
|
#### Marker strengths
|
|
@@ -206,10 +206,10 @@ Proposed edits to the source:
|
|
|
206
206
|
|
|
207
207
|
1. 🚀 ■■□ Implement directly and commit
|
|
208
208
|
2. 📋 ■□□ Ask the author to address the findings
|
|
209
|
-
3. 📋🔍 ■□□ Wait for the author to address the findings, then
|
|
209
|
+
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
210
210
|
4. 🎫 ■□□ Create a follow-up ticket
|
|
211
211
|
|
|
212
|
-
If the author is an agent, run
|
|
212
|
+
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
213
213
|
```
|
|
214
214
|
|
|
215
215
|
Local-branch variant, rendered when a finding names alternatives that the author owns. The entry states the alternatives; choosing option 1 hands that call to whoever implements:
|
|
@@ -225,10 +225,10 @@ Proposed edits to the source:
|
|
|
225
225
|
|
|
226
226
|
1. 🚀 ■□□ Implement directly and commit
|
|
227
227
|
2. 📋 ■■□ Ask the author to address the findings
|
|
228
|
-
3. 📋🔍 ■□□ Wait for the author to address the findings, then
|
|
228
|
+
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
229
229
|
4. 🎫 ■□□ Create a follow-up ticket
|
|
230
230
|
|
|
231
|
-
If the author is an agent, run
|
|
231
|
+
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
232
232
|
```
|
|
233
233
|
|
|
234
234
|
Local-branch variant, rendered when three findings naming a single change each appear next to one separable recommendation. The ticket option's findings keep their entries, since the user is consenting to their disposition too:
|
|
@@ -250,10 +250,10 @@ Proposed edits to the source:
|
|
|
250
250
|
|
|
251
251
|
1. 🚀 ■■□ Implement directly and commit
|
|
252
252
|
2. 📋 ■□□ Ask the author to address the findings
|
|
253
|
-
3. 📋🔍 ■□□ Wait for the author to address the findings, then
|
|
253
|
+
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
254
254
|
4. 🎫 ■□□ Create a follow-up ticket for R2
|
|
255
255
|
|
|
256
|
-
If the author is an agent, run
|
|
256
|
+
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
257
257
|
```
|
|
258
258
|
|
|
259
259
|
PR variant, rendered for the default case. "Implement directly and commit" is on the menu, so the preview renders here too:
|
|
@@ -277,11 +277,11 @@ Proposed edits to the source:
|
|
|
277
277
|
Per the session-boundary rule, two options name a skill in the render:
|
|
278
278
|
|
|
279
279
|
- **Ask the author to address the findings**: The author's disposition happens in another session. The separate line below the list names `respond-to-review` for the case in which that author is an agent.
|
|
280
|
-
- **Wait for the author to address the findings, then re-review**: Names `review-branch` in the render, because the re-review runs after a wait that only the user can end. It
|
|
280
|
+
- **Wait for the author to address the findings, then re-review**: Names `review-branch` in the render, because the re-review runs after a wait that only the user can end. It does not have a "Clear context" prefix: The saved review records the findings, so the re-review works the same in this session or a fresh one.
|
|
281
281
|
|
|
282
282
|
#### Recommendation rules
|
|
283
283
|
|
|
284
|
-
Both variants share one cascade. Check the rules in order and stop at the first match. Every rule states a firing condition, and an option is never a default that fires for
|
|
284
|
+
Both variants share one cascade. Check the rules in order and stop at the first match. Every rule states a firing condition, and an option is never a default that fires for lack of one: A conditionless option outranks a conditioned one in practice, however the conditions are worded.
|
|
285
285
|
|
|
286
286
|
1. **Create a follow-up ticket**: Every open finding clears one of [`scope-and-deferral.md`](../_data/scope-and-deferral.md)'s affirmative reasons for spinning off, namely a genuinely separable concern, a materially different risk surface, size that would overwhelm the current change, or independent prioritization. "The ticket didn't mention it" is never such a reason. Absent an affirmative reason the fold-in default applies and the cascade continues.
|
|
287
287
|
2. **Implement directly and commit**: Every open finding names a single change rather than a choice among alternatives, which are the two shapes that the [Proposed-change gate](../review-criteria/SKILL.md#proposed-change-gate) admits. Implementing forfeits the second look, and the single-change shape makes that acceptable: The fix's diff is the finding restated, so a reviewer would be re-reading text that the review already contains. One finding leaving its choice to the author is enough to fail this rule, however small the alternatives look, since implementing would settle it on the author's behalf.
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
## Option format
|
|
2
2
|
|
|
3
|
-
**
|
|
3
|
+
**Confirm that the menu is needed before rendering it.** Mark the options first, check the leader as "Check the leader before rendering" below states, then read the markers: Render the menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class below. Decide every other field: State the decision in one line with its reason, record it, and proceed. Decide an all-■□□ field too. An unmarked list is a pure-preference call, and a preference is in the gated class. The rejected alternative belongs in a clause ("X rather than Y, because Z"), never as a numbered option awaiting selection.
|
|
4
4
|
|
|
5
5
|
A determination that has one right answer under a governing document, such as a change's work type under the work-type test, is not a fork. Resolve doubt about which answer the test yields by applying the test and picking: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact. The developer holds less of the evidence than the agent, so handing the doubt back produces a worse-informed answer.
|
|
6
6
|
|
|
7
|
-
The gated class is closed.
|
|
7
|
+
The gated class is closed. Ask about these decisions whatever the markers say:
|
|
8
8
|
|
|
9
9
|
- the shape of a public API or a contract
|
|
10
10
|
- remote shared state: a ticket edit, a push, a merge, the creation of a branch or a ticket
|
|
@@ -12,13 +12,13 @@ The gated class is closed. These decisions are asked whatever the markers say:
|
|
|
12
12
|
- spend or budget
|
|
13
13
|
- a preference for which you do not hold any evidence
|
|
14
14
|
|
|
15
|
-
|
|
15
|
+
Decide everything else yourself by default. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; hold the gated action itself until the developer authorizes it. A templated next-steps menu is in the class, because what to do next is a preference about the developer's time, for which you do not hold any evidence. Verification is never in the gated class: Run a check that a command, a test, or a browser could settle.
|
|
16
16
|
|
|
17
|
-
**Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only
|
|
17
|
+
**Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it ⏳ as "Record what you did not ask" states, and ask at the checkpoint; revise if overruled. In a skill without a phase structure, treat the skill's own approval gate, or the end of its work, as the checkpoint.
|
|
18
18
|
|
|
19
|
-
**Batch, never stream.**
|
|
19
|
+
**Batch, never stream.** Collect the asks that survive the gate into one review at the checkpoint, not one per turn.
|
|
20
20
|
|
|
21
|
-
**Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason
|
|
21
|
+
**Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason; when the work does not have a plan, write it into the turn's summary. Always record: A silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with ⏳, wherever you state it: in the record, and in a turn's narrative, such as a checkpoint summary or a list of decisions. The marker lets the developer find what they may overrule without reading every line. Drop it once the developer approves the checkpoint at which the decision was presented.
|
|
22
22
|
|
|
23
23
|
**Never rank the options by your own elapsed time, round trips, or effort.** You measure these costs yourself, and that measure counts the user's context switch and review cycles as nothing. Measuring one does not make the call yours, and a more accurate measurement still cannot rank the options.
|
|
24
24
|
|
|
@@ -39,33 +39,34 @@ Render every option-style question in this form: any numbered list of 2 or more
|
|
|
39
39
|
| ■□□ | weakly recommended | A slight edge; mostly preference. |
|
|
40
40
|
| □□□ | not recommended | Clear drawbacks; included for completeness or to rule out explicitly. |
|
|
41
41
|
|
|
42
|
-
Marking is all-or-none: Once any option has a marker, every option
|
|
42
|
+
Marking is all-or-none: Once any option has a marker, give every option one. Without a preference (a pure taste call), omit markers from every option and don't explain the omission; the absence is the signal. Mark at the strength that you actually hold: A marker that reads the same whatever the analysis found does not convey any information, and the reader must do all the work of telling a real choice from a formality. Render markers as plain text, never inside backticks; backticks shrink the glyphs and hurt readability.
|
|
43
43
|
|
|
44
|
-
**Format each option** as marker, then title, then a colon.
|
|
44
|
+
**Format each option** as marker, then title, then a colon. Make each pro (`➕`) and con (`➖`) a nested list item beneath its option, without terminal punctuation. Apply this even when an option has only one pro or con. Lead with the strongest argument.
|
|
45
45
|
|
|
46
|
-
|
|
46
|
+
Make every line subordinate to an option (a pro, a con, invocation guidance) a nested list item, never a whitespace-indented continuation. Indentation by spaces, ASCII or non-breaking alike, does not survive terminal rendering: The lines collapse to the left margin, and the reader cannot tell which reason belongs to which option. Markdown structure survives; whitespace does not.
|
|
47
47
|
|
|
48
|
-
|
|
48
|
+
Stop nesting at one level: Never put a sub-option in an option or a sub-pro in a pro. Terminal rendering stops being reliable at deeper nesting, so this contract is written never to need it.
|
|
49
49
|
|
|
50
50
|
**Write only bullets that are real.** Bullets report the weight of each option, not a balance between the options: When the options differ in quality, an uneven menu is the accurate one, and a menu that looks balanced misreports the analysis. A `➕` or `➖` asserts that the reader should weigh it, and bullets render at equal visual weight. A manufactured one reads exactly like a load-bearing one, and it takes a round trip to discover that it was empty. Seven tests:
|
|
51
51
|
|
|
52
52
|
- **Falsifiability.** A `➖` must be false for at least one other option on the menu, and a `➕` likewise. Anything that would still be true if this were the only option is a mechanic of carrying it out rather than a tradeoff; it belongs on the invocation line or nowhere.
|
|
53
53
|
- **Decision weight.** Would a reader who believed this bullet choose differently? Bookkeeping, mechanically-implied, and trivially-reversible consequences (a doc line to update, a criterion to reword, a rename to propagate) are real, specific, and decision-irrelevant. Restatements of an option's inherent properties ("longer wall time", "structured review pass", "ships faster") are one instance of the same failure.
|
|
54
54
|
- **Session context.** Cut a bullet that cites the conversation, what the session holds, or what is "already in context". Every handoff goes through a saved artifact, so session context does not distinguish one option from another, and a bullet that rests on it tells the reader that the artifact is incomplete. When the bullet is true, the artifact has a gap: Add the fact to the artifact rather than citing the session.
|
|
55
|
-
- **Consequence.**
|
|
55
|
+
- **Consequence.** State in a `➖` what breaks or what it costs, and for whom, concretely enough that the reader can weigh it without investigating. Cut a con that cannot be stated that way.
|
|
56
56
|
- **The qualifier tell.** A bullet undercut by its own qualifier ("negligible", "inert", "harmless") is filler. The only repair is to cut the bullet: Deleting the qualifier leaves the same minor con, now looking weighty.
|
|
57
57
|
- **One tradeoff, stated once.** When one option's `➕` restates another option's `➖`, the two options are the sides of one tradeoff. State it once, in a line above the list, rather than as bullets split between the options, which the reader counts as separate reasons.
|
|
58
58
|
- **Check before you hedge.** If a cheap check would settle whether a con is real, run the check. Presenting the uncertainty as a bullet transfers the check to the user.
|
|
59
59
|
|
|
60
|
-
Asymmetry is a report, not a defect.
|
|
60
|
+
Asymmetry is a report, not a defect. Give an option that has three real pros but lacks a real con its three pros, and do not give it a con. Never add a bullet to fill a slot, reach parity between options, or avoid looking one-sided; when the honest cost is hard to find, that difficulty is itself evidence the option is strong. When every option lacks a real bullet, omit them all and let the markers alone convey the recommendation. Do not add tiebreaker text for equal-strength options; the developer picks the number.
|
|
61
61
|
|
|
62
|
-
|
|
62
|
+
Keep on a `□□□` option the `➖` that explains why you ruled it out. Under the falsifiability test that bullet is real by construction, and without it the reader is left with a veto that they cannot check.
|
|
63
63
|
|
|
64
|
-
**Check the leader before rendering.** Once the bullets
|
|
64
|
+
**Check the leader before rendering.** Once you have drafted the bullets, and before you read the markers against the gate, run this check. It applies to a gated decision as fully as to any other: The menu renders whatever the markers say, and the marker tells the developer how much deliberation the ask needs.
|
|
65
65
|
|
|
66
|
-
1. For each
|
|
67
|
-
2.
|
|
68
|
-
3. Re-
|
|
66
|
+
1. For each alternative, look for a cost that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand. When you find one, state it as the alternative's `➖`.
|
|
67
|
+
2. For each `➖` on the strongest-marked option, name the reader who would choose differently because of it. Cut the bullet if there is none.
|
|
68
|
+
3. Re-mark the options. When every alternative has a disqualifying `➖`, mark the leader ■■■. The observed bias is a marker set too weak, not one set too strong.
|
|
69
|
+
4. Re-apply the gate. Outside the gated class, a leader marked above every other option means that the field is decided: State the decision in one line, and do not render a menu. Inside the class, render the menu with the leader's marker as the check set it.
|
|
69
70
|
|
|
70
71
|
**Identify each question** when a single response contains 2 or more option-style questions: Prefix them `Q1`, `Q2`, and so on, so that the user can reference answers unambiguously. When the underlying data already has stable identifiers (plan-review findings such as `C1` or `X2`), use those in place of `Q1`/`Q2`. For a single option-style question, omit the identifier. Inside an [action-items block](../_data/action-items.md), identifiers are mandatory whenever the block contains more than one item (or more than one independently-numbered list), and they distinguish actions (`A`) from questions (`Q`).
|
|
71
72
|
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
|
|
14
14
|
## Decisions taken
|
|
15
15
|
|
|
16
|
-
- {A decision that the agent took without asking, with its one-line reason
|
|
16
|
+
- {⏳ while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason}
|
|
17
17
|
|
|
18
18
|
## Tasks
|
|
19
19
|
|
|
@@ -50,19 +50,19 @@
|
|
|
50
50
|
|
|
51
51
|
`## Dependencies` (external dependencies or blockers) is the one optional section: Insert it between `## Risks` and `## Verification` only when the plan has external blockers, and omit it otherwise.
|
|
52
52
|
|
|
53
|
-
**Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion (e.g., "New/modified behavior is covered by tests"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests it would
|
|
53
|
+
**Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
|
|
54
54
|
|
|
55
55
|
**Per-task documentation criterion:** When a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include updating documentation, help text, and usage examples, including removal of references to anything that no longer exists.
|
|
56
56
|
|
|
57
57
|
**Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
|
|
58
58
|
|
|
59
|
-
**Per-task interface guidance:** When a task defines colour tokens, styles text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} while planning the task. Its key decisions state the
|
|
59
|
+
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
|
|
60
60
|
|
|
61
|
-
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data.
|
|
61
|
+
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge.
|
|
62
62
|
|
|
63
63
|
**Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
|
|
64
64
|
|
|
65
|
-
**Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that
|
|
65
|
+
**Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that the tests do not assert. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
|
|
66
66
|
|
|
67
67
|
Before (a verification task handed to the developer):
|
|
68
68
|
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
Selecting Split is the developer's consent to the split at the seam that its `➕` line names. Nothing is created before that selection, and the bodies get one confirmation before anything is created.
|
|
2
2
|
|
|
3
|
-
**Compose.** Compose a ticket body per piece (problem, context, acceptance criteria) from the piece's work and the ticket's criteria. Compose the originating ticket's new body as well: With two pieces, rewrite it to the first piece, so that the originating ticket and one new ticket
|
|
3
|
+
**Compose.** Compose a ticket body per piece (problem, context, acceptance criteria) from the piece's work and the ticket's criteria. Compose the originating ticket's new body as well: With two pieces, rewrite it to the first piece, so that the originating ticket and one new ticket cover the two pieces; with three or more, make it an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. When the work does not have a governing ticket, every piece is a new ticket and there is nothing to rewrite.
|
|
4
4
|
|
|
5
5
|
**Confirm once.** Show every body, every relationship, and everything that the steps below create or change in one block, and confirm once. This single confirmation stands in for the per-ticket confirmation that `{skill:create-ticket}` would otherwise raise for each piece.
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
**Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. For a piece that depends on an earlier piece
|
|
1
|
+
**Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. For a piece that depends on an earlier piece being merged first, pass `--blocked-by` naming that piece's reference, which exists by then.
|
|
2
2
|
|
|
3
3
|
**Rewrite the originating ticket.** Write the originating ticket's new body per the platform-specific write in [ticket source resolution](../_data/ticket-source-resolution.md#platform-specific-write).
|
|
@@ -7,7 +7,7 @@ The handoff test has two halves, and each needs a different reader. The sweep ch
|
|
|
7
7
|
**Sweep for:**
|
|
8
8
|
|
|
9
9
|
- Settled decisions, including the rejected alternatives.
|
|
10
|
-
- Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked
|
|
10
|
+
- Decisions that the agent took without asking: Every one is in the plan's `## Decisions taken` section, with its reason, marked ⏳ when it awaits this checkpoint.
|
|
11
11
|
- Constraints and scope boundaries on which the conversation agreed.
|
|
12
12
|
- Edge cases and success criteria raised in discussion but missing from the acceptance criteria.
|
|
13
13
|
- Tacit context of the form "the implementer might not realize X": What the conversation established as known and the artifacts leave the reader to rediscover.
|
|
@@ -24,7 +24,7 @@ plan: {plan draft path}
|
|
|
24
24
|
root: {repository root}
|
|
25
25
|
```
|
|
26
26
|
|
|
27
|
-
The block contains scalars only, and only these keys. Do not compose any prose into it: A sentence written here
|
|
27
|
+
The block contains scalars only, and only these keys. Do not compose any prose into it: A sentence written here gives the reader the session's knowledge, and the pass is worth nothing once the reader shares what the writer knows.
|
|
28
28
|
|
|
29
29
|
**A reply that lacks the `Phase: handoff-review` return block is a reviewer stopped by its turn limit.** Resume that reviewer once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. The resumption continues the same dispatch, so it is not the second dispatch that the pass forbids. When the harness cannot resume a subagent, or the resumed reviewer still does not return a report, do not dispatch again: Save the drafts without the pass, and report that the handoff pass did not return a report, even when the sweep found nothing.
|
|
30
30
|
|
|
@@ -1,7 +1,7 @@
|
|
|
1
|
-
**Test criterion convention:** When writing a ticket that changes testable behavior, include a test criterion in its acceptance criteria (e.g., "New/modified behavior in this change is covered by tests"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests it would
|
|
1
|
+
**Test criterion convention:** When writing a ticket that changes testable behavior, include a test criterion in its acceptance criteria that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior in this change is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
|
|
2
2
|
|
|
3
3
|
**Documentation criterion convention:** When writing a ticket that adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), include in its acceptance criteria the corresponding updates to documentation, help text, and usage examples, including removal of references to anything that no longer exists.
|
|
4
4
|
|
|
5
|
-
**Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must
|
|
5
|
+
**Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must be merged before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
|
|
6
6
|
|
|
7
|
-
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever
|
|
7
|
+
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration.
|
|
@@ -8,9 +8,9 @@ user-invocable: true
|
|
|
8
8
|
|
|
9
9
|
Append a `change-record` block to a pull request whose body has none, so that the merge publishes the change entries.
|
|
10
10
|
|
|
11
|
-
The block is drafted by `{skill:summarize-change}`, which consolidates the branch, draws the entries, audits them, and renders the block. This skill
|
|
11
|
+
The block is drafted by `{skill:summarize-change}`, which consolidates the branch, draws the entries, audits them, and renders the block. This skill copies the rendered block from the summary that the run saved and appends it to the pull-request body; it drafts nothing of its own.
|
|
12
12
|
|
|
13
|
-
**A block that is already written is never replaced.** A readable block, a malformed one, and one that does not record an entry are all left for the author to repair by hand, as [the change record](../_data/change-record.md#where-the-record-is-read) states. This skill adds a block only
|
|
13
|
+
**A block that is already written is never replaced.** A readable block, a malformed one, and one that does not record an entry are all left for the author to repair by hand, as [the change record](../_data/change-record.md#where-the-record-is-read) states. This skill adds a block only to a body that does not contain one.
|
|
14
14
|
|
|
15
15
|
## Arguments
|
|
16
16
|
|
|
@@ -49,7 +49,7 @@ When aligning to an existing implementation, _the implementation_ is the code on
|
|
|
49
49
|
|
|
50
50
|
### Two branches
|
|
51
51
|
|
|
52
|
-
What the skill does
|
|
52
|
+
What the skill does depends on whether a prior ticket exists, not on how the caller scoped the call.
|
|
53
53
|
|
|
54
54
|
**Generation, when a prior ticket does not exist.** The work was done on the branch without a ticket, so every section is authored now from the implementation and nothing is overwritten. The skeleton's `## Proposed solution` section is forward-looking by default; here it records the approach that the branch actually took, not a proposal still under consideration.
|
|
55
55
|
|
|
@@ -96,7 +96,7 @@ The skill writes two artifacts: the ticket of record on its platform, and a loca
|
|
|
96
96
|
|
|
97
97
|
**`--write-target=local` writes the local artifact alone.** The ticket of record is left as it stands, however it resolved. The override selects the target and nothing else: The mode still bounds the revision, and the no-delta confirmation still precedes the write. `--write-target=remote` states the default explicitly and, when a ticket of record does not resolve, stops and reports the missing target rather than falling back to the local artifact.
|
|
98
98
|
|
|
99
|
-
**Order and reporting.** Write the remote, then save the local artifact, then report. A remote write that fails leaves the artifact saved and is reported as a failure, naming the manual step that remains; when the remote did not resolve, or `--write-target=local`
|
|
99
|
+
**Order and reporting.** Write the remote, then save the local artifact, then report. A remote write that fails leaves the artifact saved and is reported as a failure, naming the manual step that remains; when the remote did not resolve, or `--write-target=local` excluded it, report that the remote was not updated and which of the two is the reason.
|
|
100
100
|
|
|
101
101
|
### Path resolution
|
|
102
102
|
|
|
@@ -34,7 +34,7 @@ Common but problematic approaches that should be avoided in favor of proper solu
|
|
|
34
34
|
### Suppression directives
|
|
35
35
|
|
|
36
36
|
- **A suppression directive (a comment that tells a linter or type checker to ignore a specific warning) is a design signal, not a workaround.** The rule flagged the code because it matched a pattern that is usually wrong.
|
|
37
|
-
- **Try these in order before suppressing inline:** (1) change the code so that the rule no longer triggers, usually the right answer; (2) reconfigure the rule if its default is wrong for the project; (3) define a scoped exception for a whole category that is legitimately exempt. Suppress inline only as a last resort, when the case is genuinely local and none of the above fits, such as an external boundary
|
|
37
|
+
- **Try these in order before suppressing inline:** (1) change the code so that the rule no longer triggers, usually the right answer; (2) reconfigure the rule if its default is wrong for the project; (3) define a scoped exception for a whole category that is legitimately exempt. Suppress inline only as a last resort, when the case is genuinely local and none of the above fits, such as an external boundary at which the real type can't be known.
|
|
38
38
|
- **An `any` or a type assertion suppresses in the language what a directive suppresses in a comment.** Both silence the checker without changing what the code does, so the same ladder applies to both: Model the type that the value actually has, or return `unknown` and let the caller narrow it.
|
|
39
39
|
- **Write a rationale for every suppression that you introduce**, naming the rule, why it doesn't apply here, and what alternatives you rejected. Restating the rule is not a rationale.
|
|
40
40
|
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: assess-usability
|
|
3
|
+
description: Assess a product's usability through three to five lenses, one subagent per lens walking its use cases in a browser or a shell, and merge their reports into a ranked findings artifact that a triage pass can dispose of. Use when asked to evaluate a site's, an app's, or a CLI's usability, or to find the bugs, flaws, and obvious gaps that a user would meet.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
supported-harnesses: [claude]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Assess usability
|
|
9
|
+
|
|
10
|
+
Find where a product would lead its users to conclude that it is broken or unfinished. Each lens is a {subagent:usability-assessor} that walks its use cases in a browser or, for a command-line product, in a shell, without seeing any other lens's report. You prepare the targets, write the brief that every lens reads, dispatch the lenses one at a time, and merge their reports into one findings artifact.
|
|
11
|
+
|
|
12
|
+
The skill writes nothing remote: It does not create a ticket, post a comment, or edit an issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
|
|
13
|
+
|
|
14
|
+
## Inputs
|
|
15
|
+
|
|
16
|
+
- **The medium**: `browser` (default) or `cli`, as the developer names it.
|
|
17
|
+
- **The targets**: under `browser`, the URLs or local stacks to assess; under `cli`, the package whose binary is assessed.
|
|
18
|
+
- **The roles**: the kinds of user that the product serves, such as a signed-out visitor, a member, and an administrator. When the developer does not name them, derive them under `browser` from the repository's routes and its auth model, and under `cli` from the CLI's commands and documented workflows. Under `cli`, ask at the checkpoint for a routine-use role, such as the user who runs one command daily, which the command list does not show.
|
|
19
|
+
- **The ticket**, optional. Without one in session, `{skill:save-artifact}` saves the artifacts under the ticket ID that it generates.
|
|
20
|
+
|
|
21
|
+
Read the declared stage of the project under assessment from `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`. When `project_sensitivity` is `personal` or `confidential`, every lens uses seeded or test data only, and no target that holds real users' data is used for anything but reading public pages.
|
|
22
|
+
|
|
23
|
+
## Process
|
|
24
|
+
|
|
25
|
+
### 1. Prepare the targets
|
|
26
|
+
|
|
27
|
+
Resolve the ticket directory per {skill:save-artifact}, and create `{ticket_dir}/usability/`. Then prepare the targets for the medium.
|
|
28
|
+
|
|
29
|
+
Under `browser`:
|
|
30
|
+
|
|
31
|
+
- **The browser.** The lenses share one browser that the Playwright MCP server drives, so they run one after another. Confirm that the browser responds before anything else; when it does not, ask the developer for one and stop.
|
|
32
|
+
- **The local stack.** When a target is local, confirm that it runs, and start it by the repository's own scripts when it does not. Use a development build that connects only to the local stack, never a script that connects to a hosted service.
|
|
33
|
+
- **Sign-in state.** For each hosted target, find out whether the browser profile is signed in on it. A lens opens its own browser context for a signed-out view; nothing signs the profile out.
|
|
34
|
+
|
|
35
|
+
Under `cli`:
|
|
36
|
+
|
|
37
|
+
- **The build.** Build the package by the repository's own build script, never a shim that runs source, as a dev server is excluded under `browser`.
|
|
38
|
+
- **The invocation.** Choose how a lens runs the binary: the built binary by absolute path by default, or the packed package installed into each fixture when the product's documentation describes installation as how it is used.
|
|
39
|
+
- **The readiness check.** Create a scratch fixture as step 2 describes, and confirm that `<bin> --version` exits 0 from it. When the build or the check fails, report the failure to the developer and stop.
|
|
40
|
+
- **Network and credential state.** For each host that the product reaches, find out whether this machine can reach it and whether a credential is present. A lens never uses the developer's credentials; a host that it cannot reach is recorded as `not exercised`.
|
|
41
|
+
|
|
42
|
+
### 2. Write the brief
|
|
43
|
+
|
|
44
|
+
Compose the brief with these sections. Each names its `browser` form, then its `cli` form when the two differ.
|
|
45
|
+
|
|
46
|
+
1. **Product.** What the product is and whom it serves, in two or three sentences.
|
|
47
|
+
2. **Targets.** One row per target: its URL, its write rule, its sign-in state, and the method by which a lens grants itself a role or an approval there. A target is read-only unless it is on `localhost` or the developer names it as disposable, per {rulebook:shared-data-conventions}. Writes go to a writable target, with `@example.com` accounts that the lens creates. Under `cli`, one row per target: the binary and its invocation, its write rule, its network and credential state, and what a lens may install. The checkout and every remote source are read-only; each lens's fixture is writable, and its git author is the only identity.
|
|
48
|
+
3. **Lenses.** Three to five: one per role, and one for styling and access. Give each a unique ID prefix (two roles can share an initial), its targets, and its minimum use cases, each with its route. The styling-and-access lens covers light and dark mode, a 1440×900 and a 390×844 viewport, and keyboard-only use of the other lenses' core flows, against the floors in {rulebook:accessibility-conventions}. It runs last, so that it can reach every screen that the earlier lenses found. Under `cli`, each use case has its command lines, and the last lens is output-and-access: the CLI's `--style` or equivalent option, `NO_COLOR`, TTY versus pipe when the developer opted in to `script` and pipe output otherwise, 80 columns, and help and error text, of the other lenses' core flows. Each lens also has its fixture: Create it now with `mktemp -d "${TMPDIR:-/tmp}/usability-{lens slug}.XXXXXX"`, outside the checkout and the artifact directory, as a git repository with `user.name` `Usability Assessor` and `user.email` `assessor@example.com` set locally and one empty initial commit, and name its absolute path in the lens's row.
|
|
49
|
+
4. **Exclusions.** Routes, surfaces, and products out of scope, such as a developer-only page or a browser extension; under `cli`, commands, flags, and modes, such as one that runs source.
|
|
50
|
+
5. **Settled.** The decisions above, stated as final, so that a lens does not re-decide them. State the medium as `medium: browser` or `medium: cli`. Under `cli`, also state the pseudo-terminal rule: A lens measures line lengths in captured output rather than observing a terminal, and runs `script` only when the developer opts in at the checkpoint.
|
|
51
|
+
|
|
52
|
+
### 3. Checkpoint
|
|
53
|
+
|
|
54
|
+
Save the brief with {skill:save-artifact} as a ticket-level `usability-brief` artifact, and show it to the developer. Ask in one action-items block for approval of the brief, and for any target that the developer wants to mark disposable. Under `cli`, also ask whether a lens may run `script` for pseudo-terminal observation, and record the answer under **Settled**. Do not dispatch any lens before approval.
|
|
55
|
+
|
|
56
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
57
|
+
|
|
58
|
+
### 4. Dispatch the lenses
|
|
59
|
+
|
|
60
|
+
Dispatch one lens at a time, under either medium, in the order of the brief's lens table, and wait for each to return before dispatching the next. Create `{ticket_dir}/usability/{lens slug}/` before dispatching each lens. Send one {tool:Task} call, `subagent_type: usability-assessor`, with this block and nothing else composed into it:
|
|
61
|
+
|
|
62
|
+
```dispatch
|
|
63
|
+
brief: {path to the saved brief}
|
|
64
|
+
lens: {lens name}
|
|
65
|
+
output: {ticket_dir}/usability/{lens slug}/
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Never pass one lens's report, or anything learned from it, to a later lens: Each lens's value is its independent view, and the synthesis removes the duplicates.
|
|
69
|
+
|
|
70
|
+
**A reply that lacks the `Phase: usability-assessment` line is a lens stopped by its turn limit.** Resume that lens 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 lens still does not return a report, do not dispatch it again: Record the lens as not reported, and continue with the next.
|
|
71
|
+
|
|
72
|
+
Save each report as `{ticket_dir}/usability/{lens slug}-report.md` as soon as it returns.
|
|
73
|
+
|
|
74
|
+
### 5. Synthesize
|
|
75
|
+
|
|
76
|
+
Merge the reports into one findings document:
|
|
77
|
+
|
|
78
|
+
- **Ranked findings.** Merge findings that describe one problem across lenses, keeping every source ID and every evidence path. Rank by effect (blocks, slows, confuses, polish), then by reach: the number of distinct use cases, across all lenses, in whose flow the finding was reported. A merged finding takes the strongest effect of its sources and states `Reproduced: yes` when any source does.
|
|
79
|
+
- **Use cases.** Each lens's use cases with their outcomes.
|
|
80
|
+
- **Ideas.** Every lens's ideas, with duplicates merged and each one's source IDs kept. An idea never enters the ranked findings.
|
|
81
|
+
- **Proposed groupings.** Findings that one change would fix, grouped, each group with a one-line title and its finding IDs. Do not search the tracker or file anything: `triage-spike-findings` checks each group against the open issues.
|
|
82
|
+
- **Residual unknowns.** Every use case marked `not exercised`, every entry under a report's **Limits**, and every lens recorded as not reported.
|
|
83
|
+
- **Method.** One paragraph: the lenses, the targets with their write rules, and the order of the runs.
|
|
84
|
+
- **Lens reports.** Each report, appended unedited.
|
|
85
|
+
|
|
86
|
+
Write every evidence path relative to `{ticket_dir}`, so that a later session can open the evidence that a finding cites.
|
|
87
|
+
|
|
88
|
+
### 6. Save and publish
|
|
89
|
+
|
|
90
|
+
Save the document with {skill:save-artifact} as a ticket-level `usability-findings` artifact.
|
|
91
|
+
|
|
92
|
+
Then publish it as an artifact page: Load the artifact-design skill, and render the ranked findings as a table that can be filtered by effect, followed by the ideas and the residual unknowns. List each finding's evidence paths; do not embed the screenshots or the transcripts.
|
|
93
|
+
|
|
94
|
+
### 7. Report
|
|
95
|
+
|
|
96
|
+
Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas. Name `triage-spike-findings` as the next step, with the findings artifact's path as its input.
|
|
@@ -43,7 +43,7 @@ A value-bearing flag accepts both `--summary text` and `--summary=text`. The eve
|
|
|
43
43
|
|
|
44
44
|
### Store selection
|
|
45
45
|
|
|
46
|
-
`--store` is required: Every capture names its destination. The helper resolves the store by registry name only. It never walks the working directory for a `.kb/` folder, so a capture goes to the named store and never to a project-local KB near which it happened to be invoked. The store must be registered in `kb.yaml`.
|
|
46
|
+
`--store` is required: Every capture names its destination. The helper resolves the store by registry name only. It never walks the working directory for a `.kb/` folder, so a capture goes to the named store and never to a project-local KB near which it happened to be invoked. The store must be registered in `kb.yaml`. The helper refuses a capture that omits `--store`, with an error that lists the registered stores, rather than defaulting silently.
|
|
47
47
|
|
|
48
48
|
Choose the destination deliberately. When the lesson is specific to a project, pass that project's KB with `--store <name>`. Only when the lesson is environment-level, meaning an observation or refinement that applies across every project in the current environment, send it to the registry's `default_kb` by passing `--store @default`. Selecting the default is an explicit act, not what happens when the flag is forgotten.
|
|
49
49
|
|
|
@@ -51,7 +51,7 @@ A caller whose destination is a configured role rather than a per-lesson judgmen
|
|
|
51
51
|
|
|
52
52
|
### Amending an event
|
|
53
53
|
|
|
54
|
-
`--amend <id>` rewrites an existing capture in place (for example, an event that a `capture-feedback` pass got wrong). Prefer amending over capturing a near-duplicate. Amend always rewrites `summary` and the body from the invocation. It overwrites `--skill`, `--model`, `--tags`, or `--impact` only when you pass that flag; any you omit keep their existing value, as do the provenance fields (`id`, `captured-at`, `session`, `cwd`, `repo`, `harness`) and any `addressed-by` marks. To clear a curatorial field rather than edit content, use its `kb-update-events` mutator.
|
|
54
|
+
`--amend <id>` rewrites an existing capture in place (for example, an event that a `capture-feedback` pass got wrong). Prefer amending over capturing a near-duplicate. Amend always rewrites `summary` and the body from the invocation. It overwrites `--skill`, `--model`, `--tags`, or `--impact` only when you pass that flag; any that you omit keep their existing value, as do the provenance fields (`id`, `captured-at`, `session`, `cwd`, `repo`, `harness`) and any `addressed-by` marks. To clear a curatorial field rather than edit content, use its `kb-update-events` mutator.
|
|
55
55
|
|
|
56
56
|
Amend is a plain in-place edit and does not consult push state. To correct an event that may already have been shared, prefer appending a supersession with `kb-update-events --add-addressed-by` over rewriting it, so that the correction becomes a new record rather than a change to history.
|
|
57
57
|
|