codeassembly-guidance 0.2.0 → 0.4.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 (98) hide show
  1. package/.meta/changelog.json +291 -0
  2. package/CHANGELOG.md +82 -0
  3. package/README.md +20 -121
  4. package/content/_partials/README.md +19 -3
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/guidance-change-since-capture.md +9 -0
  7. package/content/_partials/kb-standard-tags.md +7 -0
  8. package/content/codeassembly-content.yaml +8 -0
  9. package/content/collections/recommended.md +1 -1
  10. package/content/guidance/README.md +1 -1
  11. package/content/guidance/rulebooks/cli-conventions.md +16 -2
  12. package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
  13. package/content/guidance/rulebooks/commit-conventions.md +3 -2
  14. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
  15. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  16. package/content/guidance/shared/AGENTS.md +31 -4
  17. package/content/scripts/check-prose.mjs +38 -38
  18. package/content/scripts/describe-change.mjs +69 -69
  19. package/content/scripts/manage-jira-ticket.mjs +73 -73
  20. package/content/scripts/select-lede-exemplars.mjs +53 -53
  21. package/content/scripts/validate-preferences.mjs +1 -1
  22. package/content/skills/_data/action-items.md +2 -0
  23. package/content/skills/_data/artifact-conventions.md +24 -3
  24. package/content/skills/_data/complexity-classification.md +1 -1
  25. package/content/skills/_data/design-priorities.md +12 -1
  26. package/content/skills/_data/spike-conventions.md +21 -6
  27. package/content/skills/_data/title-templates.md +3 -1
  28. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  29. package/content/skills/_partials/cluster-feedback-events.md +21 -0
  30. package/content/skills/_partials/commit-title-rendering.md +1 -1
  31. package/content/skills/_partials/next-steps-after-plan.md +1 -1
  32. package/content/skills/_partials/option-format.md +2 -2
  33. package/content/skills/_partials/plan-template.md +4 -2
  34. package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
  35. package/content/skills/_partials/ticket-composition.md +40 -0
  36. package/content/skills/_partials/ticket-skeleton.md +15 -1
  37. package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
  38. package/content/skills/assess-code-health/SKILL.md +127 -0
  39. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  40. package/content/skills/assess-usability/SKILL.md +3 -1
  41. package/content/skills/capture-event/SKILL.md +2 -0
  42. package/content/skills/capture-event/capture-event.mjs +32 -32
  43. package/content/skills/capture-feedback/SKILL.md +1 -1
  44. package/content/skills/collaborate/SKILL.md +2 -2
  45. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  46. package/content/skills/create-commit/SKILL.md +1 -1
  47. package/content/skills/create-gh-pr/SKILL.md +4 -1
  48. package/content/skills/create-pr/SKILL.md +2 -1
  49. package/content/skills/create-ticket/SKILL.md +3 -7
  50. package/content/skills/curate-feedback/SKILL.md +102 -0
  51. package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
  52. package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
  53. package/content/skills/design-and-plan/SKILL.md +5 -9
  54. package/content/skills/implement-plan/SKILL.md +2 -2
  55. package/content/skills/index-prototypes/SKILL.md +1 -1
  56. package/content/skills/kb-add/SKILL.md +2 -0
  57. package/content/skills/kb-add/kb-add.mjs +53 -53
  58. package/content/skills/kb-curate/kb-curate.mjs +64 -64
  59. package/content/skills/kb-edit/SKILL.md +2 -0
  60. package/content/skills/kb-edit/kb-edit.mjs +59 -59
  61. package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
  62. package/content/skills/kb-retrieve-events/SKILL.md +19 -10
  63. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
  64. package/content/skills/kb-update-events/SKILL.md +9 -6
  65. package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
  66. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  67. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
  68. package/content/skills/plan/SKILL.md +1 -1
  69. package/content/skills/refine-guidance/SKILL.md +97 -0
  70. package/content/skills/review-branch/SKILL.md +350 -1
  71. package/content/skills/revise-prose/revise-prose.mjs +103 -103
  72. package/content/skills/save-artifact/SKILL.md +1 -1
  73. package/content/skills/streamline-guidance/SKILL.md +10 -15
  74. package/content/skills/streamline-guidance/streamline-guidance.mjs +74 -74
  75. package/content/skills/summarize-change/SKILL.md +1 -1
  76. package/content/skills/testing-conventions/SKILL.md +7 -1
  77. package/content/skills/triage-feedback/SKILL.md +135 -0
  78. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  79. package/content/skills/triage-spike-findings/SKILL.md +6 -6
  80. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
  81. package/content/skills/update-project-guidance/SKILL.md +10 -10
  82. package/content/subagents/code-health-assessor.md +98 -0
  83. package/content/subagents/feedback-coverage-judge.md +95 -0
  84. package/content/subagents/feedback-triage-challenger.md +86 -0
  85. package/content/subagents/lesson-clusterer.md +68 -0
  86. package/package.json +13 -13
  87. package/schemas/preferences.v1.json +22 -6
  88. package/schemas/work-types.v1.json +1 -1
  89. package/content/_partials/code-descriptions.md +0 -4
  90. package/content/_partials/code-style.md +0 -7
  91. package/content/_partials/live-repo-writes.md +0 -13
  92. package/content/_partials/reduced-object-relative.md +0 -28
  93. package/content/_partials/test-structure-audit-checklist.md +0 -7
  94. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  95. package/content/skills/_partials/next-steps-after-review.md +0 -350
  96. package/content/skills/_partials/ticket-concision.md +0 -18
  97. package/content/skills/_partials/ticket-placement.md +0 -14
  98. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: assess-code-health
