codeassembly-guidance 0.2.0 → 0.3.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 (88) hide show
  1. package/.meta/changelog.json +227 -0
  2. package/CHANGELOG.md +59 -0
  3. package/README.md +37 -121
  4. package/content/_partials/README.md +19 -3
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/kb-standard-tags.md +7 -0
  7. package/content/codeassembly-content.yaml +6 -0
  8. package/content/collections/recommended.md +1 -1
  9. package/content/guidance/README.md +1 -1
  10. package/content/guidance/rulebooks/cli-conventions.md +16 -2
  11. package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
  12. package/content/guidance/rulebooks/commit-conventions.md +3 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
  14. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  15. package/content/guidance/shared/AGENTS.md +31 -4
  16. package/content/scripts/check-prose.mjs +38 -38
  17. package/content/scripts/describe-change.mjs +69 -69
  18. package/content/scripts/manage-jira-ticket.mjs +73 -73
  19. package/content/scripts/validate-preferences.mjs +1 -1
  20. package/content/skills/_data/action-items.md +2 -0
  21. package/content/skills/_data/artifact-conventions.md +18 -2
  22. package/content/skills/_data/complexity-classification.md +1 -1
  23. package/content/skills/_data/design-priorities.md +12 -1
  24. package/content/skills/_data/spike-conventions.md +21 -6
  25. package/content/skills/_data/title-templates.md +3 -1
  26. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  27. package/content/skills/_partials/commit-title-rendering.md +1 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +1 -1
  29. package/content/skills/_partials/option-format.md +2 -2
  30. package/content/skills/_partials/plan-template.md +4 -2
  31. package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
  32. package/content/skills/_partials/ticket-composition.md +40 -0
  33. package/content/skills/_partials/ticket-skeleton.md +15 -1
  34. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
  35. package/content/skills/assess-code-health/SKILL.md +127 -0
  36. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  37. package/content/skills/assess-usability/SKILL.md +3 -1
  38. package/content/skills/capture-event/SKILL.md +2 -0
  39. package/content/skills/capture-feedback/SKILL.md +1 -1
  40. package/content/skills/collaborate/SKILL.md +2 -2
  41. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  42. package/content/skills/create-commit/SKILL.md +1 -1
  43. package/content/skills/create-gh-pr/SKILL.md +4 -1
  44. package/content/skills/create-pr/SKILL.md +2 -1
  45. package/content/skills/create-ticket/SKILL.md +3 -7
  46. package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
  47. package/content/skills/design-and-plan/SKILL.md +5 -9
  48. package/content/skills/implement-plan/SKILL.md +2 -2
  49. package/content/skills/index-prototypes/SKILL.md +1 -1
  50. package/content/skills/kb-add/SKILL.md +2 -0
  51. package/content/skills/kb-edit/SKILL.md +2 -0
  52. package/content/skills/kb-edit/kb-edit.mjs +24 -24
  53. package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
  54. package/content/skills/kb-retrieve-events/SKILL.md +19 -10
  55. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
  56. package/content/skills/kb-update-events/SKILL.md +9 -6
  57. package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
  58. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  59. package/content/skills/plan/SKILL.md +1 -1
  60. package/content/skills/refine-guidance/SKILL.md +97 -0
  61. package/content/skills/review-branch/SKILL.md +350 -1
  62. package/content/skills/revise-prose/revise-prose.mjs +85 -85
  63. package/content/skills/save-artifact/SKILL.md +1 -1
  64. package/content/skills/streamline-guidance/SKILL.md +10 -15
  65. package/content/skills/streamline-guidance/streamline-guidance.mjs +73 -73
  66. package/content/skills/summarize-change/SKILL.md +1 -1
  67. package/content/skills/testing-conventions/SKILL.md +7 -1
  68. package/content/skills/triage-feedback/SKILL.md +150 -0
  69. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  70. package/content/skills/triage-spike-findings/SKILL.md +5 -5
  71. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
  72. package/content/skills/update-project-guidance/SKILL.md +10 -10
  73. package/content/subagents/code-health-assessor.md +98 -0
  74. package/content/subagents/feedback-triage-challenger.md +81 -0
  75. package/content/subagents/lesson-clusterer.md +68 -0
  76. package/package.json +13 -13
  77. package/schemas/preferences.v1.json +22 -6
  78. package/schemas/work-types.v1.json +1 -1
  79. package/content/_partials/code-descriptions.md +0 -4
  80. package/content/_partials/code-style.md +0 -7
  81. package/content/_partials/live-repo-writes.md +0 -13
  82. package/content/_partials/reduced-object-relative.md +0 -28
  83. package/content/_partials/test-structure-audit-checklist.md +0 -7
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  85. package/content/skills/_partials/next-steps-after-review.md +0 -350
  86. package/content/skills/_partials/ticket-concision.md +0 -18
  87. package/content/skills/_partials/ticket-placement.md +0 -14
  88. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: triage-spike-findings
3
- description: Dispose of the findings that a spike or a usability assessment left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the labelled tickets under an umbrella and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
3
+ description: Dispose of the findings that a spike, a usability assessment, or a code-health assessment left without a ticket. Inventories every undisposed item, grades each one's confidence and value, has a subagent without session context challenge every grade, and then creates the labelled tickets under an umbrella and records every disposition on the triage ticket. Use when a findings artifact has proposals or ideas that the existing tickets have not absorbed.
4
4
  user-invocable: true
5
5
  ---
6
6
 
@@ -12,7 +12,7 @@ Dispose of every item that a findings artifact leaves undisposed: the proposals,
12
12
 
