codeassembly-guidance 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (101) hide show
  1. package/.meta/changelog.json +261 -0
  2. package/CHANGELOG.md +62 -0
  3. package/README.md +47 -29
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/plain-speech.md +2 -2
  7. package/content/_partials/ticket-assessment.md +3 -3
  8. package/content/codeassembly-content.yaml +6 -0
  9. package/content/collections/recommended.md +6 -0
  10. package/content/collections/williamthorsen.md +2 -1
  11. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  12. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  13. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  14. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +6 -2
  17. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  20. package/content/guidance/shared/AGENTS.md +2 -3
  21. package/content/scripts/README.md +1 -1
  22. package/content/scripts/check-branch-currency.mjs +7 -7
  23. package/content/scripts/check-prose.mjs +38 -38
  24. package/content/scripts/describe-change.mjs +32 -32
  25. package/content/scripts/manage-jira-ticket.mjs +148 -146
  26. package/content/scripts/validate-preferences.mjs +9 -9
  27. package/content/skills/_data/artifact-conventions.md +3 -3
  28. package/content/skills/_data/entry-points.md +1 -1
  29. package/content/skills/_data/reduced-object-relatives.md +15 -0
  30. package/content/skills/_data/spike-conventions.md +9 -2
  31. package/content/skills/_data/ticket-evaluation.md +3 -0
  32. package/content/skills/_partials/implementation-order-list.md +4 -4
  33. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  34. package/content/skills/_partials/plan-template.md +1 -1
  35. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  36. package/content/skills/_partials/split-ticket-create.md +1 -1
  37. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  38. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  39. package/content/skills/analyze-performance/SKILL.md +1 -1
  40. package/content/skills/assess-code-health/SKILL.md +4 -4
  41. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  42. package/content/skills/assess-ticket/SKILL.md +3 -1
  43. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  44. package/content/skills/assess-usability/SKILL.md +4 -4
  45. package/content/skills/capture-event/capture-event.mjs +30 -30
  46. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  47. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +37 -37
  48. package/content/skills/collaborate/SKILL.md +1 -1
  49. package/content/skills/condense-branch/SKILL.md +18 -36
  50. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  51. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  52. package/content/skills/create-commit/SKILL.md +1 -1
  53. package/content/skills/create-devlog/SKILL.md +4 -4
  54. package/content/skills/create-gh-pr/SKILL.md +9 -11
  55. package/content/skills/create-pr/SKILL.md +9 -11
  56. package/content/skills/create-ticket/SKILL.md +22 -15
  57. package/content/skills/curate-feedback/SKILL.md +2 -2
  58. package/content/skills/derive-session-context/derive-session-context.mjs +103 -103
  59. package/content/skills/design-and-plan/SKILL.md +6 -6
  60. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  61. package/content/skills/implement-plan/SKILL.md +1 -1
  62. package/content/skills/implementation-order/implementation-order.mjs +29 -29
  63. package/content/skills/index-prototypes/SKILL.md +2 -2
  64. package/content/skills/investigate-spike/SKILL.md +3 -3
  65. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  66. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  67. package/content/skills/list-implementation-order/SKILL.md +2 -2
  68. package/content/skills/merge-bb-pr/SKILL.md +9 -11
  69. package/content/skills/merge-gh-pr/SKILL.md +9 -11
  70. package/content/skills/merge-pr/SKILL.md +10 -12
  71. package/content/skills/plan/SKILL.md +2 -2
  72. package/content/skills/prepare-prototype-brief/SKILL.md +2 -2
  73. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  74. package/content/skills/refine-plan/SKILL.md +3 -3
  75. package/content/skills/refine-prototype/SKILL.md +2 -1
  76. package/content/skills/respond-to-review/SKILL.md +4 -4
  77. package/content/skills/review-bb-pr/SKILL.md +1 -2
  78. package/content/skills/review-branch/SKILL.md +18 -13
  79. package/content/skills/review-criteria/SKILL.md +1 -1
  80. package/content/skills/review-gh-pr/SKILL.md +1 -2
  81. package/content/skills/review-pr/SKILL.md +2 -3
  82. package/content/skills/revise-prose/revise-prose.mjs +52 -52
  83. package/content/skills/save-artifact/SKILL.md +4 -6
  84. package/content/skills/save-plan/SKILL.md +2 -2
  85. package/content/skills/start-ticket/SKILL.md +1 -1
  86. package/content/skills/streamline-guidance/streamline-guidance.mjs +24 -24
  87. package/content/skills/summarize-change/SKILL.md +5 -4
  88. package/content/skills/summarize-chat/SKILL.md +2 -2
  89. package/content/skills/triage-feedback/SKILL.md +2 -2
  90. package/content/skills/triage-spike-findings/SKILL.md +26 -22
  91. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  92. package/content/skills/update-project-guidance/SKILL.md +1 -1
  93. package/content/skills/wrap-up/SKILL.md +4 -4
  94. package/content/skills/write-progress-report/SKILL.md +111 -0
  95. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  96. package/content/subagents/disposition-challenger.md +7 -6
  97. package/content/subagents/entry-drafter.md +2 -0
  98. package/content/subagents/usability-assessor.md +3 -2
  99. package/package.json +11 -10
  100. package/schemas/preferences.v1.json +9 -1
  101. package/schemas/work-types.v1.json +1 -1
@@ -33,7 +33,9 @@ Obtain the base SHA via `git rev-parse --short HEAD`.
33
33
 