3
+ description: Survey one package or subtree of a codebase for code and tests that would be written differently today, through five lenses, one read-only subagent per lens, and merge their evidence-checked proposals into a ranked findings artifact that a triage pass can dispose of. Use when asked to find refactoring opportunities, convention drift, duplication, extraction candidates, or tests below the current bar in an existing codebase.
4
+ user-invocable: true
5
+ supported-harnesses: [claude]
6
+ ---
7
+
8
+ # Assess code health
9
+
10
+ Find the code and tests in one unit of a codebase that would be written differently if they were written afresh today, and propose one change for each. Each lens is a {subagent:code-health-assessor} that reads the unit without seeing any other lens's report. You run the sensors, write the brief that every lens reads, dispatch the lenses, check every proposal's evidence against the tree, and merge the proposals into one findings artifact.
11
+
12
+ The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. Its one remote write is the [closing post](../_data/spike-conventions.md#closing-post) on the ticket, made on the developer's consent.
13
+
14
+ ## Inputs
15
+
16
+ - **The unit**: a package or a subtree, as the developer names it. When the developer does not name one, propose one from the hotspot ranking at the checkpoint. Never assess the whole repository by default.
17
+ - **The window**: the number of days of history that the hotspots read, 180 by default.
18
+ - **The ticket**, optional. Without one in session, {skill:save-artifact} saves the artifacts under the ticket ID that it generates.
19
+
20
+ Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`. Invoke the helper as:
21
+
22
+ ```bash
23
+ node {harness_home_dir}/skills/assess-code-health/assess-code-health.mjs {command} {flags}
24
+ ```
25
+
26
+ The helper's commands, flags, and output shapes are documented in the guidance package's `docs/assess-code-health-helper.md`.
27
+
28
+ ## Process
29
+
30
+ ### 1. Prepare
31
+
32
+ Resolve the ticket directory per {skill:save-artifact}, and create `{ticket_dir}/code-health/`. Read the declared stage from `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`.
33
+
34
+ Find the repository's own commands for lint, typecheck, and tests with coverage, in its manifest, its `AGENTS.md`, or its README. Run the tests with coverage once, with a reporter that writes an istanbul `json-summary` and a JUnit reporter, both into `{ticket_dir}/code-health/`. Run every command by the repository's own scripts, and never one that writes outside the working tree's ignored output or reaches a hosted service.
35
+
36
+ Find the repository's tracked build output: the paths that its guidance or configuration declares as generated, and the changelogs and release metadata that its release tooling writes, which `.gitattributes` does not already mark `linguist-generated`. Pass each as an `--exclude` glob. Release files otherwise lead the hotspot ranking, because every release rewrites them.
37
+
38
+ Then run `sense`:
39
+
40
+ ```bash
41
+ node {harness_home_dir}/skills/assess-code-health/assess-code-health.mjs sense --unit {unit} --window {days} \
42
+ --out {ticket_dir}/code-health/sense.json --check lint={lint command} --check typecheck={typecheck command} \
43
+ --coverage-summary {summary path} --junit {junit path} --exclude {glob}
44
+ ```
45
+
46
+ Omit `--coverage-summary` or `--junit` when the test command cannot write that report; the sensor is then recorded as not applicable. A sensor that fails is recorded with its reason and does not stop the run.
47
+
48
+ ### 2. Write the brief
49
+
50
+ Compose the brief with these sections:
51
+
52
+ 1. **Unit.** The unit, the window and its first commit date from the sense document, and the top ten hotspots.
53
+ 2. **Reference points.** The reuse-candidate directory and the library inventory. Take the directory from the implementation guidance spliced below when it names one. The inventory is the repository's declared dependencies plus any library that the guidance names.
54
+ 3. **Lenses.** Five, each with its name, its slug, its ID prefix, its subject, the rulebooks that it reads by path, and its proposal cap (10 by default):
55
+
56
+ | Lens | Slug | Prefix | Subject |
57
+ | ----------------------------------- | ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
58
+ | Convention conformance | `conventions` | `C` | What the linters miss, cited by rulebook path, section, and quoted sentence |
59
+ | Structure | `structure` | `S` | Smells with a metric attached, and coupling from the co-change pairs |
60
+ | Extraction | `extraction` | `X` | Code duplicated across packages, code that belongs in the reuse-candidate directory, and code equivalent to a library in the inventory |
61
+ | Error handling and input validation | `errors` | `E` | Statically evidenced patterns only; performance is out of scope |
62
+ | Tests | `tests` | `T` | Coverage intersected with hotspots, duration outliers, duplicated setup, and tests below the bar of the testing conventions |
63
+
64
+ List the deployed rulebooks and guidance skills under `{harness_home_dir}/skills/`, and the guidance spliced below, and assign each to the lenses whose subject it governs: the testing conventions to tests, layout and language preferences to conventions and extraction, and every code rulebook to conventions. Name each by its absolute path.
65
+
66
+ 4. **Exclusions.** Paths out of scope, such as generated code, fixtures, and vendored code.
67
+ 5. **Settled.** The decisions above, stated as final, so that a lens does not re-decide them, and the declared stage.
68
+
69
+ ### 3. Checkpoint
70
+
71
+ Save the brief with {skill:save-artifact} as a ticket-level `code-health-brief` artifact, and show it to the developer. Ask in one action-items block for approval of the brief, the unit, and the caps. Do not dispatch any lens before approval.
72
+
73
+ <!-- include: ../_partials/action-items.md / -->
74
+
75
+ ### 4. Dispatch the lenses
76
+
77
+ Confirm that `git status --porcelain` prints nothing before the first dispatch; when it prints anything, ask the developer to commit or set the changes aside, because the check after each lens cannot tell their changes from a lens's.
78
+
79
+ Create `{ticket_dir}/code-health/{lens slug}/` for each lens, and dispatch all five in one message, one {tool:Task} call each, `subagent_type: code-health-assessor`, with this block and nothing else composed into it:
80
+
81
+ ```dispatch
82
+ brief: {path to the saved brief}
83
+ lens: {lens name}
84
+ sense: {ticket_dir}/code-health/sense.json
85
+ output: {ticket_dir}/code-health/{lens slug}/
86
+ ```
87
+
88
+ Never pass one lens's report, or anything learned from it, to another lens: Each lens's value is its independent view, and the synthesis removes the duplicates.
89
+
90
+ **A reply that lacks the `Phase: code-health-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.
91
+
92
+ As each lens returns:
93
+
94
+ 1. Run `git status --porcelain`. When it prints anything, stop the run and report the changed paths and the lens that returned last.
95
+ 2. Confirm that the lens saved `{ticket_dir}/code-health/{lens slug}/report.md` and `proposals.json`. When either is missing, save it from the reply: the report, or the report's JSON block.
96
+ 3. Run `check-evidence --proposals {that file} --sense {ticket_dir}/code-health/sense.json`. Drop every proposal that it lists under `failed`, and record each with its reason under residual unknowns. When the block fails the schema as a whole, record the lens's proposals as unchecked and drop them all.
97
+
98
+ ### 5. Synthesize
99
+
100
+ Merge the passed proposals of every lens into one list, and write it to `{ticket_dir}/code-health/proposals.json`:
101
+
102
+ - **Merge** proposals that share a key: Keep the first source ID as the merged entry's `id`, which the schema limits to one, and list every source ID with the proposal in the findings document. Keep the union of paths and evidence, the strongest strength (`sensor`, then `rule`, then `reading`), the largest size, and the largest reach.
103
+ - **Tracked.** Run `check-tracked --proposals {ticket_dir}/code-health/proposals.json` with one `--prior` for each `*_dispositions.md` under `{artifact_base_dir}/projects/{project_slug}/tickets/`. Move every proposal that it lists under `tracked` out of the ranking, into a **Tracked** section with its source and reason. When `tracker.checked` is false, record its reason under residual unknowns.
104
+ - **Rank** the rest by reach, then by the best hotspot rank among the proposal's paths (a proposal without a ranked path sorts last), then by ID.
105
+
106
+ Write the findings document:
107
+
108
+ - **Ranked proposals.** Each with its IDs, title, key, paths, change, strength, size, reach, and evidence. State the key and the paths verbatim, so that `triage-spike-findings` copies them into its record.
109
+ - **Proposed groupings.** Proposals that one change would fix, grouped, each group with a one-line title and its proposal IDs. Do not search the tracker or file anything.
110
+ - **Tracked.** The proposals that a prior disposition or an issue already covers.
111
+ - **Residual unknowns.** Every failed or inapplicable sensor, every dropped proposal with its reason, an unchecked tracker, every lens recorded as not reported, and the sample that each lens read.
112
+ - **Method.** One paragraph: the unit, the window, the sensors and their versions, and the lenses.
113
+ - **Lens reports.** Each report, appended unedited.
114
+
115
+ Write every evidence path relative to the repository root.
116
+
117
+ ### 6. Save
118
+
119
+ Save the document with {skill:save-artifact} as a ticket-level `code-health-findings` artifact.
120
+
121
+ ### 7. Report
122
+
123
+ Give the developer the findings artifact's path and one line of counts: proposals ranked, tracked, and dropped. Name `triage-spike-findings` as the next step, with the findings artifact's path as its input.
124
+
125
+ In the same response's action-items block, offer the closing post on the ticket, whose contents, consent, and duplicate check are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts and the top ranked proposals, and its groupings are the proposed groupings of step 5.
126
+
127
+ <!-- guidance-hook: implementation-preferences -->