13
13
  ## Inputs
14
14
 
15
- - **The findings artifact**: A spike's findings or a `usability-findings` artifact, by local path or by artifact URL. Read a URL with the Artifact tool and save the content to `{ticket_dir}/triage/findings.md`, so that the challenger can read it from a path; on a harness without that tool, the input is a local path.
15
+ - **The findings artifact**: A spike's findings, a `usability-findings` artifact, or a `code-health-findings` artifact, by local path or by artifact URL. Read a URL with the Artifact tool and save the content to `{ticket_dir}/triage/findings.md`, so that the challenger can read it from a path; on a harness without that tool, the input is a local path.
16
16
  - **The triage ticket**: The ticket on which the dispositions are posted and under which the working files are kept, resolved per [ticket source resolution](../_data/ticket-source-resolution.md); when none is given, the session's ticket. The umbrella is created as a separate ticket, so the triage ticket may be the spike's own ticket.
17
17
 
18
18
  GitHub alone is supported, through `gh`. When the session-context manifest's `scm` is not `github`, stop at preflight and report that the skill does not support the platform.
@@ -47,7 +47,7 @@ Resolve `{ticket_dir}` per {skill:save-artifact}, and write every working file u
47
47
 
48
48
  Read the findings in full. List every item that the artifact leaves without a disposition, where a disposition is a ticket or a comment that the artifact itself names: a proposed ticket that was not filed, a grouping, a finding outside every grouping, and an idea that the filed tickets did not absorb. Verify each item's claim against the current code and against the open issues (`gh issue list --search`, `gh issue view`): The finding may describe a problem that a merge has since fixed, a decision that the repository records, or work that an open issue already covers.
49
49
 
50
- Write `inventory.md` as a table: the item's id (the artifact's own id when it has one), its title, where it appears in the artifact, and the verification outcome (holds, partly holds, or does not hold, with the evidence).
50
+ Write `inventory.md` as a table: the item's id (the artifact's own id when it has one), its title, where it appears in the artifact, the verification outcome (holds, partly holds, or does not hold, with the evidence), and, when the findings give the item an evidence key and the paths that it covers, that key and those paths, copied verbatim.
51
51
 
52
52
  ### 3. Recommend
53
53
 
@@ -69,11 +69,11 @@ Save the reply as `challenge.md`. Then take each item in turn: Defend the recomm
69
69
 
70
70
  Decide the blockers of every `ticket` item under the threshold in the ticketing preferences rulebook: An item is blocked by another ticket when there is some probability that the other ticket affects it and should be merged first, and a ticket whose design takes another ticket's outcome as an input is blocked by it. A blocker is another `ticket` item, by id, or an open issue in this repository outside the triage, by number; check each issue with `gh issue view {issue} --json state`, and omit a closed one, which does not block. Record every such dependency in `blockedBy`, never in `notes`.
71
71
 
72
- Write `dispositions.json` in the helper's record shape: `source` (the findings as given), `triageTicket`, `umbrella: null`, `items`, `challengeSummary` (what the challenge refuted or narrowed and what it did not), and `notes` (the lines of the comment's "Labels and follow-ups" section, empty when there are none). Each item has `id`, `title`, `disposition`, `confidence`, `value`, `reason`, `target` (the issue number of a `comment`, the target id of a `merge`, null otherwise), `ticket: null`, `blockedBy` on a `ticket` item that has blockers (item ids and issue numbers), and `challenge` with `argument`, `outcome` (`defended`, `modified`, or `abandoned`), and `note`. Run the helper's `validate`, which reports every schema and gate violation at once, a cycle among the blockers included, and fix the record until it passes.
72
+ Write `dispositions.json` in the helper's record shape: `source` (the findings as given), `triageTicket`, `umbrella: null`, `items`, `challengeSummary` (what the challenge refuted or narrowed and what it did not), and `notes` (the lines of the comment's "Labels and follow-ups" section, empty when there are none). Each item has `id`, `title`, `disposition`, `confidence`, `value`, `reason`, `target` (the issue number of a `comment`, the target id of a `merge`, null otherwise), `ticket: null`, `blockedBy` on a `ticket` item that has blockers (item ids and issue numbers), `evidence` with `key` and `paths` on an item whose inventory row has them (omitted otherwise), and `challenge` with `argument`, `outcome` (`defended`, `modified`, or `abandoned`), and `note`. When any item has `evidence`, write the output of `git rev-parse HEAD` into the record's `commit`. Run the helper's `validate`, which reports every schema and gate violation at once, a cycle among the blockers included, and fix the record until it passes.
73
73
 
74
74
  ### 5. Checkpoint: The dispositions
75
75
 
76
- Present the dispositions as a table (item, disposition, confidence, value, blocked by, reason, challenge outcome), in the order that `validate` reports as `order`, which places every blocker before the items that it blocks, and the challenge summary, and ask in the action-items block for approval. Revise the record until the developer approves it; re-run `validate` after each change.
76
+ Present the dispositions as a table (item, disposition, confidence, value, blocked by, reason, challenge outcome), in the order that `validate` reports as `order`, which places every blocker before the items that it blocks, and the challenge summary, and ask in the action-items block for approval. Revise the record until the developer approves it; re-run `validate` after each change. Once the developer approves, and when any item has `evidence`, set the record's `commit` again to the output of `git rev-parse HEAD`, so that it names the commit at which the dispositions were approved and a later run can tell whether an item's paths changed after the disposition, and run `validate` once more.
77
77
 
78
78
  <!-- include: ../_partials/action-items.md / -->
79
79