codeassembly-guidance 0.0.0 → 0.2.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 (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,263 @@
1
+ ---
2
+ name: refine-plan
3
+ description: Review and refine an implementation plan for completeness and correctness
4
+ user-invocable: true
5
+ dependencies:
6
+ subagents:
7
+ - plan-reviewer
8
+ - plan-reviser
9
+ ---
10
+
11
+ # Refine plan
12
+
13
+ Perform a single review-and-revise round on a saved implementation plan, checking for completeness (decision gaps that the coder would fill) and correctness (factual accuracy against the codebase). Produces a refined plan ready for implementation.
14
+
15
+ ## Arguments
16
+
17
+ - Plan file path (required): Path to a saved plan artifact (e.g., the `{timestamp}_{slug}_plan.md` from `save-plan`)
18
+ - Ticket source (required): File path or URL (GitHub issue URL, Jira URL, etc.)
19
+
20
+ ## Visibility
21
+
22
+ Before every {tool:Task} call and after every phase completion, output a status line:
23
+
24
+ - **Before dispatch:** `-- Refine plan -- delegating to {agent}...`
25
+ - **After completion:** `-- Refine plan -- {summary}`
26
+
27
+ ## Flow
28
+
29
+ ### 1. Validate inputs and resolve context
30
+
31
+ 1. Read the plan file. If not found, report an error and stop.
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
+ 3. Resolve the ticket source:
34
+ - GitHub URL (`github.com/.../issues/...`) -> use `gh issue view --json title,body,blockedBy {url}` via Bash to fetch content.
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).
37
+ - Other URL -> Fetch the URL content.
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.
42
+ 5. Resolve artifact directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
43
+ 6. `mkdir -p {artifact_dir}`
44
+
45
+ ### 2. Dispatch plan-reviewer
46
+
47
+ Extract the slug from the original plan filename. The slug is the middle segment of `{timestamp}_{slug}_{artifact-type}.md`. If the filename doesn't follow this pattern, derive a slug from the filename.
48
+
49
+ Generate a UTC timestamp: `{YYYYMMDD-HHMMSSZ}`.
50
+
51
+ Set the review output path: `{artifact_dir}/{timestamp}_{slug}_plan-review.md`
52
+
53
+ `-- Refine plan -- delegating to plan-reviewer...`
54
+
55
+ Call {tool:Task} with `subagent_type: plan-reviewer`, `max_turns: 30`:
56
+
57
+ > Review the following implementation plan for completeness and correctness.
58
+ >
59
+ > **Plan file:** {plan_path}
60
+ >
61
+ > **Ticket/requirements:**
62
+ > {ticket content}
63
+ >
64
+ > **Output path:** {review_output_path}
65
+
66
+ Parse the return block:
67
+
68
+ - `Status`: Must be `completed`
69
+ - `AutoResolvable`: Integer count of auto-resolvable findings
70
+ - `UserQuestions`: Integer count of findings requiring user input
71
+
72
+ `-- Refine plan -- {AutoResolvable + UserQuestions} findings ({AutoResolvable} auto-resolvable, {UserQuestions} require user input)`
73
+
74
+ ### 3. Present user questions
75
+
76
+ Evaluate the finding counts:
77
+
78
+ - **0 total findings** (AutoResolvable = 0 AND UserQuestions = 0): Skip the reviser entirely. Report that the plan does not need any refinement, then present next steps.
79
+
80
+ ```
81
+ Plan reviewed -- no findings. The plan is ready for implementation.
82
+ Review: {review_output_path}
83
+ ```
84
+
85
+ <HARD-GATE>
86
+ Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The plan was just reviewed, and the review did not find any issues; use this as recommendation context. Use `{plan_path}` (the original plan argument, not `{revision_output_path}`; this path does not produce a revised plan) and `{ticket_source}` in each skill-invoking option line.
87
+ </HARD-GATE>
88
+
89
+ - **0 user questions** (UserQuestions = 0, AutoResolvable > 0): Skip user interaction. Proceed to step 4 with empty user answers.
90
+
91
+ - **User questions present** (UserQuestions > 0): Read the review artifact. Extract all findings from the "Decision gaps" section (these may be C or X findings -- the section is organized by resolution type, not finding category). Present each finding's question using the finding's ID (e.g., `C1`, `X2`) as the question identifier. When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
92
+
93
+ ```
94
+ The plan review identified {UserQuestions} question(s) that need your input:
95
+
96
+ **C1: {title}**
97
+ {question text}
98
+ 1. ■■■ {recommended option}:
99
+ - ➕ {strongest argument}
100
+ - ➕ {secondary argument}
101
+ 2. ■□□ {alternative option}:
102
+ - ➕ {pro}
103
+ - ➖ {con}
104
+
105
+ **X2: {title}**
106
+ {open-ended question text: describe what you want in free-form text}
107
+
108
+ Please answer using the finding ID (e.g., "C1: Option 2; X2: ..."), or respond in free-form text.
109
+ ```
110
+
111
+ Wait for the user's response. Capture their answers as `user_answers`.
112
+
113
+ <!-- include: ../_partials/action-items.md / -->
114
+
115
+ ### 4. Dispatch plan-reviser
116
+
117
+ Generate a new UTC timestamp for the refined plan.
118
+
119
+ Set the revision output path: `{artifact_dir}/{new_timestamp}_{slug}_plan-v2.md`
120
+
121
+ `-- Refine plan -- delegating to plan-reviser...`
122
+
123
+ Call {tool:Task} with `subagent_type: plan-reviser`, `max_turns: 30`:
124
+
125
+ > Revise the following implementation plan based on review findings and user answers.
126
+ >
127
+ > **Original plan:** {plan_path}
128
+ > **Review findings:** {review_output_path}
129
+ > **User answers:** {user_answers or "No user answers -- all findings are auto-resolvable."}
130
+ >
131
+ > **Ticket/requirements:**
132
+ > {ticket content}
133
+ >
134
+ > **Output path:** {revision_output_path}
135
+
136
+ Parse the return block:
137
+
138
+ - `Status`: Must be `completed`
139
+ - `Artifact`: Path to the refined plan
140
+
141
+ `-- Refine plan -- revision complete`
142
+
143
+ If the plan-reviser {tool:Task} failed or the return block does not have `Status: completed`, skip the provenance update and report the failure:
144
+
145
+ ```
146
+ Plan revision failed -- the plan-reviser did not complete successfully.
147
+ Review: {review_output_path}
148
+ ```
149
+
150
+ Stop here. Do not attempt provenance update or report completion.
151
+
152
+ Stamp the revised plan with frontmatter conforming to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema plus the [plan provenance](../_data/artifact-conventions.md#plan-provenance) extensions. This is the single write point for the revised plan's frontmatter: `plan-reviser` does not output any frontmatter of its own; `refine-plan` owns it.
153
+
154
+ The stamp writes the full canonical schema in one atomic write: the `provenance:` block plus the top-level canonical fields.
155
+
156
+ The top-level fields come from the script; the `provenance:` block is computed from `{input-provenance}` plus the stamping logic below.
157
+
158
+ This site uses `--format json` because the `provenance:` block is case-branched on the input artifact's existing provenance; see [artifact-conventions.md](../_data/artifact-conventions.md#bespoke-frontmatter-composition).
159
+
160
+ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --format json` via Bash. It emits a JSON object with the universal artifact fields (`branch`, `commit`, `baseSha`, `pr`, `ticket_id`, `ticket_ref`, `scm`, `timestamp`, `run_id`). Use those values verbatim for the matching YAML keys. Optional fields that the script omits from its output (`baseSha`, `pr`, `ticket_id`, `ticket_ref`, `run_id`) must be omitted from the frontmatter too; do not emit `null` or empty strings.
161
+
162
+ The `provenance:` block is **not** populated from the script. Construct it manually per the case branches below.
163
+
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).
165
+
166
+ **When `{input-provenance}` is non-empty:**
167
+
168
+ 1. Use the script's `baseSha` as the new value. If the script omitted `baseSha`, preserve the original `baseSha` from `{input-provenance}`.
169
+ 2. Read the revised plan file at `{revision_output_path}`.
170
+ 3. Construct updated provenance:
171
+ - `skill`: Preserve from `{input-provenance}` (the original authoring skill)
172
+ - `refinedBy`: Set to `refine-plan`
173
+ - `timestamp`: Use the script's `timestamp`
174
+ - `baseSha`: The script's value (or preserved original)
175
+ - `isInteractive`: Preserve from `{input-provenance}` if present
176
+ - `iteration`: If `{input-provenance}.iteration` is present, set to `{input-provenance}.iteration + 1`. If absent, set to `2`.
177
+ 4. Prepend the unified YAML frontmatter (`provenance:` block plus top-level canonical fields from the script) to the revised plan and write back. Example output (assuming input had `skill: design-and-plan` and `isInteractive: true` but did not have an `iteration` field):
178
+
179
+ ```markdown
180
+ ---
181
+ provenance:
182
+ skill: design-and-plan
183
+ refinedBy: refine-plan
184
+ timestamp: 2026-03-10T08:00:00Z
185
+ baseSha: abc123def456...
186
+ isInteractive: true
187
+ iteration: 2
188
+ ticket_id: '537'
189
+ ticket_ref: '#537'
190
+ branch: 537/feat/example
191
+ commit: 1d2c3b4
192
+ ---
193
+ ```
194
+
195
+ Include `isInteractive` only if it was present in `{input-provenance}`. Include `baseSha` only if available. Top-level fields follow the script's omit rules.
196
+
197
+ **When `{input-provenance}` is empty:**
198
+
199
+ 1. Use the script's `baseSha`. If the script omitted it, omit it.
200
+ 2. Read the revised plan file at `{revision_output_path}`.
201
+ 3. Construct provenance:
202
+ - `skill`: `unknown`
203
+ - `refinedBy`: `refine-plan`
204
+ - `timestamp`: Script's value
205
+ - `baseSha`: Script's value (omit when absent)
206
+ - `isInteractive`: Always `true`. `refine-plan` is an interactive user-invocable skill: When it stamps a plan without prior provenance, the stamp itself is always produced inside that interactive session.
207
+ - `iteration`: `2`
208
+ 4. Prepend the unified YAML frontmatter and write back:
209
+
210
+ ```markdown
211
+ ---
212
+ provenance:
213
+ skill: unknown
214
+ refinedBy: refine-plan
215
+ timestamp: 2026-03-10T08:00:00Z
216
+ baseSha: abc123def456...
217
+ isInteractive: true
218
+ iteration: 2
219
+ ticket_id: '537'
220
+ ticket_ref: '#537'
221
+ branch: 537/feat/example
222
+ commit: 1d2c3b4
223
+ ---
224
+ ```
225
+
226
+ ### 5. Offer ticket update if approach diverged
227
+
228
+ Compare the revised plan's approach/solution with the source ticket's solution section. If they materially diverge, offer to update the ticket to match the revised plan. If the approaches haven't diverged, skip this step silently.
229
+
230
+ **Material divergence** means a different technical approach (e.g., build-time flag changed to runtime detection) or changed scope boundaries (features added or removed). **Non-divergence** means refined details within the same approach (e.g., different function names, reordered steps).
231
+
232
+ On consent, write the update per [platform-specific write](../_data/ticket-source-resolution.md#platform-specific-write), which resolves the platform and states how a revision confined to the solution section composes.
233
+
234
+ This is a shared-state action; do not update without explicit consent. If the user declines, continue to step 6.
235
+
236
+ <!-- include: ../../_partials/prose-line-breaks.md / -->
237
+
238
+ ### 6. Report completion and present next steps
239
+
240
+ ```
241
+ Plan refined:
242
+ Review: {review_output_path}
243
+ Revised: {revision_output_path}
244
+ ```
245
+
246
+ <HARD-GATE>
247
+ Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The plan was just reviewed. If the review identified significant scope changes or unresolved questions that led to a dramatic revision, the plan may warrant another refinement round; otherwise apply the recommendation rules, with a revision that grew the plan as evidence for rule 2. Use this as recommendation context. Include both `{revision_output_path}` (as the plan path) and `{ticket_source}` in each skill-invoking option line.
248
+ </HARD-GATE>
249
+
250
+ ## Edge cases
251
+
252
+ - **Ticket URL unreachable**: Report error with the URL and suggest verifying access (e.g., `gh auth status` for GitHub URLs).
253
+
254
+ ## Constraints
255
+
256
+ - All codebase exploration is delegated to the subagents -- do not analyze code directly.
257
+ - The user interaction step is conversational -- present questions as formatted text and wait for a free-form response.
258
+ - This skill performs one review-and-revise round. Do not loop or iterate.
259
+ - The original plan file is never modified. All output goes to new artifact files.
260
+
261
+ <!-- include: ../_partials/next-steps-after-plan.md / -->
262
+
263
+ <!-- include: ../_partials/option-format.md / -->
@@ -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.