codeassembly-guidance 0.0.0 → 0.1.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 +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: capture-feedback
|
|
3
|
+
description: 'Capture feedback on agent behavior as a guidance-refinement candidate: apply the immediate fix when concrete, then record the generalized lesson. Use when correcting a misapplied rule or specifying a new desired behavior.'
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Capture feedback
|
|
8
|
+
|
|
9
|
+
Record feedback on the agent's behavior as evidence for a future guidance refinement, applying the immediate fix when there is something concrete to change. The user describes a correction or a desired behavior, the agent applies it when applicable, and the agent appends a generalized record that a later recall-driven pass reads to refine guidance.
|
|
10
|
+
|
|
11
|
+
The actual guidance refinement is **deferred**: This skill captures the candidate, it does not edit the skill, subagent, rulebook, general guidance, or helper. A later pass refines the guidance in bulk, recalling the accumulated `feedback` records together, so a single data point never over-fits a rule.
|
|
12
|
+
|
|
13
|
+
**Announce at start:** "Using capture-feedback to apply this and record it for guidance refinement."
|
|
14
|
+
|
|
15
|
+
## When to use
|
|
16
|
+
|
|
17
|
+
Invoke `{skill:capture-feedback}` whenever the user gives feedback that should change how the agent behaves, either:
|
|
18
|
+
|
|
19
|
+
- **Correcting a misapplied rule**: The agent broke guidance that already exists (for example, title-cased a heading when the sentence-case rule was in force).
|
|
20
|
+
- **Specifying a new desired behavior**: The user wants a behavior that the current guidance does not cover.
|
|
21
|
+
|
|
22
|
+
Both are captured the same way; the difference is recorded in the tags.
|
|
23
|
+
|
|
24
|
+
## Runtime dependencies
|
|
25
|
+
|
|
26
|
+
- **`node` ≥ 24**: The capture runs through `{skill:capture-event}`'s bundled helper, which inherits the Node version floor of `@williamthorsen/kb`.
|
|
27
|
+
- **A `kb.yaml` registry declaring `feedback_kb`**: `--store @feedback` resolves through `~/.agents/kb.yaml`, and only when that registry sets `feedback_kb` to a registered, writable KB. If it does not, apply the immediate fix, then report that the record went uncaptured and that `feedback_kb` must be set in `~/.agents/kb.yaml`. Never retry against another store.
|
|
28
|
+
|
|
29
|
+
## Process
|
|
30
|
+
|
|
31
|
+
### 1. Classify the feedback
|
|
32
|
+
|
|
33
|
+
Decide one question: **Did relevant guidance already exist?**
|
|
34
|
+
|
|
35
|
+
- **Yes: misapplied existing guidance.** A rule was in force and the agent missed it. This is a mistake plus its correction.
|
|
36
|
+
- **No: no such guidance.** The user is establishing a net-new expectation. The agent did not make a mistake; there is only a refinement to propose.
|
|
37
|
+
|
|
38
|
+
Assess this best-effort from the guidance that you can see. When you genuinely cannot tell, record the uncertainty in the body rather than forcing the call.
|
|
39
|
+
|
|
40
|
+
### 2. Apply the immediate fix
|
|
41
|
+
|
|
42
|
+
If the feedback names a concrete artifact (something the agent produced, such as code, a doc, a PR body, or a ticket), apply the fix:
|
|
43
|
+
|
|
44
|
+
- **Apply it directly, without asking for approval.** Invoking this skill and describing the fix is the authorization.
|
|
45
|
+
- **Confirm first only when the fix is genuinely ambiguous** (more than one reasonable reading of what to change) **or risky, large, or hard to reverse.** Then state the change that you intend to make and wait for a go-ahead before applying.
|
|
46
|
+
|
|
47
|
+
If the feedback is purely behavioral (a standing rule with nothing to fix right now), skip this step.
|
|
48
|
+
|
|
49
|
+
### 3. Capture the record
|
|
50
|
+
|
|
51
|
+
Invoke the `{skill:capture-event}` skill to append the record, composing its arguments and body as follows:
|
|
52
|
+
|
|
53
|
+
- `--store @feedback`: Always. The registry's `feedback_kb` names the KB read by the pass that refines guidance in this environment, whichever repository the guidance came from.
|
|
54
|
+
- `--tags feedback`: Always. Add `,mistake` when existing guidance was misapplied (step 1, "Yes").
|
|
55
|
+
- `--skill <slug>`: When the refinement target is a skill.
|
|
56
|
+
- `--impact <level>`: Optionally rate how much addressing this feedback would improve the agent's future behavior: `low`, `medium`, `high`, or `critical`. Omit it when you do not have a clear read; the rating is revisable later with `kb-update-events`.
|
|
57
|
+
- `--summary`: A one-line recall label, for example "Agent title-cased a heading; sentence case is the rule."
|
|
58
|
+
- **Body**: The generalized lesson, only to the extent needed to act on it later:
|
|
59
|
+
- The **error→correction pair** (misapplied-guidance mode) or the **desired behavior** (no-guidance mode), generalized, not the raw artifact or diff.
|
|
60
|
+
- A **best-effort candidate refinement target**: The guidance artifact and its type (skill, subagent, rulebook, general guidance, or helper), with the provenance that the artifact's file states: its `<!-- codeassembly-* -->` ownership marker or its `Source:` line. Use `--skill` for a skill target; name the artifact in the body for the other four. Write "candidate: undetermined" when you genuinely cannot place it.
|
|
61
|
+
- Any uncertainty about the classification from step 1.
|
|
62
|
+
|
|
63
|
+
### 4. Report
|
|
64
|
+
|
|
65
|
+
State what was fixed (or that the feedback was behavioral-only) and the captured record's id and path. If `~/.agents/kb.yaml` does not configure `feedback_kb`, say so in place of the id and path, and name the key to set.
|
|
66
|
+
|
|
67
|
+
If the user then says the record is inaccurate, correct it in place with `capture-event --amend <id>` rather than capturing a second record; amend rewrites the record in place. Capture a fresh record only when the correction is a genuinely distinct lesson.
|
|
68
|
+
|
|
69
|
+
## Completion
|
|
70
|
+
|
|
71
|
+
The immediate fix is applied (when applicable) and a `feedback`-tagged record is written, ready for a later refinement pass to recall by that tag.
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: capture-lede-decision
|
|
3
|
+
description: Record the author's rating of a merged pull request's lede into the lede-decision corpus. Invoke only when the author asks for it.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Capture a lede decision
|
|
8
|
+
|
|
9
|
+
Record how good the lede in the merged pull request is. A bundled helper does the mechanical work: It reads the lede that the agent published and the lede that merged from the ticket's own artifacts, fingerprints the doctrine that applied to the first, and writes one event record. You present what shipped and relay the author's rating.
|
|
10
|
+
|
|
11
|
+
Every lede decision belongs to one corpus, the `codeassembly` event store, whichever repository the pull request merged in. The helper targets it without being told, so a caller never chooses a destination.
|
|
12
|
+
|
|
13
|
+
**Announce at start:** "Using capture-lede-decision to record the lede decision for #{pr}."
|
|
14
|
+
|
|
15
|
+
## What the rating grades
|
|
16
|
+
|
|
17
|
+
The rating grades the lede in the merged pull request, whichever hand wrote it: the merged lede when the author rewrote it before merge, and the agent's lede when it was merged as written. It is one of five levels, lowest to highest:
|
|
18
|
+
|
|
19
|
+
`poor`, `adequate`, `good`, `strong`, `exemplary`
|
|
20
|
+
|
|
21
|
+
The middle of the scale is what the corpus most needs and most easily loses: a lede good enough that editing it is not worth the time, and not good enough that the author wants their imprimatur on it. Record such a lede at the level that it deserves rather than rounding it up.
|
|
22
|
+
|
|
23
|
+
The verdict, `accepted` or `revised`, is not asked. The helper derives it from whether the two ledes differ and records it beside the rating.
|
|
24
|
+
|
|
25
|
+
The merge commit's body records its change entries below the lede, as a `change-record` block or, in a merge published before that block existed, as one `Change:` trailer per entry. The helper removes every `change-record` block and then a trailing trailer block before comparing and recording. A trailer block qualifies only as a run at the end whose every line is a trailer, which leaves a body that ends in prose untouched.
|
|
26
|
+
|
|
27
|
+
## The corpus stores positive signals only
|
|
28
|
+
|
|
29
|
+
A record exists because the author looked at the lede and rated it. Declining to rate writes nothing. **The absence of a record means nothing, and in particular is not an endorsement**: A merge that nobody evaluated is indistinguishable from a merge on which this skill never ran. Never infer a rating, and never record one that the author did not give: A lede that was merged unchanged under time pressure is not a rated lede, and recording a rating not made by the author is the single failure that would make the corpus useless.
|
|
30
|
+
|
|
31
|
+
For the same reason, the corpus is outcome-selected: It contains only changes that someone chose to evaluate. It is the right population for reading what good looks like and what typically fails, and the wrong one for measuring whether guidance helps. A comparison must never draw its fixtures from it.
|
|
32
|
+
|
|
33
|
+
## Arguments
|
|
34
|
+
|
|
35
|
+
| Argument | Description | Required |
|
|
36
|
+
| -------------------- | ------------------------------------------------------------------------------------------------ | -------- |
|
|
37
|
+
| `--artifact-dir` | The ticket's artifact directory, containing the pull-request and merge artifacts. | Yes |
|
|
38
|
+
| `--pr` | The pull-request number. | Yes |
|
|
39
|
+
| `--merge-commit` | The merge commit's SHA. | Yes |
|
|
40
|
+
| `--inspect` | Resolve and report the episode without writing. Mutually exclusive with `--quality`. | Mode |
|
|
41
|
+
| `--quality` | The author's rating of the lede in the merged pull request. Mutually exclusive with `--inspect`. | Mode |
|
|
42
|
+
| `--store` | Names a corpus registered under some other name; `@default` and `@feedback` are refused. | No |
|
|
43
|
+
| `--type` | Work type. `--type feat!` is accepted as `--type feat --breaking`. | Identity |
|
|
44
|
+
| `--scope` | Package or surface scope. Omit it for a change that does not name a scope; `*` names none. | Identity |
|
|
45
|
+
| `--breaking` | Marks the change breaking. | Identity |
|
|
46
|
+
| `--ticket` | Ticket id. Falls back to the change summary's frontmatter. | No |
|
|
47
|
+
| `--merged-lede-file` | File containing the merged lede, for a pull request without a merge artifact. | No |
|
|
48
|
+
| `--agent-lede-file` | File containing the agent's lede, for a pull request without a pull-request artifact. | No |
|
|
49
|
+
| `--harness` | The agent platform (`claude`, `rovo`); install-injected. Keep as-is. | Injected |
|
|
50
|
+
|
|
51
|
+
Exactly one of `--inspect` and `--quality` must appear. The author's comment is read from stdin to EOF; an empty comment is allowed, and the helper then does not record a comment section.
|
|
52
|
+
|
|
53
|
+
The change's identity comes wholly from one source. If any of `--type`, `--scope`, and `--breaking` is passed, it comes from those flags alone, and `--type` is required. If none is, it comes from the change summary's frontmatter, whose override fields apply to `scope`, `type`, and `breaking` as [the effective record](../_data/change-record.md#the-effective-record) states. A scope of `*` from either source does not name a scope. `--ticket` falls back to the change summary on its own.
|
|
54
|
+
|
|
55
|
+
## Runtime dependencies
|
|
56
|
+
|
|
57
|
+
- **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
|
|
58
|
+
- **A `kb.yaml` registering the `codeassembly` store**: The corpus to which every lede decision is written. If the `kb.yaml` registry does not declare it, the skill says so and records nothing, rather than filing the decision somewhere else.
|
|
59
|
+
|
|
60
|
+
## Process
|
|
61
|
+
|
|
62
|
+
### 1. Resolve the inputs
|
|
63
|
+
|
|
64
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `artifact_base_dir`, `project_slug`, `ticket_id`, and `pr_url` from it. `--artifact-dir` is `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`, and `--pr` is the number that `pr_url` ends with.
|
|
65
|
+
|
|
66
|
+
The newest `*_merge.md` artifact in that directory supplies the rest: its `Merge commit:` line is `--merge-commit`, and its `PR:` line is `--pr` when the manifest stored none, which is what the default branch stores.
|
|
67
|
+
|
|
68
|
+
### 2. Inspect the episode
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
node {harness_home_dir}/skills/capture-lede-decision/capture-lede-decision.mjs \
|
|
72
|
+
--inspect \
|
|
73
|
+
--artifact-dir <ticket artifact directory> \
|
|
74
|
+
--pr <number> \
|
|
75
|
+
--merge-commit <sha> \
|
|
76
|
+
[--type <key> [--scope <name>] [--breaking]] [--ticket <id>]
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
The helper prints a JSON object to stdout: `ok: true` with `episode` and `store` on success, or `ok: false` with `error` and `message`. Inspecting writes nothing, so it can never block or alter a merge that already happened.
|
|
80
|
+
|
|
81
|
+
On `ok: false`, report the `message` on one line and stop. The merge has already succeeded; do not present this as a merge failure, and do not retry.
|
|
82
|
+
|
|
83
|
+
On `store.reachable: false`, report `store.message` on one line and stop here, before presenting anything. The skill cannot reach the corpus, so it cannot record a decision; asking for one would spend the author's attention on an answer that this skill would then discard.
|
|
84
|
+
|
|
85
|
+
### 3. Present what shipped and ask
|
|
86
|
+
|
|
87
|
+
Read `episode.differ`. When it is `true`, show the agent's lede and the merged lede; when it is `false`, show the single lede. Then ask for a rating of the lede in the merged pull request, adding a comment if the author wants to say what was wrong:
|
|
88
|
+
|
|
89
|
+
1. `poor`
|
|
90
|
+
2. `adequate`
|
|
91
|
+
3. `good`
|
|
92
|
+
4. `strong`
|
|
93
|
+
5. `exemplary`
|
|
94
|
+
6. Skip
|
|
95
|
+
|
|
96
|
+
Ask once. A skip is a complete answer, not a prompt to re-ask or to persuade: The corpus is better off one record smaller than storing a rating that the author did not make.
|
|
97
|
+
|
|
98
|
+
### 4. Record the decision
|
|
99
|
+
|
|
100
|
+
On a skip, write nothing and say nothing further.
|
|
101
|
+
|
|
102
|
+
On a rating, pipe the author's comment (empty when they gave none) to the helper:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
cat <<'EOF' | node {harness_home_dir}/skills/capture-lede-decision/capture-lede-decision.mjs \
|
|
106
|
+
--quality <poor|adequate|good|strong|exemplary> \
|
|
107
|
+
--harness {harness_id} \
|
|
108
|
+
--artifact-dir <ticket artifact directory> \
|
|
109
|
+
--pr <number> \
|
|
110
|
+
--merge-commit <sha> \
|
|
111
|
+
[--type <key> [--scope <name>] [--breaking]] [--ticket <id>]
|
|
112
|
+
<the author's comment, verbatim; may be empty and may span multiple lines>
|
|
113
|
+
EOF
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
Relay the comment verbatim. It is free text on purpose: Naming which doctrine rule the fix invoked is the refinement pass's job, and a rule list offered at capture time would presuppose which rules matter, which is the question that the corpus exists to answer.
|
|
117
|
+
|
|
118
|
+
Report the written `path` on success.
|
|
119
|
+
|
|
120
|
+
### Recording a pull request merged outside the merge flow
|
|
121
|
+
|
|
122
|
+
The merge flow did not write a merge artifact for such a pull request, so the caller supplies the merged lede. The helper reads a lede file whole and records it as the lede, applying none of the heading extraction that it uses on the artifact path: If the file contains the entire pull-request body, the helper records the entire body as the lede. Extract the `## What` section as the file is written:
|
|
123
|
+
|
|
124
|
+
```bash
|
|
125
|
+
scratch_dir=$(mktemp -d "${TMPDIR:-/tmp}/lede.XXXXXX")
|
|
126
|
+
lede_path="${scratch_dir:?scratch directory not created}/lede-pr<number>.md"
|
|
127
|
+
gh pr view <number> --json body --jq '.body' \
|
|
128
|
+
| awk '{ sub(/\r$/, "") }
|
|
129
|
+
tolower($0) ~ /^## what[[:space:]]*$/ { capturing = 1; next }
|
|
130
|
+
/^## / { capturing = 0 }
|
|
131
|
+
capturing' \
|
|
132
|
+
> "$lede_path"
|
|
133
|
+
echo "$lede_path"
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
Read the printed path and pass it to `--merged-lede-file` as literal text, because a shell variable does not outlive the invocation that set it: A later call naming `$lede_path` would find nothing. Continue from step 3; everything else resolves from the ticket's artifacts as usual.
|
|
137
|
+
|
|
138
|
+
## The record
|
|
139
|
+
|
|
140
|
+
One event per decision, in the corpus:
|
|
141
|
+
|
|
142
|
+
- **Tags**: `lede-decision`, `type:{work type}`, `breaking` for a change whose work type had the marker, the derived verdict, and `quality:{level}`. Recall the corpus as a group with `kb-retrieve-events --tag lede-decision`, by work type with `--tag type:feat`, by rating with `--tag quality:exemplary`, and the breaking changes alone with `--tag breaking`.
|
|
143
|
+
- **Frontmatter**: The rating; the work type and tier, and the scope when the change names one; `breaking: true` for a breaking change, and nothing for any other; the pull-request number, merge commit, and ticket; `doctrine-hash`, a digest of the `entry-drafter` body in force when the agent wrote; and `agents-version` when the home-provenance stamp supplies one.
|
|
144
|
+
- **Body**: `## Agent lede`, then `## Merged lede` whenever the two texts differ, then `## Comment` when one was given.
|
|
145
|
+
|
|
146
|
+
`doctrine-hash` groups records by doctrine generation. The drafter writes the lede and the entries both, so its body is what a draft was written under and a change to it opens a generation. Nothing is recorded at install time to make that work: The mapping from a digest back to the commit that introduced it stays recoverable by re-hashing the body's own history. A digest recorded under an earlier generation resolves against that generation's files the same way: one combining the drafter with the retired `lede-cutter.md`, and an older one fingerprinting the retired `skills/_data/lede-voice.md` alone.
|
|
147
|
+
|
|
148
|
+
## Handling failures
|
|
149
|
+
|
|
150
|
+
Handle the `error` code as follows:
|
|
151
|
+
|
|
152
|
+
- `no-artifact-dir`, `no-agent-lede`, `no-merged-lede`: The ticket's artifacts do not contain both ledes. Report and stop; supply `--agent-lede-file` or `--merged-lede-file` only when the text is genuinely in hand.
|
|
153
|
+
- `no-doctrine`: The installed subagent body covered by the digest is unreadable; the message names it. Report it as an install problem.
|
|
154
|
+
- `no-taxonomy`: The installed `work-types.json` is unreadable. Report it as an install problem; a `--type` value cannot resolve against a taxonomy that did not load.
|
|
155
|
+
- `unresolved-identity`: The work type or its tier could not be resolved, or `--scope` or `--breaking` was passed without `--type`. The message names which; pass `--type`, with `--scope` and `--breaking` as they apply to the change.
|
|
156
|
+
- `invalid-args`: Report the message and propose a corrected invocation.
|
|
157
|
+
- `store-not-registered`: The corpus is not registered in any `kb.yaml`. If it is registered under some other name, re-run with `--store <name>`.
|
|
158
|
+
- `readonly-store`: The corpus is registered readonly. Report and stop; the skill does not substitute another destination for one that the registry protects.
|
|
159
|
+
- `schema-validation`: Report the `errors`.
|
|
160
|
+
|
|
161
|
+
## Completion
|
|
162
|
+
|
|
163
|
+
Either one written record at the reported path, or nothing at all. The skill does not have a third outcome, and it never writes a record without the author's rating.
|