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
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: curate-feedback
|
|
3
|
+
description: Cull the open feedback events that no longer need attention. Clusters the events by the lesson that they teach, has subagents without session context read the current guidance and sort every event into covered, duplicate, obsolete, or kept, and then, once the developer approves or under --apply, marks the culled events addressed-by or obsolete, recording the run in a curation artifact. Use when the feedback pool has grown with lessons that guidance has since absorbed, or before a triage-feedback run.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Curate feedback
|
|
8
|
+
|
|
9
|
+
Cull the feedback events that no longer need attention, and do nothing else: This skill does not surface lessons, file tickets, or edit guidance. You inventory and cluster the open `feedback` events, pin every guidance repository at a commit, have one {subagent:feedback-coverage-judge} per group of clusters sort each event into a bin, and then, once the developer approves, mark the culled events. Two bundled helpers do the mechanical work: `lesson-clusters` inventories and clusters the events, and `curate-feedback` prepares the judges' assignments, checks their bins, and writes the record and the artifact.
|
|
10
|
+
|
|
11
|
+
**Announce at start:** "Using curate-feedback to cull the feedback events that no longer need attention."
|
|
12
|
+
|
|
13
|
+
<HARD-GATE>
|
|
14
|
+
Never edit a guidance artifact: a skill, a subagent, a rulebook, a partial, a guidance file, or a helper. This skill marks events and nothing else.
|
|
15
|
+
</HARD-GATE>
|
|
16
|
+
|
|
17
|
+
## Arguments
|
|
18
|
+
|
|
19
|
+
| Argument | Effect | Default |
|
|
20
|
+
| ------------------ | ----------------------------------------------------------------------- | ----------- |
|
|
21
|
+
| `--store <name>` | The event store: a registry name, `@default`, or `@feedback`. | `@feedback` |
|
|
22
|
+
| `--apply` | Apply the marks without the approval checkpoint, for an unattended run. | Off |
|
|
23
|
+
| `--group-size <n>` | The most events in one judge's assignment. | 60 |
|
|
24
|
+
| `--list` | Show the per-event listing at the checkpoint and in the report. | Off |
|
|
25
|
+
|
|
26
|
+
## Bins and marks
|
|
27
|
+
|
|
28
|
+
Each judge sorts each event into one bin, and step 7 marks it accordingly:
|
|
29
|
+
|
|
30
|
+
- `covered`: Guidance at its pinned commit states the lesson, in a sentence that the judge quotes and that `validate` finds in the file. The event is marked `addressed-by` a GitHub permalink to the file at that commit.
|
|
31
|
+
- `duplicate`: An already-addressed event teaches the same lesson. The event is marked `addressed-by` that event's references, other than triage artifacts and covered permalinks.
|
|
32
|
+
- `obsolete`: The target was removed without a successor, a later deliberate decision overruled the lesson, or it concerns a harness or model no longer in use. The event is tagged `obsolete`.
|
|
33
|
+
- `kept`: The event stays in the pool, and nothing is written.
|
|
34
|
+
|
|
35
|
+
An event that is marked or tagged drops out of every later inventory, so a rerun continues where a run stopped.
|
|
36
|
+
|
|
37
|
+
## Process
|
|
38
|
+
|
|
39
|
+
`<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:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
node {harness_home_dir}/skills/lesson-clusters/lesson-clusters.mjs {command} {flags}
|
|
43
|
+
node {harness_home_dir}/skills/curate-feedback/curate-feedback.mjs {command} {flags}
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### 1. Preflight
|
|
47
|
+
|
|
48
|
+
1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `artifact_base_dir`, `project_slug`, and `ticket_id`.
|
|
49
|
+
2. Fix the artifact's path. The directory is `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` when `ticket_id` is set, and `{artifact_base_dir}/projects/{project_slug}/feedback-curation/` otherwise; the `feedback-curation/` name is hardcoded. The filename is `{YYYYMMDD-HHMMSSZ}_{slug}_feedback-curation.md`, with the current UTC time and a slug per {skill:save-artifact}, or `curation` when nothing else suits.
|
|
50
|
+
3. Create the work directory `{timestamp}_work/` beside the artifact, where `{timestamp}` is the filename's prefix. Every working file goes there.
|
|
51
|
+
|
|
52
|
+
### 2. Pin the guidance
|
|
53
|
+
|
|
54
|
+
1. Run `codeassembly library list --json` and `codeassembly library list --global --json`, and collect the `dir` of every source in either listing. A listing that fails because its domain does not declare a source contributes nothing.
|
|
55
|
+
2. Run `curate-feedback pin --out {work}/pins.json`, with one `--source` for each collected directory and one for the current repository's root.
|
|
56
|
+
3. Report each `skipped` source with its reason: A judge cannot mark an event covered by guidance in a skipped source. Stop when `pins` is empty.
|
|
57
|
+
|
|
58
|
+
### 3. Cluster
|
|
59
|
+
|
|
60
|
+
<!-- include: ../_partials/cluster-feedback-events.md / -->
|
|
61
|
+
|
|
62
|
+
### 4. Assign
|
|
63
|
+
|
|
64
|
+
1. Run `curate-feedback references --store <store> --out {work}/references.json`.
|
|
65
|
+
2. Run `curate-feedback assign --inventory {work}/inventory.json --map {work}/map.json --references {work}/references.json --pins {work}/pins.json --out {work}/assignments`, adding `--group-size {n}` when it was given. Its `assignments` list gives each assignment's `path` and the `bins` path to which its judge writes.
|
|
66
|
+
|
|
67
|
+
### 5. Judge
|
|
68
|
+
|
|
69
|
+
1. Send one {tool:Task} call per assignment, all in one message, `subagent_type: feedback-coverage-judge`, each with this block and nothing else composed into it:
|
|
70
|
+
|
|
71
|
+
```dispatch
|
|
72
|
+
assignment: {assignment path}
|
|
73
|
+
output: {bins path}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
2. **A reply that lacks the `Phase: feedback-coverage` line is a judge stopped by its turn limit.** Resume that judge once, asking only for its bins file and its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned.
|
|
77
|
+
3. Run `curate-feedback validate --assignments {work}/assignments --out {work}/record.json`. On `invalid-bins`, resume the judge of each bins file that the `violations` name once, sending it that file's violations and asking it to correct its bins file. Run `validate` again, and on a second failure, stop and report the violations.
|
|
78
|
+
|
|
79
|
+
### 6. Checkpoint: The marks
|
|
80
|
+
|
|
81
|
+
Under `--apply`, skip this step.
|
|
82
|
+
|
|
83
|
+
Present the `counts` lines that `validate` reports, one per bin, then the marks from `record.json`: one line per `marks.addressedBy` group, with its reference and event count, and one line for `marks.obsolete`. Under `--list`, add a table of every event in `record.json` with its summary, bin, reference, reason, and quote. Ask in the action-items block for one approval of every mark.
|
|
84
|
+
|
|
85
|
+
The developer may move events between bins by id in the reply. For each move, edit the entry in the bins file that the event's `file` in `record.json` names. A move into `covered` needs the guidance file, and a move into `duplicate` needs the addressed event; ask for either when the reply does not name it. For a move into `covered`, read the file at its pin with `git -C {root} show {sha}:{path}` and copy the sentence that states the lesson into the entry's `quote`. Then run `validate` again, and present only the changed counts and marks before writing. The approval covers every mark that step 7 applies.
|
|
86
|
+
|
|
87
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
88
|
+
|
|
89
|
+
### 7. Apply
|
|
90
|
+
|
|
91
|
+
Nothing before this step writes to the store. For each group in `marks.addressedBy`, then for `marks.obsolete` when its `eventIds` is not empty, run {skill:kb-update-events} and write the result into the group's `result` in `record.json` as soon as it returns:
|
|
92
|
+
|
|
93
|
+
- **An `addressedBy` group**: `node {harness_home_dir}/skills/kb-update-events/kb-update-events.mjs --store <store> --add-addressed-by={the group's references, comma-joined} {event ids}`.
|
|
94
|
+
- **`obsolete`**: `node {harness_home_dir}/skills/kb-update-events/kb-update-events.mjs --store <store> --add-tag obsolete {event ids}`.
|
|
95
|
+
|
|
96
|
+
A result is `{ "ok": true, "failed": [] }` when every event's result has `ok: true`, and `{ "ok": false, "failed": [ids] }` otherwise. On a failed write or an `ok: false` result, stop applying, report which group failed, and continue to step 8, so that the artifact records what was applied.
|
|
97
|
+
|
|
98
|
+
### 8. Record and report
|
|
99
|
+
|
|
100
|
+
Run `curate-feedback render --file {work}/record.json --out {work}/artifact.md`. Save the rendered body, with frontmatter, at the artifact path fixed in step 1, per {skill:save-artifact}.
|
|
101
|
+
|
|
102
|
+
Report the `counts` lines, the marks applied, any failure, the skipped sources, and the artifact's path. Under `--list`, add the per-event table; otherwise leave the listing in the artifact. The report is the same under `--apply`.
|