codeassembly-guidance 0.1.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.
Files changed (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: refine-guidance
3
+ description: Turn a lesson into a guidance change, conversationally. Finds the rule that already states the lesson or places a new artifact per the content specification, confirms the placement, drafts the edits for approval, applies them, opens a pull request, and marks any feedback events that the lesson came with as addressed by it. Use when a lesson from the conversation, a pasted finding, or a triage-feedback ticket should become a change to a skill, subagent, rulebook, partial, or AGENTS.md.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Refine guidance
8
+
9
+ Turn one lesson into one guidance pull request. You find whether a rule already states the lesson, place the change, draft the edits, and deliver them; the developer approves the placement and then the edits. A rule that exists and keeps failing is the common case, and it calls for changing that rule rather than adding a parallel one.
10
+
11
+ **Announce at start:** "Using refine-guidance to turn this lesson into a guidance change."
12
+
13
+ ## Arguments
14
+
15
+ | Argument | Description | Required |
16
+ | ---------------- | --------------------------------------------------------------------------------------------------- | -------- |
17
+ | `[target]` | A guidance file to change: a source file or a deployed copy. Without one, step 4 places the change. | No |
18
+ | `--ticket <ref>` | A ticket that states the lesson, such as one that {skill?:triage-feedback} filed. | No |
19
+
20
+ The lesson comes from the conversation when the conversation states one. Otherwise it comes from `--ticket`, and without that, from the branch's ticket.
21
+
22
+ ## Prerequisites
23
+
24
+ Placement follows the `codeassembly-content-specification` rulebook, which deploys as the `consult-codeassembly-content-specification` skill in a repository that declares it. When it is not deployed, report that and stop before step 4.
25
+
26
+ ## Never edit
27
+
28
+ - Text inside a generated region, which the next deployment rewrites.
29
+ - A deployed copy. Edit its source, which step 3 resolves.
30
+ - A file in another repository. Step 4 offers a ticket there instead.
31
+
32
+ ## Process
33
+
34
+ ### 1. Preflight
35
+
36
+ Run `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` and read `branch_name`, `default_branch`, and `ticket_id`. Stop on the default branch, and report that the change needs a ticket branch: This skill commits and opens a pull request from the current branch.
37
+
38
+ ### 2. Resolve the lesson
39
+
40
+ Take the lesson from the conversation or from a finding pasted into it. When the conversation does not state one, resolve `--ticket`, or else the branch's ticket, per [ticket source resolution](../_data/ticket-source-resolution.md), and take the lesson from the ticket. Restate the lesson in one sentence: the behavior that the agent showed and the behavior that the lesson asks for.
41
+
42
+ Collect any feedback event ids that the input contains, with their store. An event id is a ULID, 26 Crockford base32 characters; a {skill?:triage-feedback} ticket lists them in its context under the store name. When the input names ids without a store, the store is `@feedback`. Input without ids makes step 9 a no-op.
43
+
44
+ ### 3. Find existing coverage
45
+
46
+ Search the guidance for a rule that states the lesson: the library's content, the repository's `.agents/content`, and its `AGENTS.md`. Search with `rg` on the lesson's key terms, then read each matching section and the descriptions of the rulebooks that it reaches. A rule states the lesson when following its directive would have prevented the behavior that the lesson describes. A rule that covers the lesson in part is still the rule to change.
47
+
48
+ Run `resolve` on the target, or on the files that the search found:
49
+
50
+ ```bash
51
+ node {harness_home_dir}/skills/streamline-guidance/streamline-guidance.mjs resolve {paths}
52
+ ```
53
+
54
+ It maps each deployed copy to its source (`redirectedFrom`) and reports each file's `dirty` state and `generatedRegions`. Report every redirect.
55
+
56
+ ### 4. Place the change
57
+
58
+ Decide the mode, and give its reason in one sentence:
59
+
60
+ - **An existing rule states the lesson**: `strengthen`, `relocate`, or `illustrate` it, per "Choosing a kind" in the content specification.
61
+ - **The guidance does not state it**: a new artifact, `new {kind} in {content root}`, with the kind and the content root chosen per the same section.
62
+
63
+ Decide which repository owns the target. A file with a `<!-- codeassembly-` marker, or a file in the CodeAssembly guidance library, belongs to the CodeAssembly repository, per [deployed-file provenance](../_data/deployed-file-provenance.md); a project's `.agents/content` file or `AGENTS.md` belongs to that project's repository. When the owner is not the current repository, do not edit the file: Offer to file the lesson there with {skill:create-ticket} `--repo {repo}`, and stop.
64
+
65
+ Present the placement: the lesson, the mode and its reason, and the target file or the new artifact's path. Ask for confirmation before drafting.
66
+
67
+ ### 5. Draft the edits
68
+
69
+ Draft under "Adding guidance" in the content specification: Change the fewest surfaces that plausibly account for the behavior, and trim any text that the change makes redundant, in that file or another. A new artifact follows the content specification and the repository's content conventions: its frontmatter, its naming, its dependency declarations, and the tests that the repository runs over its content.
70
+
71
+ Before presenting the edits, run `resolve` on every existing file that a drafted edit changes and on each rulebook whose `version` step 6 will bump. Stop if any of them is `dirty`, and name it: The commit must contain only this run's edits.
72
+
73
+ Present each edit as a numbered row: file, line, the text that it replaces (or `new file`), and the new text. Ask for one approval that covers applying the edits, the commit, the push, and the pull request. A row that the developer declines is dropped; re-draft only when the developer asks.
74
+
75
+ ### 6. Apply
76
+
77
+ <!-- include: ../_partials/apply-guidance-edits.md / -->
78
+
79
+ ### 7. Commit
80
+
81
+ Commit per {skill:create-commit}, passing the edited paths and the purpose `{mode}: {reason}` from step 4.
82
+
83
+ ### 8. Open the pull request
84
+
85
+ Push with `git push --set-upstream origin HEAD`, which the approval in step 5 covers: {skill:create-pr} does not push, and it stops when the branch is not up to date with its remote. On a failed push, report it and stop. Then open the pull request with {skill:create-pr}.
86
+
87
+ ### 9. Mark the events
88
+
89
+ Skip this step when step 2 did not collect any event id: This skill does not write to a knowledge base otherwise.
90
+
91
+ Mark the events with {skill:kb-update-events}: `--store {store} --add-addressed-by={pull request URL}` and the event ids. Report each id whose result has `ok: false`.
92
+
93
+ ### 10. Report
94
+
95
+ Report the pull request's URL, the mode and its reason, the edited files, the marked event ids, and each id that failed. When an edited file is larger than before, offer {skill:streamline-guidance} on it in the action-items block, per "Adding guidance": That run commits on the same branch, which adds its cuts to the open pull request. The block contains nothing else.
96
+
97
+ <!-- include: ../_partials/action-items.md / -->
@@ -31,10 +31,14 @@ Before every {tool:Task} call and after every phase completion, output a status
31
31
  1. Read the plan file. If not found, report an error and stop.
32
32
  2. Parse YAML frontmatter from the plan content. If a `provenance` block is present, store it as `{input-provenance}`. If the plan does not have frontmatter or a `provenance` block, set `{input-provenance}` to empty.
33
33
  3. Resolve the ticket source:
34
- - GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body {url}` via Bash to fetch content.
34
+ - GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body,blockedBy {url}` via Bash to fetch content.
35
35
  - File path -> Read the file.
36
+ - Jira URL or key -> Fetch per the Jira entry in [platform-specific fetch](../_data/ticket-source-resolution.md#platform-specific-fetch).
36
37
  - Other URL -> Fetch the URL content.
37
- 4. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout.
38
+
39
+ Then report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop the review.
40
+
41
+ 4. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `branch_name`, `default_branch`, `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout. Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths in the plan's **Files:** lists, before the review starts.
38
42
  5. Resolve artifact directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
39
43
  6. `mkdir -p {artifact_dir}`
40
44
 
@@ -157,7 +161,7 @@ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash.
157
161
 
158
162
  The `provenance:` block is **not** populated from the script. Construct it manually per the case branches below.
159
163
 
160
- **Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not carried forward from `{input-provenance}`. This is correct: The output is a new artifact at a new point in time on a potentially different branch. The `provenance:` block's camelCase convention (`baseSha`, `isInteractive`, `refinedBy`) is preserved as-is on both read and write; the keys are not renamed. Provenance fields carried forward from the input are `skill`, `baseSha`, `isInteractive`, and `iteration` (per the case branches).
164
+ **Round-trip preservation:** The top-level canonical fields (`branch`, `commit`, etc.) are always re-resolved from current session context via the script; they are not copied from `{input-provenance}`. This is correct: The output is a new artifact at a new point in time on a potentially different branch. The `provenance:` block's camelCase convention (`baseSha`, `isInteractive`, `refinedBy`) is preserved as-is on both read and write; the keys are not renamed. Provenance fields copied from the input are `skill`, `baseSha`, `isInteractive`, and `iteration` (per the case branches).
161
165
 
162
166
  **When `{input-provenance}` is non-empty:**
163
167
 
@@ -0,0 +1,113 @@
1
+ ---
2
+ name: refine-prototype
3
+ description: Refine one prototype page at sketch speed, between the verdict on a round and the end vision, or sketch a variant of a built product the same way. Transfers the kept and adapted ideas of the round to the base, applies the developer's commands in batches while the page reloads in their browser, snapshots each accepted version into the ticket's prototype set with its id on the page, and records every accepted change in a refinement log that the end vision reads. Use when the developer wants to refine, combine, or vary prototypes before a ticket is written.
4
+ user-invocable: true
5
+ supported-harnesses: [claude]
6
+ ---
7
+
8
+ # Refine prototype
9
+
10
+ Work one prototype page the way a designer works a sketch: The developer gives commands, you apply them to the page, their browser shows the result, and nothing else runs. The development gates are off on purpose. A sketch is the reference for the ticket that follows, never the implementation, and it is fast because it skips what a change to the product needs.
11
+
12
+ The page is in the ticket's prototype set, per {skill:index-prototypes}, and each snapshot adds the accepted version to the set under its id: The snapshot replaces the slug's card on the index under the new id, and the manifest and the refinement log keep the earlier versions.
13
+
14
+ ## Inputs
15
+
16
+ - **The set**: its manifest and verdicts, the latest `idea-decisions` artifact in the ticket directory, and any `refinement-log` artifact there.
17
+ - **The base**: the prototype that the developer names by its number, or the winner when they name none. When the base is a built product rather than a page, the base is one region of it, reconstructed as a page from a screenshot and the design doc. It takes a new slug, and its band and description name what it was built from.
18
+ - **The developer's commands**, in their words: "Move the rail under the matrix", "Tighten the row spacing", "Split Start from into two tabs", "Take the scope text area from 4".
19
+
20
+ ## Rules of the sketch
21
+
22
+ Off:
23
+
24
+ - Tests, lint, formatters, type checks, and every `nmr` command.
25
+ - Commits, branches, and edits to the ticket, the design doc, or any file outside the set directory, the scratch directory, and the artifact directory.
26
+ - The brainstorming, planning, test-driven, review, and verification skills. A sketch does not have a plan or a review.
27
+ - Questions that a render answers. When a command admits two renderings, render both and let the developer pick.
28
+
29
+ On:
30
+
31
+ - The page is self-contained and opens from `file://`, with its demo chrome in a band whose every part is inside an element that has `data-demo`, as the brief that built it required.
32
+ - The band's first line is the page's id and title, `{number}.{version} {title}`, so that the developer reads which version they have open without returning to the index.
33
+ - {rulebook:accessibility-conventions} is the floor: Check contrast and size when a command changes a colour or a text size.
34
+ - A new string on the product surface follows {rulebook:ui-copy-conventions}.
35
+ - One working file. A batch edits it in place; a fork is written next to it and is deleted once the developer picks.
36
+
37
+ ## Process
38
+
39
+ ### 1. Resolve the set and the base
40
+
41
+ Resolve the set directory and the scratch directory per {skill:index-prototypes} step 1, read back the verdicts per its "Read back the verdicts", and read the latest `idea-decisions` and `refinement-log` artifacts in the ticket directory. Name the base to the developer as `{id} {title}`.
42
+
43
+ A refinement keeps the base's slug, and its first snapshot takes the slug's next version. Resolve the id before the first edit:
44
+
45
+ ```bash
46
+ node {harness_home_dir}/skills/index-prototypes/index-prototypes.mjs resolve-ids \
47
+ --set-dir "{set_dir}" \
48
+ --slugs {slug}
49
+ ```
50
+
51
+ Copy the base's latest source to `{scratch_dir}/{slug}-v{n}.html`, the working file, and set the band's first line to the new id. A base reconstructed from a built product takes a new slug and starts at version 1, and its band's first line names the source after the id, such as `6.1 Start from as tabs, from the api-tokens page`.
52
+
53
+ ### 2. Serve the working file
54
+
55
+ Start a reloading server on the scratch directory in the background, and give the developer the working file's URL once:
56
+
57
+ ```bash
58
+ pnpm dlx vite --host 127.0.0.1 "{scratch_dir}"
59
+ ```
60
+
61
+ Read the host and port from the server's `Local:` line; when `pnpm` is absent, run `npx --yes vite` the same way. The developer keeps `{local_url}/{slug}-v{n}.html` open, and the server reloads it on every save. Capture screenshots from the same server with the Playwright MCP, per {skill:index-prototypes} step 3, at width 1280 and at width 390.
62
+
63
+ ### 3. Propose the transplants
64
+
65
+ The verdict picked the base; it did not pick the base's ideas over the others. From the `idea-decisions` table, list every row whose decision is `keep` and whose sources do not include the base, and every row whose decision is `adapt`, and propose them as the first batch in one action-items block, ordered so that a structural change comes before the changes that depend on it. The developer trims or reorders the list.
66
+
67
+ A transplant moves the mechanism, not the look: Read the source prototype's file, and copy the markup, the styles, and the script that make the idea work, fitted to the base. Rebuilding an idea from its screenshot is a defect, because a screenshot does not show what the mechanism does.
68
+
69
+ <!-- include: ../_partials/action-items.md / -->
70
+
71
+ ### 4. Apply the batches
72
+
73
+ Each turn, take every command in the developer's message as one batch:
74
+
75
+ 1. Apply every command to the working file.
76
+ 2. Take the screenshots, and look at them before replying. An overlap, a cut-off, text under the size floor, or a contrast failure that a command caused is reported with the batch, not left for the developer to find.
77
+ 3. For a command that admits two renderings, write each as `{scratch_dir}/{slug}-v{n}-{letter}.html`, screenshot both, and leave the working file as it was before that command. The developer picks by letter; the next batch applies the pick and deletes the forks.
78
+ 4. Append each applied command to the session's log, under the id of the version that it will enter, with the developer's reason when they gave one and the source id when it was a transplant.
79
+ 5. Reply with one line per command (applied, forked with its letters and their URLs, or refused with the reason), and nothing else. The developer looks at the browser, not at a description of it.
80
+
81
+ Propose a new number when a batch replaces the layout or the model to the point that the earlier version's verdicts and notes no longer describe the page. On yes, the working file takes a new slug and the id that `resolve-ids` gives it, and its band names the version from which it came. The old slug keeps its last snapshot.
82
+
83
+ ### 5. Snapshot
84
+
85
+ Snapshot when the developer asks for one, in any words ("snapshot", "keep this", "version it"), and at the end of the session before stopping. A snapshot creates a version: Until then the working file is unregistered, and a session that stops without one loses the work since the last.
86
+
87
+ 1. Copy the working file to `{set_dir}/{slug}-v{n}.html`.
88
+ 2. Publish it with the Artifact tool: to the slug's existing artifact URL when the manifest's latest entry for the slug has one, so that the index card's link stays current, or as a new artifact for a new slug.
89
+ 3. Capture its screenshots per {skill:index-prototypes} step 3, and register it per its step 4 with `--number {number}`, `--source`, the set's note labels (copied from the latest entry, with any change that the batches made to them), and, for a new slug, a `--description` that names the version from which it came.
90
+ 4. Update the set's summary per {skill:index-prototypes} step 5, naming the version in `changes`, then render and republish the index per its step 6.
91
+ 5. The next batch opens the next version: Copy the snapshot to `{scratch_dir}/{slug}-v{n+1}.html` and set the band's id.
92
+
93
+ ### 6. Close
94
+
95
+ When the developer says that the refinement is done:
96
+
97
+ 1. Snapshot whatever has changed since the last one.
98
+ 2. When the ticket or the design doc names a component library, dispatch one reader with {tool:Task} (`subagent_type: general-purpose`, model `sonnet`) to list every element of the final page that the library does not supply, each with the nearest thing that the library has. The decisions on those belong to the end vision, not to this skill.
99
+ 3. Save the log per [The refinement log](#the-refinement-log).
100
+ 4. Stop the server, and give the developer the index link, the final id, and the log's path.
101
+
102
+ The end vision writes the design doc from the log and the `idea-decisions` artifact. This skill edits neither.
103
+
104
+ ## The refinement log
105
+
106
+ Save it with {skill:save-artifact} as a ticket-level `refinement-log` artifact:
107
+
108
+ - `## Base`: the base's id and title, and the index URL.
109
+ - `## Snapshots`: one `### {id}` per snapshot in order, each listing its accepted changes, one line per change, with the developer's reason when they gave one and `from {id}` on a transplant.
110
+ - `## Open forks`: forks shown and not picked, each with its letters and what differed.
111
+ - `## Library check`: the reader's list from step 6, when it ran.
112
+
113
+ A later session starts a new log from the latest snapshot; it does not edit this one.
@@ -155,7 +155,7 @@ The disposition conflates two decisions: whether the change belongs (substance),
155
155
 
156
156
  ## Writing code after a review
157
157
 
158
- Implementing an ACCEPTed finding puts you mid-conversation with the reviewer, which is when that voice enters the comments. A comment must not narrate the change, retell the reviewer's concern, or cite a finding or acceptance-criterion ID.
158
+ Implementing an ACCEPTed finding puts you mid-conversation with the reviewer, which is when comments start to repeat the reviewer's wording. A comment must not narrate the change, retell the reviewer's concern, or cite a finding or acceptance-criterion ID.
159
159
 
160
160
  **Before** (narrates the review, cites a finding and an acceptance criterion):
161
161
 
@@ -36,7 +36,7 @@ On HEAD mismatch, do not return; exit non-zero with the mismatch error. `review-
36
36
 
37
37
  ## Bitbucket access
38
38
 
39
- Every Bitbucket call below goes through the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). That document owns the tool, the coordinates, the field vocabulary, and the not-connected stop; this skill states only what it does with them.
39
+ Make every Bitbucket call below with the tool named in [Bitbucket pull-request access](../_data/bitbucket-pr-access.md). That document specifies the tool, the coordinates, the field vocabulary, and the not-connected stop; this skill states only what it does with them.
40
40
 
41
41
  ## Process
42
42