codeassembly-guidance 0.3.0 → 0.5.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 +385 -272
- package/CHANGELOG.md +39 -0
- package/README.md +8 -40
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/codeassembly-content.yaml +2 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/rulebooks/shared-data-conventions.md +4 -2
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/skills/_data/artifact-conventions.md +9 -423
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/plan-template.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +1 -1
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/kb-add/kb-add.mjs +53 -53
- package/content/skills/kb-curate/kb-curate.mjs +64 -64
- package/content/skills/kb-edit/kb-edit.mjs +61 -61
- package/content/skills/kb-update-events/kb-update-events.mjs +19 -19
- package/content/skills/lesson-clusters/lesson-clusters.mjs +47 -47
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/refine-guidance/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +66 -66
- package/content/skills/save-artifact/SKILL.md +2 -2
- package/content/skills/streamline-guidance/streamline-guidance.mjs +30 -30
- package/content/skills/triage-feedback/SKILL.md +8 -23
- package/content/skills/triage-feedback/triage-feedback.mjs +7 -7
- package/content/skills/triage-spike-findings/SKILL.md +1 -1
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +10 -5
- package/content/subagents/plan-reviewer.md +8 -7
- package/package.json +6 -6
- package/schemas/preferences.v1.json +1 -1
- package/schemas/work-types.v1.json +1 -1
|
@@ -42,10 +42,14 @@ Each surfaced cluster takes one disposition:
|
|
|
42
42
|
|
|
43
43
|
A ticket disposition names the repository that owns its target:
|
|
44
44
|
|
|
45
|
-
- An artifact with a `<!-- codeassembly-` marker, or one in the CodeAssembly guidance library, belongs to the CodeAssembly repository, whose name the marker's provenance or the library's `Source:` line states.
|
|
45
|
+
- An artifact with a `<!-- codeassembly-` marker, or one in the CodeAssembly guidance library, belongs to the CodeAssembly guidance repository (`williamthorsen/codeassembly-guidance`), whose name the marker's provenance or the library's `Source:` line states.
|
|
46
46
|
- A project's `.agents/content` artifact belongs to that project's repository: Take it from the events' `repo` field, and confirm it with `gh repo view {repo} --json nameWithOwner`.
|
|
47
47
|
- A new or undecided target belongs to the current repository.
|
|
48
48
|
|
|
49
|
+
## Guidance history
|
|
50
|
+
|
|
51
|
+
<!-- include: ../../_partials/guidance-change-since-capture.md / -->
|
|
52
|
+
|
|
49
53
|
## Process
|
|
50
54
|
|
|
51
55
|
`<store>` below is the `--store` argument, `@feedback` when it is omitted. Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`, except when a step below says otherwise. Invoke the helpers as:
|
|
@@ -64,32 +68,13 @@ node {harness_home_dir}/skills/triage-feedback/triage-feedback.mjs {command} {fl
|
|
|
64
68
|
|
|
65
69
|
### 2. Cluster
|
|
66
70
|
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
1. Run `lesson-clusters inventory --store <store> --out {work}/inventory.json`. Report each `skipped` file, and stop when `pool` and `deferred` are both zero: Nothing awaits triage.
|
|
70
|
-
2. Run `lesson-clusters batch --inventory {work}/inventory.json --out {work}/batches`. Its `batches` list gives each batch's `path` and the `map` path to which its clusterer writes.
|
|
71
|
-
3. Send one {tool:Task} call per batch, all in one message, `subagent_type: lesson-clusterer`, each with this block and nothing else composed into it:
|
|
72
|
-
|
|
73
|
-
```dispatch
|
|
74
|
-
inventory: {batch path}
|
|
75
|
-
output: {batch map path}
|
|
76
|
-
```
|
|
77
|
-
|
|
78
|
-
4. When there is one batch, its map is the event map: Go to the last sub-step with `--map {work}/batches/map-01.json`.
|
|
79
|
-
5. Run `lesson-clusters lessons --batches {work}/batches --out {work}/lessons.json`. On `invalid-map`, resume the clusterer of each batch that the `violations` name once, sending it that batch's violations and asking it to correct its map; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. Run `lessons` again, and on a second failure, stop and report the violations.
|
|
80
|
-
6. Send one more {tool:Task} call, `subagent_type: lesson-clusterer`, for the merge pass:
|
|
81
|
-
|
|
82
|
-
```dispatch
|
|
83
|
-
inventory: {work}/lessons.json
|
|
84
|
-
output: {work}/merge.json
|
|
85
|
-
```
|
|
71
|
+
<!-- include: ../_partials/cluster-feedback-events.md / -->
|
|
86
72
|
|
|
87
|
-
7. Run `lesson-clusters combine --batches {work}/batches --lessons {work}/lessons.json --map {work}/merge.json --out {work}/map.json`. On `invalid-map`, resume the merge clusterer once with the violations, run `combine` again, and on a second failure, stop and report them.
|
|
88
73
|
8. Run `lesson-clusters clusters --inventory {work}/inventory.json --map {work}/map.json --limit {limit} --out {work}/clusters.json`, adding `--defer-days {n}` when it was given. `clusters.json` lists the candidates, the clusters that the triage ranks: each signal nominates its own top clusters, four times `--limit` of them, so that a single critical event or a recent spike is considered beside the clusters that recur most. `unranked` counts the clusters that no signal nominated.
|
|
89
74
|
|
|
90
75
|
### 3. Recommend
|
|
91
76
|
|
|
92
|
-
Read `clusters.json`.
|
|
77
|
+
Read `clusters.json`. For every candidate, search the guidance for the artifact that states or should state the lesson, decide its repository by the rules above, and check its history per [Guidance history](#guidance-history). Then assign every candidate a priority and a reason. A cluster whose latest capture predates a change to its guidance takes `low`, unless an event or other evidence shows the failure recurring under the changed guidance. Its reason names the change, and when the priority is above `low`, it also cites that evidence. Order the clusters by priority, recurrence, and latest capture; the first `--limit` clusters are surfaced. For each surfaced cluster, suggest a disposition, and for a ticket disposition, take the artifact found above as the target. Then search the target repository's open issues with `gh issue list --repo {repo} --search`; when one already covers the lesson, suggest `comment` on it instead.
|
|
93
78
|
|
|
94
79
|
Write `{work}/recommendations.md`: one line per cluster, with its id, priority, disposition, target, target repository, and a one-sentence reason. Write a line for every candidate, not only the surfaced ones, because the challenger argues against every priority. Nothing else goes in the file, because the challenger reads it and a sentence of your reasoning there would bias its judgment toward yours.
|
|
95
80
|
|
|
@@ -105,7 +90,7 @@ root: {repository root}
|
|
|
105
90
|
|
|
106
91
|
**A reply that lacks the `Phase: feedback-triage-challenge` line is a challenger stopped by its turn limit.** Resume it once, asking only for its report. When the resumed challenger still does not return a report, do not dispatch again: Record every challenge with the outcome `not-returned`.
|
|
107
92
|
|
|
108
|
-
Save the reply as `{work}/challenge.md`. Then take each cluster in turn: Defend the priority and the disposition when the argument fails on the evidence, modify them when the argument stands in part, and abandon the priority, by lowering it, when the argument stands. A changed priority can change which clusters are surfaced; re-apply the order and the limit.
|
|
93
|
+
Save the reply as `{work}/challenge.md`. Then take each cluster in turn: Defend the priority and the disposition when the argument fails on the evidence, modify them when the argument stands in part, and abandon the priority, by lowering it, when the argument stands. A defense answers the argument on the evidence that the argument names. A defense that rests on other grounds, such as guidance text that permits the failure when the argument names a change to the guidance, fails, and the priority is lowered. A changed priority can change which clusters are surfaced; re-apply the order and the limit.
|
|
109
94
|
|
|
110
95
|
Write `{work}/record.json` in the helper's record shape: `store` (the store name that the inventory reports), `limit`, `artifactPath` (the artifact's path with the home directory written as `~`), `clusters` (the candidates), `unranked` (as `clusters.json` reports it), and `remainder` (`clusters` and `events`, the count of clusters not surfaced, unranked ones included, and of their events, and `excluded`, the number of clusters in the `excluded` list of `clusters.json`). Each cluster carries the fields of `clusters.json` plus `priority`, `reason`, `challenge` (`argument`, `outcome`, `originalPriority` when the outcome changed the priority, and `note`), and `surfaced`. A surfaced cluster also carries `suggested` (`kind`, then `target` and `repo` for a ticket kind, with `target: null` for `ticket-undecided`, `issue` (the issue URL) for `comment`, or `level` for `impact`) and `result: null`. Run `triage-feedback validate --file {work}/record.json`, which reports every violation at once, and fix the record until it passes.
|
|
111
96
|
|