34
34
  ### 4. Next steps
35
35
 
36
- After presenting the assessment output, evaluate whether any verdicts are non-baseline and, if so, present follow-up actions. Follow [next steps after assessment](next-steps-after-assessment.md) for the verdict-to-actions mapping, combination rules, and interaction protocol, and [Baseline verdicts](#baseline-verdicts) for the baseline definition.
36
+ After presenting the assessment output, evaluate whether any verdicts are non-baseline and, if so, present follow-up actions. Follow [next steps after assessment](next-steps-after-assessment.md) for the verdict-to-actions mapping, combination rules, and interaction protocol, [option format](#option-format) for the list's form, and [Baseline verdicts](#baseline-verdicts) for the baseline definition.
37
+
38
+ <!-- include: ../_partials/option-format.md / -->
37
39
 
38
40
  <!-- include: ../_partials/action-items.md / -->
39
41
 
@@ -66,33 +66,30 @@ When multiple dimensions produce non-baseline verdicts, their actions are combin
66
66
 
67
67
  ## Output format
68
68
 
69
- ```
70
- Next steps:
71
- 1. ♻️ {Update action}
72
- 2. 🏁 {Close action}
73
- 3. 💬 {Comment action}
74
- ```
69
+ Render the list per [option format](SKILL.md#option-format), with each action's icon before its marker. The list always renders, whatever the markers say, because every action writes to the ticket.
70
+
71
+ Mark each action at the strength that the evidence behind its verdict supports. When two actions answer the same verdict, such as an update and a close for `severe` drift, the one that the evidence favors leads.
75
72
 
76
73
  ## Example: Combined output
77
74
 
78
- Assessment produces drift: `partial`, relevance: `relevant` (baseline), progress: `partial`:
75
+ Assessment produces drift: `partial`, relevance: `relevant` (baseline), progress: `partial`, and the remaining work is a small part of the ticket:
79
76
 
80
77
  ```
81
78
  Next steps:
82
- 1. ♻️ Update ticket to match current codebase state
83
- 2. 🏁 Close and create a new ticket scoped to remaining work
79
+ 1. ♻️ ■□□ Update ticket to match current codebase state
80
+ 2. 🏁 ■■□ Close and create a new ticket scoped to remaining work
84
81
  ```
85
82
 
86
- Action 1 combines drift and progress update triggers into a single option. Action 2 comes from progress. Relevance is baseline and contributes nothing.
83
+ Action 1 combines drift and progress update triggers into a single option. Action 2 comes from progress, and leads because a new ticket scoped to the small remainder states the work more plainly than a revised one. Relevance is baseline and contributes nothing.
87
84
 
88
85
  ## Example: Distinct ♻️ flavors
89
86
 
90
- Assessment produces drift: `partial` and advisability: `questionable` (other dimensions baseline):
87
+ Assessment produces drift: `partial` and advisability: `questionable` (other dimensions baseline), and the advisability concern changes the ticket's scope:
91
88
 
92
89
  ```
93
90
  Next steps:
94
- 1. ♻️ Update ticket to match current codebase state
95
- 2. ♻️ Revise ticket to address advisability concerns
91
+ 1. ♻️ ■□□ Update ticket to match current codebase state
92
+ 2. ♻️ ■■□ Revise ticket to address advisability concerns
96
93
  ```
97
94
 
98
- Both actions share the ♻️ icon but represent distinct intents (factual sync with the codebase versus content/scope rework), so they appear as separate numbered options rather than collapsing under the dedupe rule.
95
+ Both actions share the ♻️ icon but represent distinct intents (factual sync with the codebase versus content/scope rework), so they appear as separate numbered options rather than collapsing under the dedupe rule. The revision leads because a scope change also rewrites the parts that the update would sync.
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
9
9
 
10
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
11
 
12
- When the findings leave nothing to triage, the skill's remote writes are the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and the ticket's close, both made on one consent from the developer; otherwise the triage round makes both. It does not create a ticket or edit any other issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
12
+ When the findings leave nothing to triage, or the ticket is not on a [triage platform](../_data/spike-conventions.md#triage-platforms), the skill's remote writes are the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and the ticket's close, both made on one consent from the developer; otherwise the triage round makes both. It does not create a ticket or edit any other issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
13
13
 
14
14
  ## Inputs
15
15
 
@@ -45,7 +45,7 @@ Compose the brief with these sections. Each names its `browser` form, then its `
45
45
 
46
46
  1. **Product.** What the product is and whom it serves, in two or three sentences.
47
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.
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} and {rulebook:visual-design-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
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
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
51
 
@@ -95,6 +95,6 @@ Then publish it as an artifact page: Load the artifact-design skill, and render
95
95
 
96
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.
97
97
 
98
- When the artifact has any finding or idea, name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states. Findings above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
98
+ When the artifact has any finding or idea and the ticket is on a [triage platform](../_data/spike-conventions.md#triage-platforms), name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states. Findings above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
99
99
 
100
- Otherwise, offer to close the ticket with the closing post in the same response's action-items block. The post's contents, the consent, and the checks that a rerun relies on are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the use cases exercised and the page's URL.
100
+ Otherwise, name the findings and ideas left for disposal by hand when there are any, and offer to close the ticket with the closing post in the same response's action-items block. The post's contents, the consent, and the checks that a rerun relies on are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the use cases exercised and the page's URL.