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.
- package/.meta/changelog.json +291 -0
- package/CHANGELOG.md +82 -0
- package/README.md +20 -121
- package/content/_partials/README.md +19 -3
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/guidance-change-since-capture.md +9 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +1 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/cli-conventions.md +16 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +19 -2
- package/content/guidance/rulebooks/commit-conventions.md +3 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +6 -2
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +31 -4
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +69 -69
- package/content/scripts/manage-jira-ticket.mjs +73 -73
- package/content/scripts/select-lede-exemplars.mjs +53 -53
- package/content/scripts/validate-preferences.mjs +1 -1
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +24 -3
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +12 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/title-templates.md +3 -1
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/cluster-feedback-events.md +21 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/next-steps-after-plan.md +1 -1
- package/content/skills/_partials/option-format.md +2 -2
- package/content/skills/_partials/plan-template.md +4 -2
- package/content/skills/_partials/ticket-and-plan-completeness.md +1 -1
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -5
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +3 -1
- package/content/skills/capture-event/SKILL.md +2 -0
- package/content/skills/capture-event/capture-event.mjs +32 -32
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/collaborate/SKILL.md +2 -2
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +4 -1
- package/content/skills/create-pr/SKILL.md +2 -1
- package/content/skills/create-ticket/SKILL.md +3 -7
- package/content/skills/curate-feedback/SKILL.md +102 -0
- package/content/skills/curate-feedback/curate-feedback.mjs +211 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +94 -94
- package/content/skills/design-and-plan/SKILL.md +5 -9
- package/content/skills/implement-plan/SKILL.md +2 -2
- package/content/skills/index-prototypes/SKILL.md +1 -1
- package/content/skills/kb-add/SKILL.md +2 -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/SKILL.md +2 -0
- package/content/skills/kb-edit/kb-edit.mjs +59 -59
- package/content/skills/kb-retrieve/kb-retrieve.mjs +75 -75
- package/content/skills/kb-retrieve-events/SKILL.md +19 -10
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +75 -75
- package/content/skills/kb-update-events/SKILL.md +9 -6
- package/content/skills/kb-update-events/kb-update-events.mjs +86 -85
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +75 -75
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/review-branch/SKILL.md +350 -1
- package/content/skills/revise-prose/revise-prose.mjs +103 -103
- package/content/skills/save-artifact/SKILL.md +1 -1
- package/content/skills/streamline-guidance/SKILL.md +10 -15
- package/content/skills/streamline-guidance/streamline-guidance.mjs +74 -74
- package/content/skills/summarize-change/SKILL.md +1 -1
- package/content/skills/testing-conventions/SKILL.md +7 -1
- package/content/skills/triage-feedback/SKILL.md +135 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +6 -6
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +30 -28
- package/content/skills/update-project-guidance/SKILL.md +10 -10
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/feedback-coverage-judge.md +95 -0
- package/content/subagents/feedback-triage-challenger.md +86 -0
- package/content/subagents/lesson-clusterer.md +68 -0
- package/package.json +13 -13
- package/schemas/preferences.v1.json +22 -6
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
|
@@ -138,7 +138,7 @@ Both are optional, and each is recorded as an override beside the consolidated r
|
|
|
138
138
|
node {harness_home_dir}/scripts/describe-change.mjs consolidate-entries --entries-file "$entries_path"
|
|
139
139
|
```
|
|
140
140
|
|
|
141
|
-
[`consolidate-entries`](../_data/title-templates.md#consolidate-entries) states the output. Its `consolidated_record` is what the frontmatter's `scope`, `type`, and `breaking` record, each absent when it is `null` and `breaking` only when it is `true`. If the call fails, relay its error and leave all three out.
|
|
141
|
+
[`consolidate-entries`](../_data/title-templates.md#consolidate-entries) states the output. Its `consolidated_record` is what the frontmatter's `scope`, `type`, and `breaking` record, each absent when it is `null` and `breaking` only when it is `true`. If the call fails, relay its error and leave all three out. Report each entry in `defects` to the developer, naming the entry by its `text`, then continue; change nothing.
|
|
142
142
|
|
|
143
143
|
- **Re-resolve the effective record** by running `resolve-effective-record` again, on this consolidated record and the overrides resolved in step 2. The first run in step 2 used the commit-derived record, which this one supersedes, and the title and the labels downstream read the effective record. Report each `policy-violation` in `defects` and change nothing.
|
|
144
144
|
|
|
@@ -157,7 +157,13 @@ The smell is shared _setup with one variable_, not shared _shape with different
|
|
|
157
157
|
|
|
158
158
|
### Audit before save
|
|
159
159
|
|
|
160
|
-
|
|
160
|
+
Before saving a spec file, scan adjacent tests for shared-setup runs.
|
|
161
|
+
|
|
162
|
+
- **Parameterize** with `it.each` when the variation is small and the test body is structurally identical.
|
|
163
|
+
- **Extract a named helper** when the variation is bigger, when shared setup belongs behind a helper signature, or when assertion shapes differ per case.
|
|
164
|
+
- **Check the assertions, too.** When the rule is a count or predicate, specific-fixture-label assertions should not repeat per row. Assert specific data flow _once_ in a focused test; assert structurally for the rest.
|
|
165
|
+
|
|
166
|
+
Three or more `it` blocks with identical setup and a single varying input is the most common failure mode in interactive sessions. That material belongs behind a helper or a parameterized table, not in N copies of the same shape.
|
|
161
167
|
|
|
162
168
|
## Test organization
|
|
163
169
|
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: triage-feedback
|
|
3
|
+
description: Surface the few feedback lessons worth acting on. Clusters the open feedback events by the lesson that they teach, shows each cluster's recurrence, impact, and recency, has a subagent without session context challenge every priority, and then, once the developer approves, files tickets, defers clusters, or changes impact ratings, recording every disposition in a triage artifact. Use when captured feedback has accumulated and the developer wants to know which lessons deserve a guidance change.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Triage feedback
|
|
8
|
+
|
|
9
|
+
Surface the feedback lessons worth acting on. You inventory the open `feedback` events, have a {subagent:lesson-clusterer} group them by lesson, assign each cluster a priority, have a {subagent:feedback-triage-challenger} argue against every priority, and then, once the developer approves, apply the dispositions and record them. Two bundled helpers do the mechanical work: `lesson-clusters` inventories the events and computes each cluster's signals, and `triage-feedback` validates the triage record and renders the artifact.
|
|
10
|
+
|
|
11
|
+
**Announce at start:** "Using triage-feedback to surface the feedback lessons worth acting on."
|
|
12
|
+
|
|
13
|
+
<HARD-GATE>
|
|
14
|
+
Never edit a guidance artifact: a skill, a subagent, a rulebook, a partial, a guidance file, or a helper. A lesson reaches guidance through the ticket that this skill files, and a later change acts on it.
|
|
15
|
+
</HARD-GATE>
|
|
16
|
+
|
|
17
|
+
## Arguments
|
|
18
|
+
|
|
19
|
+
| Argument | Effect | Default |
|
|
20
|
+
| ------------------- | ---------------------------------------------------------------------------------------- | ----------- |
|
|
21
|
+
| `--limit <n>` | The number of clusters to surface. | 5 |
|
|
22
|
+
| `--store <name>` | The event store: a registry name, `@default`, or `@feedback`. | `@feedback` |
|
|
23
|
+
| `--defer-days <n>` | The days for which a deferred cluster stays out; overrides `triage_feedback.defer_days`. | 30 |
|
|
24
|
+
| `--resume <record>` | Resume a run that stopped during step 7, from its `record.json`. | |
|
|
25
|
+
|
|
26
|
+
With `--resume`, read the record, run `validate` on it, and go to step 7: `validate` reports as `pending` the clusters whose writes are not finished.
|
|
27
|
+
|
|
28
|
+
## Signals, priorities, and dispositions
|
|
29
|
+
|
|
30
|
+
The `clusters` command computes three signals for each cluster, and the skill shows them separately, never as one score: **recurrence** (the number of events), **impact** (the count of events at each rating, unrated included), and **recency** (the latest capture).
|
|
31
|
+
|
|
32
|
+
A priority states whether the lesson is worth acting on now: `high` (act now), `medium` (worth acting on, but arguable), or `low` (not yet). A borderline cluster takes the lower priority. Each priority has a one-sentence reason that cites the signals.
|
|
33
|
+
|
|
34
|
+
Each surfaced cluster takes one disposition:
|
|
35
|
+
|
|
36
|
+
- `ticket-existing`: a ticket to change the guidance artifact that should have taught the lesson.
|
|
37
|
+
- `ticket-new`: a ticket to create a guidance artifact for a lesson that no artifact covers.
|
|
38
|
+
- `ticket-undecided`: a ticket whose target {skill?:refine-guidance} places.
|
|
39
|
+
- `comment`: a comment on an open issue that already covers the lesson, so that the issue gains the cluster's evidence rather than a duplicate ticket.
|
|
40
|
+
- `impact`: a new impact rating on the cluster's events, for a cluster whose ratings misstate it.
|
|
41
|
+
- `defer`: set aside until the deferral interval passes or the cluster gains a new event.
|
|
42
|
+
|
|
43
|
+
A ticket disposition names the repository that owns its target:
|
|
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.
|
|
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
|
+
- A new or undecided target belongs to the current repository.
|
|
48
|
+
|
|
49
|
+
## Guidance history
|
|
50
|
+
|
|
51
|
+
<!-- include: ../../_partials/guidance-change-since-capture.md / -->
|
|
52
|
+
|
|
53
|
+
## Process
|
|
54
|
+
|
|
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:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
node {harness_home_dir}/skills/lesson-clusters/lesson-clusters.mjs {command} {flags}
|
|
59
|
+
node {harness_home_dir}/skills/triage-feedback/triage-feedback.mjs {command} {flags}
|
|
60
|
+
```
|
|
61
|
+
|
|
62
|
+
### 1. Preflight
|
|
63
|
+
|
|
64
|
+
1. Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `artifact_base_dir`, `project_slug`, and `ticket_id`.
|
|
65
|
+
2. Fix the artifact's path now, because a deferral references it. 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-triage/` otherwise; the `feedback-triage/` name is hardcoded. The filename is `{YYYYMMDD-HHMMSSZ}_{slug}_feedback-triage.md`, with the current UTC time and a slug per {skill:save-artifact}, or `triage` when nothing else suits.
|
|
66
|
+
3. Create the work directory `{timestamp}_work/` beside the artifact, where `{timestamp}` is the filename's prefix. Every working file goes there.
|
|
67
|
+
4. Run `gh auth status`. When it fails, report that tickets cannot be filed, and continue only when the developer accepts a run that defers or rates.
|
|
68
|
+
|
|
69
|
+
### 2. Cluster
|
|
70
|
+
|
|
71
|
+
<!-- include: ../_partials/cluster-feedback-events.md / -->
|
|
72
|
+
|
|
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.
|
|
74
|
+
|
|
75
|
+
### 3. Recommend
|
|
76
|
+
|
|
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.
|
|
78
|
+
|
|
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.
|
|
80
|
+
|
|
81
|
+
### 4. Challenge
|
|
82
|
+
|
|
83
|
+
Send one {tool:Task} call, `subagent_type: feedback-triage-challenger`, with this block and nothing else composed into it:
|
|
84
|
+
|
|
85
|
+
```dispatch
|
|
86
|
+
clusters: {work}/clusters.json
|
|
87
|
+
recommendations: {work}/recommendations.md
|
|
88
|
+
root: {repository root}
|
|
89
|
+
```
|
|
90
|
+
|
|
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`.
|
|
92
|
+
|
|
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.
|
|
94
|
+
|
|
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.
|
|
96
|
+
|
|
97
|
+
### 5. Checkpoint: The dispositions
|
|
98
|
+
|
|
99
|
+
Present the surfaced clusters as one table: cluster, lesson, recurrence, impact, latest capture, priority, reason, challenge outcome, and disposition. Below it, state the remainder in one line: "{clusters} more clusters, {events} events, remain in the pool; {excluded} deferred clusters are excluded." Ask in the action-items block for one approval of every disposition.
|
|
100
|
+
|
|
101
|
+
The developer may change a row in the reply. Record the change in the record, setting `decision: modified` and keeping the suggestion that it replaced in `originalSuggested`; re-run `validate`, and present only the changed rows again before writing. On approval, set `decision` on every surfaced cluster: `approved`, `modified`, or `declined`. This approval covers every ticket that step 7 files, so {skill:create-ticket} does not confirm again.
|
|
102
|
+
|
|
103
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
104
|
+
|
|
105
|
+
### 6. Compose
|
|
106
|
+
|
|
107
|
+
For each ticket disposition, compose the body in the ticket skeleton that {skill:create-ticket} step 2 states. The problem states the lesson; the context lists the event ids under the store name, with the signals; the proposed solution names the target, or states "Target: undecided; `refine-guidance` places it."; the acceptance criteria state the behavior that the lesson asks for.
|
|
108
|
+
|
|
109
|
+
For each `comment` disposition, compose a comment that opens with the line `Feedback triage: {cluster id}`, states the lesson, and lists the event ids under the store name, with the signals.
|
|
110
|
+
|
|
111
|
+
### 7. Write
|
|
112
|
+
|
|
113
|
+
Nothing before this step writes to a tracker or a store. Process each approved or modified cluster in surfacing order, and write its `result` into the record as soon as each write returns, so that a `--resume` run repeats only what is missing. On a failed write, stop and report which cluster failed.
|
|
114
|
+
|
|
115
|
+
- **A ticket disposition**: When `result.ticket` is not yet set, create the ticket with {skill:create-ticket}, adding `--repo {repo}` when the target's repository differs from the current one, and record its URL as `result.ticket`, with `marked: false`. Then mark the events with {skill:kb-update-events}: `--store <store> --add-addressed-by={ticket URL}` and the event ids. Set `marked: true`.
|
|
116
|
+
- **`comment`**: When `result.comment` is not yet set, read the issue's comments with `gh issue view {issue} --json comments`, and post the comment only when none already opens with its first line; record the comment's URL as `result.comment`, with `marked: false`. Then mark the events with {skill:kb-update-events}: `--store <store> --add-addressed-by={issue URL}` and the event ids. Set `marked: true`.
|
|
117
|
+
|
|
118
|
+
```bash
|
|
119
|
+
body_path="{absolute path of the composed comment}"
|
|
120
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
121
|
+
gh issue comment {issue} --body-file "$body_path"
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
- **`defer`**: Run {skill:kb-update-events} with `--store <store> --add-tag deferred` and the event ids, then with `--add-addressed-by={artifactPath}`. Set `result` to `{ "marked": true }`.
|
|
125
|
+
- **`impact`**: Run {skill:kb-update-events} with `--store <store> --set-impact {level}` and the event ids. Set `result` to `{ "marked": true }`.
|
|
126
|
+
|
|
127
|
+
Each {skill:kb-update-events} result reports each event; treat any event whose result has `ok: false` as a failed write. A declined cluster does not write anything.
|
|
128
|
+
|
|
129
|
+
### 8. Record and report
|
|
130
|
+
|
|
131
|
+
Run `triage-feedback validate` on the final record, then `triage-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}.
|
|
132
|
+
|
|
133
|
+
Report each filed ticket with its repository, each deferred or rated cluster, each declined cluster, the remainder line, and the artifact's path.
|
|
134
|
+
|
|
135
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|