codeassembly-guidance 0.2.0 → 0.3.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 +227 -0
- package/CHANGELOG.md +59 -0
- package/README.md +37 -121
- package/content/_partials/README.md +19 -3
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/codeassembly-content.yaml +6 -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/validate-preferences.mjs +1 -1
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +18 -2
- 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/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-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/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-edit/SKILL.md +2 -0
- package/content/skills/kb-edit/kb-edit.mjs +24 -24
- 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/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 +85 -85
- 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 +73 -73
- 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 +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +5 -5
- 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-triage-challenger.md +81 -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
|
@@ -1,350 +0,0 @@
|
|
|
1
|
-
## Next-steps options
|
|
2
|
-
|
|
3
|
-
The next-steps block has four independent sub-blocks. Each is shown only when its condition is met. If every condition is unmet, the next-steps block does not appear. Whatever combination of sub-blocks is shown, always wrap the output in a `Next steps:` header. When two or more sub-blocks appear, label each with its `A` identifier as a bold prefix (`**A1: Deviations from ticket**`, and so on) and keep each sub-block's own 1-based numbering, so the user answers `A1: 1, A2: 2`; a lone sub-block does not take an identifier.
|
|
4
|
-
|
|
5
|
-
Use `~/`-relative paths when possible and absolute paths otherwise. Every line subordinate to an option (invocation guidance as much as a pro or con) is a nested list item, never a whitespace-indented continuation; see [option format](#option-format).
|
|
6
|
-
|
|
7
|
-
**Naming a skill in the render.** Name a skill in the rendered option only when the user must carry the invocation across a session boundary: clearing context, handing off to another session, or waiting for someone else to act. When the agent runs the skill in the current session, the skill name appears in the sub-block's Options table and the rendered line is a bare action. This limits each rendered line to the step that the user performs.
|
|
8
|
-
|
|
9
|
-
**Reviewer and author roles.** A review reports findings; the author disposes of them. The options below send the reviewer's output to the author or record what the review found; they never ask the reviewer to re-design, re-plan, or coordinate a workflow, none of which is the reviewer's job.
|
|
10
|
-
|
|
11
|
-
### Proposed-edit preview
|
|
12
|
-
|
|
13
|
-
Three of the sub-blocks below offer options that rewrite an artifact, one each: the Deviations sub-block rewrites the ticket's acceptance criteria, the source-divergence sub-block rewrites the PR description, and the Findings sub-block rewrites the source. The user consents to that rewrite by picking a number, so every such option renders a preview of the edit that it would make. The reviewer judges which criteria are genuinely in conflict with the implementation and which findings name a change that it can carry out; the preview makes those judgments reviewable instead of silent.
|
|
14
|
-
|
|
15
|
-
**Placement.** The preview renders above the numbered options, inside its sub-block, under a `Proposed edit to the {target}:` label naming what it would change; the source target's label is plural, `Proposed edits to the source:`, because it covers every open finding. Option lines stay bare actions: The preview is never a pro, a con, or a line nested beneath an option. An option that mutates nothing, such as "Leave as-is", does not render a preview.
|
|
16
|
-
|
|
17
|
-
Ticket and PR-description deltas render as a flat list, one line per change. Source entries render as blocks instead, each led by its bolded finding ID.
|
|
18
|
-
|
|
19
|
-
**Notation.** The preview is a delta. It never restates the ticket, the PR description, or a finding's Recommendation, which would duplicate the artifact in the terminal, and it contains one entry per change:
|
|
20
|
-
|
|
21
|
-
- **Ticket targets** derive their delta from the in-conflict criteria rows of `## Specification compliance`'s ticket subsection, and from nothing else. Unplanned work is never a source: Implementation that goes beyond the criteria is not a deviation, so it does not yield a line. Because a ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when it was written, this menu does not offer an edit that changes them; a divergence between one of them and the implementation is reported in the PR description instead.
|
|
22
|
-
- `Reword: {old} → {new}` for a criterion whose direction the implementation deliberately contradicts
|
|
23
|
-
- `Drop: {criterion}` for a criterion that the implementation deliberately abandoned, never for one that it has not yet reached
|
|
24
|
-
- **PR-description targets** render the concrete claim changes, each keyed to the divergent `D{n}` row from which it came: `D2: {claim as written} → {claim as built}`.
|
|
25
|
-
- **Source targets** derive their delta from the open findings, one entry per finding, keyed to its ID. An entry states two things: the surface that the change touches (source, test, comment, docs, config) and the substance of the edit. Its form follows the edit's own granularity rather than a fixed notation, so a literal single-site edit is a `{old} → {new}` clause, many sites sharing one edit are a table captioned with what is invariant across its rows, and a structural edit is a prose clause naming the shape of the resulting diff. A code snippet is one rendering among these, never the required form.
|
|
26
|
-
- When an entry covers several sites and deliberately leaves one of them alone, it names that site with the reason. The entry states its own boundary rather than leaving the reader to infer it from silence.
|
|
27
|
-
|
|
28
|
-
Every finding has one of the two shapes that the [Proposed-change gate](../review-criteria/SKILL.md#proposed-change-gate) defines, and a source entry renders which one it has: a single named change, or a choice among named alternatives that the author decides. The second is tagged as the author's choice, and its alternatives are named rather than resolved.
|
|
29
|
-
|
|
30
|
-
Do not render an exclusions line. A criterion genuinely arguable as in conflict belongs in the delta, where the user can strike it. Listing what was left out adds noise and hides the proposal that it was meant to qualify.
|
|
31
|
-
|
|
32
|
-
**Open findings.** When a ticket or PR-description delta line would settle or obviate an open finding, follow it with a sibling `⚠️` list item naming that finding, so that the user can see that accepting the edit pre-empts the finding's disposition. Those preview lists stay flat; nothing nests beneath a delta line.
|
|
33
|
-
|
|
34
|
-
**The preview is the contract.** The edit executed is the edit previewed. When carrying it out reveals a change that the preview did not contain, stop and re-confirm with the new line shown; never widen the edit under consent already given.
|
|
35
|
-
|
|
36
|
-
**Empty delta.** When the judgment drops every line, the Deviations sub-block has nothing to propose and does not render at all; see its [trigger](#deviations-sub-block). When a source divergence proposes a PR-description edit, that delta is never empty, because a divergence that the implementation resolves in the ticket's favor always leaves a claim to reconcile.
|
|
37
|
-
|
|
38
|
-
### Deviations sub-block
|
|
39
|
-
|
|
40
|
-
Shown when at least one criterion in the ticket subsection of `## Specification compliance` is in conflict with the implementation, equivalently when the criteria delta contains at least one line. Compute the delta first: When it is empty, do not render the sub-block.
|
|
41
|
-
|
|
42
|
-
A criterion from another spec source never fires this sub-block, whose only edit rewrites the ticket. Every ticket edit offered by a review is this sub-block's, and a PR description at odds with the implementation is the [source divergence sub-block](#source-divergence-sub-block)'s.
|
|
43
|
-
|
|
44
|
-
A criterion that is merely unbuilt does not contribute a line. The work is unfinished, not redirected, and a contract is not revised to match a moving target. Implementation that exceeds the criteria contributes none either.
|
|
45
|
-
|
|
46
|
-
#### Options
|
|
47
|
-
|
|
48
|
-
| # | Emoji | Option | Description |
|
|
49
|
-
| --- | ----- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
-
| 1 | 📝 | Update the acceptance criteria | Run `align-ticket-with-implementation`, which revises acceptance criteria alone, bound to the previewed delta, and writes the ticket of record when one resolves |
|
|
51
|
-
| 2 | ⏭️ | Leave as-is | Accept the deviation without updating the ticket |
|
|
52
|
-
|
|
53
|
-
#### Output format
|
|
54
|
-
|
|
55
|
-
Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker. Option 1 renders the criteria delta above the list per [proposed-edit preview](#proposed-edit-preview). Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific deviation presents a tradeoff that survives the option-format tests (e.g., "the abandoned criterion was load-bearing for downstream tests"). Generic restatements ("ships faster," "ticket drifts from reality") are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
|
|
56
|
-
|
|
57
|
-
**Name the artifact that the edit writes.** Option 1's rendered line ends with its target: `on {ticket_ref}` when a ticket of record resolves, whichever artifact supplied the spec source, and `in the local ticket snapshot` when none does. A ticket of record is the manifest's `ticket_url`, or `ticket_id` with `scm`; when auto-resolve passed over a remote candidate on recency, it already has one.
|
|
58
|
-
|
|
59
|
-
**Offer the local-only form when the snapshot may be the contract.** When the review measured against the local snapshot while a remote candidate existed, nest one invocation line under option 1; omit it otherwise:
|
|
60
|
-
|
|
61
|
-
```
|
|
62
|
-
1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
|
|
63
|
-
- or `1 local`: update the local snapshot alone, leaving {ticket_ref} as it stands
|
|
64
|
-
2. ⏭️ ■□□ Leave as-is
|
|
65
|
-
```
|
|
66
|
-
|
|
67
|
-
For a selection qualified `local`, run the delegate with `--write-target=local`.
|
|
68
|
-
|
|
69
|
-
Example (rendered for the recommendation case):
|
|
70
|
-
|
|
71
|
-
```
|
|
72
|
-
Next steps:
|
|
73
|
-
|
|
74
|
-
Deviations from ticket:
|
|
75
|
-
|
|
76
|
-
Proposed edit to the acceptance criteria:
|
|
77
|
-
- Reword: "Warns on an unknown directive" → "Fails on an unknown directive"
|
|
78
|
-
- ⚠️ W2 asks whether an unknown directive should fail the run at all; accepting this reword settles it as the contract
|
|
79
|
-
- Drop: A `--strict` flag gates the new validation
|
|
80
|
-
|
|
81
|
-
1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
|
|
82
|
-
2. ⏭️ ■□□ Leave as-is
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
When the recommendation rules do not indicate a preference, omit markers from both options per the gradient's pure-taste-call form.
|
|
86
|
-
|
|
87
|
-
#### Recommendation rules
|
|
88
|
-
|
|
89
|
-
1. **Recommend "Update the acceptance criteria"**: The implementation's direction is deliberate and sound, so the criteria as written would lead a later reader to judge correct code wrong.
|
|
90
|
-
2. **Recommend "Leave as-is"**: The review raised a finding on the conflicting behavior. The code is in question, and revising the contract to match it would hide the finding.
|
|
91
|
-
3. **No recommendation** (omit markers from both options): The reviewer cannot tell whether the criteria or the implementation is the wrong one. The user decides.
|
|
92
|
-
|
|
93
|
-
#### Marker strengths
|
|
94
|
-
|
|
95
|
-
For rules 1 and 2, the recommended option's marker follows how cleanly the rule's test is met: ■■■ when the evidence is unambiguous (the direction is plainly deliberate and sound for rule 1, or the finding plainly stands for rule 2), and ■■□ when the reading is defensible but arguable. The other option takes ■□□. Under rule 3, both options go unmarked.
|
|
96
|
-
|
|
97
|
-
### Source divergence sub-block
|
|
98
|
-
|
|
99
|
-
Shown when the consistency section of the review reports a `partial` or `severe` verdict, and the divergence leaves a PR-description claim to reconcile. The consistency section renders only when two spec sources are present (ticket and PR description), so this sub-block appears in PR reviews. The case (which spec source the implementation matches) is drawn from the consistency-section table; see `review-branch/SKILL.md` § Specification consistency.
|
|
100
|
-
|
|
101
|
-
This sub-block edits the PR description alone. Because a ticket delta derives from in-conflict criteria rows, which are the [Deviations sub-block](#deviations-sub-block)'s trigger, a ticket edit offered here would duplicate that sub-block's preview and menu for one decision. Case 3 (the ticket is the stale source) therefore renders nothing of its own: When its divergence rests on a criterion, Deviations proposes the edit, and when it rests on a narrative section, the ticket's authoring-time record stands and nothing is proposed.
|
|
102
|
-
|
|
103
|
-
#### Options
|
|
104
|
-
|
|
105
|
-
The options are:
|
|
106
|
-
|
|
107
|
-
| Emoji | Option | Action |
|
|
108
|
-
| ----- | --------------------- | --------------------------------------------------- |
|
|
109
|
-
| 📝 | Update PR description | Edit the PR description to match the implementation |
|
|
110
|
-
| ⏭️ | Leave as-is | Accept the divergence |
|
|
111
|
-
|
|
112
|
-
Every case that renders offers both, so the pair is fixed; what varies by case is which marker each takes.
|
|
113
|
-
|
|
114
|
-
#### Output format
|
|
115
|
-
|
|
116
|
-
Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker per case. Option 1 renders its PR-description delta above the list, per [proposed-edit preview](#proposed-edit-preview); "Leave as-is" has none. Pros and cons are omitted by default; add a `➕` or `➖` line only when the specific divergence presents a tradeoff that survives the option-format tests (e.g., "the diverging AC was load-bearing for adjacent work that has already shipped"). Generic restatements are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
|
|
117
|
-
|
|
118
|
-
Case 2 (implementation matches ticket; PR description is the stale source):
|
|
119
|
-
|
|
120
|
-
```
|
|
121
|
-
Source divergence:
|
|
122
|
-
|
|
123
|
-
Proposed edit to the PR description:
|
|
124
|
-
- D2: "Retries use a fixed 200ms delay" → "Retries use exponential backoff from 200ms"
|
|
125
|
-
|
|
126
|
-
1. 📝 ■■□ Update PR description
|
|
127
|
-
2. ⏭️ ■□□ Leave as-is
|
|
128
|
-
```
|
|
129
|
-
|
|
130
|
-
Case 3 (implementation matches PR description; ticket is the stale source) renders nothing; see [the sub-block's own scope](#source-divergence-sub-block).
|
|
131
|
-
|
|
132
|
-
Case 4 (implementation matches neither source, severe) renders the same pair as case 2, marker-free: The reviewer cannot tell whether the code or the specs are the wrong one, so it recommends neither. The "code is wrong" path is not offered here: The review's findings already report a divergence when the code is at fault, and disposing of those findings is the author's job (see the Findings sub-block).
|
|
133
|
-
|
|
134
|
-
Source-divergence options preserve conversation context, and the preview that each renders binds the reconciliation that follows, per [proposed-edit preview](#proposed-edit-preview).
|
|
135
|
-
|
|
136
|
-
#### Recommendation rules
|
|
137
|
-
|
|
138
|
-
In the typical flow, the ticket is written first and rarely revised, while the PR description describes the implementation as built. When the two diverge and the implementation matches one of them, the unmatched source is the stale one; update it to match reality. When the implementation matches neither (severe), the reviewer cannot attribute the fault, so the menu offers only ratification of the PR description and leaves the code-is-wrong path to the findings.
|
|
139
|
-
|
|
140
|
-
Determine the case from the implementation column of the consistency-section table:
|
|
141
|
-
|
|
142
|
-
| Implementation column shows | Verdict | Case | Recommended option |
|
|
143
|
-
| --------------------------------------------- | ------------ | ---- | ---------------------- |
|
|
144
|
-
| `🟢 ticket, 🟠/🔴 PR` on every divergent row | 🟠 `partial` | 2 | Update PR description |
|
|
145
|
-
| `🟠/🔴 ticket, 🟢 PR` on every divergent row | 🟠 `partial` | 3 | None (does not render) |
|
|
146
|
-
| `🟠/🔴 ticket, 🟠/🔴 PR` on any divergent row | 🔴 `severe` | 4 | None (marker-free) |
|
|
147
|
-
|
|
148
|
-
#### Marker strengths
|
|
149
|
-
|
|
150
|
-
For case 2, the recommended option's marker follows how cleanly the case's own test is met: ■■■ when the divergence is unambiguous and the PR description is plainly the stale source, ■■□ when which source leads is arguable. The other option takes ■□□. In case 4, both options go unmarked.
|
|
151
|
-
|
|
152
|
-
### Findings sub-block
|
|
153
|
-
|
|
154
|
-
Shown when the review has at least one finding.
|
|
155
|
-
|
|
156
|
-
The trigger does not include a tier condition; do not reintroduce one. Every finding emitted by a review has already cleared the [Proposed-change gate](../_data/artifact-conventions.md#proposed-change-gate), which requires it to name a change on which the author can act; anything without an envisioned change was dropped before it was written to the artifact. Severity orders how findings rank and what blocks merge. It never decides whether they are shown, or whether the user is offered a way to act on them.
|
|
157
|
-
|
|
158
|
-
Stating the trigger as a list of tiers is the failure that this rule replaces: An enumeration goes stale the next time the finding scheme changes, and silently withdraws the menu from whichever tier it omits.
|
|
159
|
-
|
|
160
|
-
Legacy (`-L`) findings trigger the sub-block on the same terms, with the full option pool. Do not trim the author hand-offs for a legacy-only review: That would leave implementing-in-place as the only route and forfeit the adversarial second look, which pre-existing code needs at least as much as authored code, since a legacy fix is not constrained by any ticket criterion or supported by any design discussion. The recommendation rules handle legacy findings without a carve-out: A legacy fix naming a single change satisfies rule 2 like any other, and one leaving its choice to the author falls through to a ticket or a hand-off.
|
|
161
|
-
|
|
162
|
-
The option set depends on whether the review covers a pull request. Select the variant by the review that the agent just produced: A `review-pr` run has a PR reference in the review header and a PR-description spec source, and its author is typically someone else; a `review-branch` run has neither, and its code is typically our own.
|
|
163
|
-
|
|
164
|
-
#### Options: Local-branch variant (review-branch)
|
|
165
|
-
|
|
166
|
-
| # | Emoji | Option | Description |
|
|
167
|
-
| --- | ----- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
|
|
168
|
-
| 1 | 🚀 | Implement directly and commit | Fix the findings in this session and commit the fix |
|
|
169
|
-
| 2 | 📋 | Ask the author to address the findings | Hand the findings to the author for disposition |
|
|
170
|
-
| 3 | 📋🔍 | Wait for the author to address the findings, then re-review | Wait for the author's fixes, then re-review the branch |
|
|
171
|
-
| 4 | 🎫 | Create a follow-up ticket | Spin the separable findings into their own ticket, per `scope-and-deferral.md`; the next matching rule decides the rest |
|
|
172
|
-
|
|
173
|
-
#### Options: PR variant (review-pr)
|
|
174
|
-
|
|
175
|
-
| # | Emoji | Option | Description |
|
|
176
|
-
| --- | ----- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
177
|
-
| 1 | 📋 | Post findings on the PR | Post the findings as comments anchored to file and line. On Bitbucket, use the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md); GitHub does not have a posting mechanism yet (see #1018) |
|
|
178
|
-
| 2 | 🚀 | Implement directly and commit | Fix the findings in this session and commit the fix |
|
|
179
|
-
| 3 | 🎫 | Create a follow-up ticket | Spin the separable findings into their own ticket, per `scope-and-deferral.md`; the next matching rule decides the rest |
|
|
180
|
-
|
|
181
|
-
#### Output format
|
|
182
|
-
|
|
183
|
-
Render the list per [option format](#option-format). Each option has a marker (■■■/■■□/■□□/□□□); the recommendation rules below determine which option takes the strongest marker. Whenever an option would change source, which is every rendering of this sub-block that offers "Implement directly and commit", the source delta renders above the list per [proposed-edit preview](#proposed-edit-preview). Pros and cons are omitted by default: Add a `➕` or `➖` line only when the specific findings present a tradeoff that survives the option-format tests bearing on which option fits (e.g., "the fixes touch a shared contract used outside this package"). Generic option properties are noise and must be omitted. That default applies to pros and cons alone: It never suppresses the proposed-edit preview, which is required content.
|
|
184
|
-
|
|
185
|
-
**What the commit records.** Selecting the option applies the previewed edits and commits them, composed per `{skill:create-commit}`, whose one-unit rule decides whether they form one commit or several. The commit is always a new one, never an amend: The separate commit keeps the fix visible as a diff and revertible while the branch exists, and a squash merge discards the history that an amend would tidy. Nothing is pushed, which matters most in the PR variant, in which the branch belongs to someone else.
|
|
186
|
-
|
|
187
|
-
**Naming the ticket's subset.** When only some open findings clear rule 1's spin-off bar, the follow-up-ticket line names the ones that it would cover, as `Create a follow-up ticket for R2, S1`. Choosing it disposes of those findings alone. In this case the ticket option composes with the recommendation rather than replacing it: The cascade's remaining rules run on the findings that the ticket does not cover, the option selected by those rules is the one marked, and answering with both numbers disposes of every open finding. A ticket option covering every open finding renders bare.
|
|
188
|
-
|
|
189
|
-
Local-branch variant, rendered for a review whose findings are all discretionary and all a single named change:
|
|
190
|
-
|
|
191
|
-
```
|
|
192
|
-
Next steps:
|
|
193
|
-
|
|
194
|
-
Actionable findings:
|
|
195
|
-
|
|
196
|
-
Proposed edits to the source:
|
|
197
|
-
|
|
198
|
-
**T1: test code.** Assert the corrected error classes in `parseRange.test.ts`. Every changed row keeps its message text and only gains the wrapper.
|
|
199
|
-
|
|
200
|
-
| Line | Case | `toThrow(…)` becomes |
|
|
201
|
-
| ------------ | ------------------- | -------------------------------------- |
|
|
202
|
-
| 62 | index out of bounds | `toThrow(new RangeError(msg))` |
|
|
203
|
-
| 33, 38, 43 | missing key | unchanged; that throw is still `Error` |
|
|
204
|
-
|
|
205
|
-
**S1: comment.** Replace the stale `@returns` line on `resolveBase` (`resolve.ts:88`) with a `todo:` naming what went stale.
|
|
206
|
-
|
|
207
|
-
1. 🚀 ■■□ Implement directly and commit
|
|
208
|
-
2. 📋 ■□□ Ask the author to address the findings
|
|
209
|
-
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
210
|
-
4. 🎫 ■□□ Create a follow-up ticket
|
|
211
|
-
|
|
212
|
-
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
213
|
-
```
|
|
214
|
-
|
|
215
|
-
Local-branch variant, rendered when a finding names alternatives that the author owns. The entry states the alternatives; choosing option 1 hands that call to whoever implements:
|
|
216
|
-
|
|
217
|
-
```
|
|
218
|
-
Next steps:
|
|
219
|
-
|
|
220
|
-
Actionable findings:
|
|
221
|
-
|
|
222
|
-
Proposed edits to the source:
|
|
223
|
-
|
|
224
|
-
**W2: source, author's choice.** `flush()` in `writer.ts:140` swallows the write error. Propagate it, or log and continue; which one turns on whether callers can recover.
|
|
225
|
-
|
|
226
|
-
1. 🚀 ■□□ Implement directly and commit
|
|
227
|
-
2. 📋 ■■□ Ask the author to address the findings
|
|
228
|
-
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
229
|
-
4. 🎫 ■□□ Create a follow-up ticket
|
|
230
|
-
|
|
231
|
-
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
232
|
-
```
|
|
233
|
-
|
|
234
|
-
Local-branch variant, rendered when three findings naming a single change each appear next to one separable recommendation. The ticket option's findings keep their entries, since the user is consenting to their disposition too:
|
|
235
|
-
|
|
236
|
-
```
|
|
237
|
-
Next steps:
|
|
238
|
-
|
|
239
|
-
Actionable findings:
|
|
240
|
-
|
|
241
|
-
Proposed edits to the source:
|
|
242
|
-
|
|
243
|
-
**S1: source.** Rename `x` to `descriptiveName` at its four sites in `resolve.ts`.
|
|
244
|
-
|
|
245
|
-
**S2: comment.** Drop the paraphrase above the `useDocumentTitle` call in `Header.tsx:31`.
|
|
246
|
-
|
|
247
|
-
**S3: test code.** Add the empty-input case to `parseRange.test.ts`, asserting the `RangeError` that the guard now throws.
|
|
248
|
-
|
|
249
|
-
**R2: source.** Extract the retry loop from `client.ts` into a helper shared by the three callers.
|
|
250
|
-
|
|
251
|
-
1. 🚀 ■■□ Implement directly and commit
|
|
252
|
-
2. 📋 ■□□ Ask the author to address the findings
|
|
253
|
-
3. 📋🔍 ■□□ Wait for the author to address the findings, then {skill?:review-branch}
|
|
254
|
-
4. 🎫 ■□□ Create a follow-up ticket for R2
|
|
255
|
-
|
|
256
|
-
If the author is an agent, run {skill?:respond-to-review} in that session.
|
|
257
|
-
```
|
|
258
|
-
|
|
259
|
-
PR variant, rendered for the default case. "Implement directly and commit" is on the menu, so the preview renders here too:
|
|
260
|
-
|
|
261
|
-
```
|
|
262
|
-
Next steps:
|
|
263
|
-
|
|
264
|
-
Actionable findings:
|
|
265
|
-
|
|
266
|
-
Proposed edits to the source:
|
|
267
|
-
|
|
268
|
-
**F1: source.** Guard the null branch in `parseRange.ts:44` before the index read, returning the empty result that the caller already handles.
|
|
269
|
-
|
|
270
|
-
**S1: test code.** Add the empty-input case to `parseRange.test.ts`.
|
|
271
|
-
|
|
272
|
-
1. 📋 ■■□ Post findings on the PR
|
|
273
|
-
2. 🚀 ■□□ Implement directly and commit
|
|
274
|
-
3. 🎫 ■□□ Create a follow-up ticket
|
|
275
|
-
```
|
|
276
|
-
|
|
277
|
-
Per the session-boundary rule, two options name a skill in the render:
|
|
278
|
-
|
|
279
|
-
- **Ask the author to address the findings**: The author's disposition happens in another session. The separate line below the list names `respond-to-review` for the case in which that author is an agent.
|
|
280
|
-
- **Wait for the author to address the findings, then re-review**: Names `review-branch` in the render, because the re-review runs after a wait that only the user can end. It does not have a "Clear context" prefix: The saved review records the findings, so the re-review works the same in this session or a fresh one.
|
|
281
|
-
|
|
282
|
-
#### Recommendation rules
|
|
283
|
-
|
|
284
|
-
Both variants share one cascade. Check the rules in order and stop at the first match. Every rule states a firing condition, and an option is never a default that fires for lack of one: A conditionless option outranks a conditioned one in practice, however the conditions are worded.
|
|
285
|
-
|
|
286
|
-
1. **Create a follow-up ticket**: Every open finding clears one of [`scope-and-deferral.md`](../_data/scope-and-deferral.md)'s affirmative reasons for spinning off, namely a genuinely separable concern, a materially different risk surface, size that would overwhelm the current change, or independent prioritization. "The ticket didn't mention it" is never such a reason. Absent an affirmative reason the fold-in default applies and the cascade continues.
|
|
287
|
-
2. **Implement directly and commit**: Every open finding names a single change rather than a choice among alternatives, which are the two shapes that the [Proposed-change gate](../review-criteria/SKILL.md#proposed-change-gate) admits. Implementing forfeits the second look, and the single-change shape makes that acceptable: The fix's diff is the finding restated, so a reviewer would be re-reading text that the review already contains. One finding leaving its choice to the author is enough to fail this rule, however small the alternatives look, since implementing would settle it on the author's behalf.
|
|
288
|
-
3. **Wait for the author to address the findings, then re-review**: The findings need judgment that the author owns, and the fixes are substantial enough that the result needs another review pass. PR variant: Skip this rule.
|
|
289
|
-
4. **Ask the author to address the findings**: Residual. The reviewer reports; the author disposes. PR variant: **Post findings on the PR**, since the author is typically someone else and comments on the PR are how they receive the findings.
|
|
290
|
-
|
|
291
|
-
Every rule tests the open findings as a collection, which lets one recommendation stand for the set. When only some findings clear rule 1's spin-off bar, the cascade evaluates the remainder: The recommendation comes from the findings that stay, while the separable ones go to the follow-up-ticket option, whose rendered line names them.
|
|
292
|
-
|
|
293
|
-
Whether a change is discretionary and which shape it has are independent axes. Whether a change is optional is a different question from who decides it: An `S` reading "rename `x` to `descriptiveName`" is discretionary and still a single named change, since the only decision left is yes or no and the person reading the menu is the one making it. Handing that to the author sends an edit that is already settled through a second session.
|
|
294
|
-
|
|
295
|
-
Do not attempt to detect whether the author is the person reading the review. Agents commit under the user's git identity, so the review's resolved `{author}` cannot distinguish them. Rule 2 turns on the review's own content, which is decidable.
|
|
296
|
-
|
|
297
|
-
#### Marker strengths
|
|
298
|
-
|
|
299
|
-
The selected option's marker follows how cleanly its rule matched: ■■■ when the rule's test is met squarely and the alternatives are worse on the criteria that decided it, ■■□ when the fit is good but an alternative stays defensible, ■□□ when little separates the options. The others take ■□□ by default, and □□□ when one has a clear drawback in the current context.
|
|
300
|
-
|
|
301
|
-
Complexity levels classify individual findings, but the recommendation applies to the collection.
|
|
302
|
-
|
|
303
|
-
When the cascade's conditions leave two options genuinely in balance, prefer the one that keeps a human in the loop. That resolves a tie and nothing more: It never overrides a rule that fired, and a fix that satisfies rule 2's single-change test is not a tie.
|
|
304
|
-
|
|
305
|
-
### Blocked-step sub-block
|
|
306
|
-
|
|
307
|
-
Shown when something that the user can clear, such as a sandbox denial, a missing credential, or a stopped service, blocked a review step and remains once the routes that do not need any action from the user, such as an ephemeral runner for a missing tool, are exhausted. A clean review renders it like any other trigger. The line above the options names the step and the blocker, and the first option names the action that supplies the missing resource, such as a login or a grant, never the blocked step for the user to run:
|
|
308
|
-
|
|
309
|
-
```
|
|
310
|
-
{step} was blocked: {blocker}.
|
|
311
|
-
|
|
312
|
-
1. 🔓 ■■■ {Action that supplies the resource, e.g. run `! {login command}`}, then re-run {step}
|
|
313
|
-
2. ⏭️ ■□□ Accept the review without {step}
|
|
314
|
-
```
|
|
315
|
-
|
|
316
|
-
### Combined output format
|
|
317
|
-
|
|
318
|
-
When multiple sub-blocks are shown, present them as separate sections within a single next-steps block. Ordering is Blocked step → Deviations → Source divergence → Actionable findings. Each sub-block that edits an artifact edits a different one, so selecting several runs each edit against its own preview. Because source divergence appears only in PR reviews, a block that includes it renders the Findings PR variant. The example below illustrates one such arrangement; each sub-block's recommendation rules and marker strengths determine which marker applies to each option:
|
|
319
|
-
|
|
320
|
-
```
|
|
321
|
-
Next steps:
|
|
322
|
-
|
|
323
|
-
**A1: Deviations from ticket**
|
|
324
|
-
|
|
325
|
-
Proposed edit to the acceptance criteria:
|
|
326
|
-
- Drop: A `--strict` flag gates the new validation
|
|
327
|
-
|
|
328
|
-
1. 📝 ■■□ Update the acceptance criteria on {ticket_ref}
|
|
329
|
-
2. ⏭️ ■□□ Leave as-is
|
|
330
|
-
|
|
331
|
-
**A2: Source divergence**
|
|
332
|
-
|
|
333
|
-
Proposed edit to the PR description:
|
|
334
|
-
- D2: "Unknown directives are warned on" → "Unknown directives fail the run"
|
|
335
|
-
|
|
336
|
-
1. 📝 ■■□ Update PR description
|
|
337
|
-
2. ⏭️ ■□□ Leave as-is
|
|
338
|
-
|
|
339
|
-
**A3: Actionable findings**
|
|
340
|
-
|
|
341
|
-
Proposed edits to the source:
|
|
342
|
-
|
|
343
|
-
**F1: source.** Fail on an unknown directive in `directives.ts:52`, replacing the warning that the loop currently emits.
|
|
344
|
-
|
|
345
|
-
**S1: test code.** Add the unknown-directive case to `directives.test.ts`, asserting the failure.
|
|
346
|
-
|
|
347
|
-
1. 📋 ■■□ Post findings on the PR
|
|
348
|
-
2. 🚀 ■□□ Implement directly and commit
|
|
349
|
-
3. 🎫 ■□□ Create a follow-up ticket
|
|
350
|
-
```
|
|
@@ -1,18 +0,0 @@
|
|
|
1
|
-
**Write the tightened ticket, not a draft to be tightened later.** A ticket is the minimal contract that a reader needs, not a transcript of the design session. Compose the maximally tight version that still keeps the full meaning; length comes from content, not from a completeness instinct. (Producing the tight version up front spares the reader, and spares everyone the tighten-on-request round trip.)
|
|
2
|
-
|
|
3
|
-
State conclusions, not the journey to them. Naming a chosen approach (including "X, not Y") is a durable decision and belongs in the ticket. The _story_ of how the decision was reached does not: Drop the design back-and-forth, the false starts, restated context, and motivating episodes.
|
|
4
|
-
|
|
5
|
-
**Self-check before presenting.** For each sentence, ask: Would removing it change what the reader does or how the work gets executed? If not, cut it. State each acceptance criterion once, and do not restate it in surrounding prose.
|
|
6
|
-
|
|
7
|
-
Add a design-narrative section (rationale, alternatives explored) only when the user explicitly asks for it.
|
|
8
|
-
|
|
9
|
-
**Before** (the design journey is left in):
|
|
10
|
-
|
|
11
|
-
> We first considered extending the existing `FooAdapter`, but a spike showed it couples the cache to the transport, so after some back-and-forth we landed on a separate `CacheLayer`. The team has struggled with cache invalidation before, and this should finally fix that. Acceptance: A new `CacheLayer` module exists. It must be covered by tests so we know it works.
|
|
12
|
-
|
|
13
|
-
**After** (conclusion only, full meaning intact):
|
|
14
|
-
|
|
15
|
-
> Add a `CacheLayer` separate from the transport (not an extension of `FooAdapter`, which would couple cache to transport).
|
|
16
|
-
>
|
|
17
|
-
> - [ ] `CacheLayer` is independent of the transport.
|
|
18
|
-
> - [ ] New behavior is covered by tests.
|
|
@@ -1,14 +0,0 @@
|
|
|
1
|
-
**Place ticket content by kind, not by volume.** A ticket states the change's _subject_ and the _outcomes_ that it must produce; the _mechanism_ that achieves them belongs with the implementation, not the ticket. This is a separate axis from concision: A perfectly short ticket can still contain the wrong _kind_ of content.
|
|
2
|
-
|
|
3
|
-
- **Ticket**: The change's **subject** (the defect being fixed, the current structure being changed, the target contract or behavior that it exposes) and **key** non-obvious details that save the implementer real derivation (e.g. "reuse the sibling table's `getSortValue`").
|
|
4
|
-
- **Implementation**: The **mechanism**, meaning internal wiring, files as a diff-list, step sequences, deletion lists, and the internal props/config of a dependency consumed by the change.
|
|
5
|
-
|
|
6
|
-
The line is subject vs. mechanism, not code vs. prose: A code name is fine when it _is_ the subject. **Bug and refactoring tickets** name existing code because that code is the subject. Keep it; the fix procedure still belongs with the implementation.
|
|
7
|
-
|
|
8
|
-
**Before** (a feature ticket transcribing a reference implementation's API surface):
|
|
9
|
-
|
|
10
|
-
> Set `columnDefs`, pass `getSortedRowModel`, and wire `state.sorting`; pin the first column via `columnPinning.left: ['name']`; mock `@acme/table` in `__mocks__/@acme/table/compiled.tsx`.
|
|
11
|
-
|
|
12
|
-
**After** (the same change stated as the contract that it must honor):
|
|
13
|
-
|
|
14
|
-
> Every column sorts client-side, and the first column stays pinned during horizontal scroll. (Which props wire this up is implementation.)
|
|
@@ -1,6 +0,0 @@
|
|
|
1
|
-
Start from this skeleton. Add a section only when it adds signal on which the reader must act.
|
|
2
|
-
|
|
3
|
-
- **Problem** and **Acceptance criteria (Must have)**: Always present.
|
|
4
|
-
- **Context**, **Proposed solution** (including "X, not Y"), and **Should have / Nice to have**: Opt-in, added only when the reader needs them. Omit empty tiers.
|
|
5
|
-
|
|
6
|
-
This applies the [concision principle](../_data/concision.md) to tickets.
|