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,208 @@
1
+ ---
2
+ name: people-report
3
+ description: Generate headcount, attrition, diversity, or org health reports from employee data. Use when pulling a headcount snapshot, analyzing turnover trends, preparing diversity metrics, or assessing span of control and flight risk.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # People report
8
+
9
+ Generate HR analytics reports from employee data provided as CSV paste or file path.
10
+
11
+ **Announce at start:**
12
+
13
+ - With `--report-type`: "Using people-report to generate a {report type} report."
14
+ - Without `--report-type`: "Using people-report to generate an HR analytics report."
15
+
16
+ ## Arguments
17
+
18
+ - `--report-type` (optional): Comma-separated list of report types to generate. Valid values: `headcount`, `attrition`, `diversity`, `org-health`. When omitted, prompt the user interactively.
19
+
20
+ ## Report types
21
+
22
+ - **Headcount:** Current org snapshot (by team, location, level, tenure)
23
+ - **Attrition:** Turnover analysis (voluntary/involuntary, by team, trends over time)
24
+ - **Diversity:** Representation metrics (by level, team, pipeline, promotion rates)
25
+ - **Org health:** Span of control, management layers, team sizes, flight risk indicators
26
+
27
+ ## Process
28
+
29
+ ### 1. Select report type
30
+
31
+ If `--report-type` is provided, use the specified types. Skip the prompt.
32
+
33
+ If `--report-type` is omitted, present the four report types and ask the user to choose one or more. The report that the user wants is a taste call, so the options do not have strength markers:
34
+
35
+ > ---
36
+ >
37
+ > **Action items**
38
+ >
39
+ > Which report type(s) would you like? Select one or more.
40
+ >
41
+ > 1. Headcount: Org snapshot by team, location, level, tenure
42
+ > 2. Attrition: Turnover analysis by team, trends
43
+ > 3. Diversity: Representation metrics by level, team, pipeline
44
+ > 4. Org health: Span of control, layers, team sizes, flight risk
45
+
46
+ <!-- include: ../_partials/action-items.md / -->
47
+
48
+ ### 2. Collect data
49
+
50
+ Ask the user to provide employee data:
51
+
52
+ > Paste your employee data below, or provide a file path and I'll read it.
53
+
54
+ Accept CSV, TSV, or any tabular format. If the user provides a file path, read it using the available file-read tool.
55
+
56
+ ### 3. Infer columns
57
+
58
+ Examine the column headers and infer their meaning. Map each column to a recognized field based on common naming patterns (e.g., `Dept`, `Department`, `Team`, `Business Unit` all map to the department/team concept).
59
+
60
+ **If any column mapping is ambiguous**, confirm with the user before proceeding. One item per ambiguous column, so that the user can resolve them all in a single reply:
61
+
62
+ > Two of your columns do not have an unambiguous mapping.
63
+ >
64
+ > ---
65
+ >
66
+ > **Action items**
67
+ >
68
+ > **Q1:** `DoT`: Is this date of termination or date of transfer? πŸ€”
69
+ >
70
+ > **Q2:** `L`: Is this level or location? πŸ€”
71
+
72
+ Do not guess silently on ambiguous columns.
73
+
74
+ After resolving all columns, confirm the mapping with the user. The mapping itself is prose; only the confirmation is an item:
75
+
76
+ > I found {N} rows and mapped your columns:
77
+ >
78
+ > - `Dept` β†’ department
79
+ > - `Hire Date` β†’ start date
80
+ > - `Emp ID` β†’ employee identifier
81
+ > - ...
82
+ >
83
+ > ---
84
+ >
85
+ > **Action items**
86
+ >
87
+ > Proceed with this column mapping? πŸ‘πŸΌπŸ‘ŽπŸΌ
88
+
89
+ Proceed only after the user confirms.
90
+
91
+ ### 4. Validate minimum fields
92
+
93
+ The minimum required fields are:
94
+
95
+ - **Employee identifier** (name, ID, or email)
96
+ - **Department/team** (department, team, business unit, or org)
97
+
98
+ If the dataset contains column headers but zero data rows, stop and tell the user: "Your data contains headers but does not contain any employee records."
99
+
100
+ If either minimum field is missing, stop and tell the user:
101
+
102
+ > I need at least an employee identifier (name, ID, or email) and a department/team column to generate any report. Your data appears to be missing: {missing fields}.
103
+
104
+ ### 5. Assess field coverage per report type
105
+
106
+ For each requested report type, check which analyses are possible given the available fields. If a report type cannot be fully produced, note the limitations and proceed with what is available.
107
+
108
+ #### Headcount
109
+
110
+ | Analysis | Required fields |
111
+ | ------------------ | ------------------------------------------- |
112
+ | By department/team | department |
113
+ | By location | location (city, office, region, or country) |
114
+ | By level | level, grade, or band |
115
+ | By tenure | start date or hire date |
116
+
117
+ #### Attrition
118
+
119
+ | Analysis | Required fields |
120
+ | ------------------------ | ---------------------------------------- |
121
+ | Overall attrition rate | start date, end date or termination date |
122
+ | Voluntary vs involuntary | termination reason or termination type |
123
+ | By department | department + dates |
124
+ | Trend over time | dates with enough historical range |
125
+ | Regrettable attrition | performance rating or termination reason |
126
+
127
+ #### Diversity
128
+
129
+ | Analysis | Required fields |
130
+ | ------------------------ | ----------------------------------------------------- |
131
+ | Representation by group | demographic fields (gender, ethnicity, age) |
132
+ | By level | demographics + level |
133
+ | By team | demographics + department |
134
+ | Promotion rates by group | demographics + promotion date or level change history |
135
+ | Pay equity | demographics + compensation |
136
+
137
+ #### Org health
138
+
139
+ | Analysis | Required fields |
140
+ | ----------------- | ----------------------------------------------------------------------------------- |
141
+ | Span of control | manager field (manager name, manager ID, or reports-to) |
142
+ | Management layers | manager field (to build hierarchy) |
143
+ | Team sizes | department + manager |
144
+ | Flight risk | tenure, performance, compensation, recent promotion (more fields = stronger signal) |
145
+
146
+ After assessing coverage, inform the user what will and won't be included:
147
+
148
+ - **Available analyses:** Headcount by department, by level, by tenure
149
+ - **Not available (missing fields):** Headcount by location; add a `location` column to enable this
150
+
151
+ ### 6. Analyze and generate report
152
+
153
+ For each requested report type, compute the relevant metrics from the available data.
154
+
155
+ **Statistical approach:**
156
+
157
+ 1. Understand the underlying business question addressed by the report type
158
+ 2. Compute counts, rates, distributions, and trends as appropriate
159
+ 3. Flag outliers and notable patterns
160
+ 4. Provide context: A 15% attrition rate means different things in different industries
161
+
162
+ **Handling limitations:**
163
+
164
+ - When the dataset is small, note statistical limitations (e.g., "with only 12 employees in Engineering, percentage breakdowns may not be meaningful")
165
+ - When date ranges are short, note that trend analysis is limited
166
+ - When fields are sparse (many null values), note the completeness rate
167
+
168
+ ### 7. Present output
169
+
170
+ Use the following template for each report type. If multiple report types are requested, use a top-level `# People report ({Date})` header with each type as a `##` section beneath it. For a single report type, use the `##` header directly.
171
+
172
+ ```markdown
173
+ ## People report: {Type} ({Date})
174
+
175
+ ### Executive summary
176
+
177
+ {2-3 key takeaways in plain language}
178
+
179
+ ### Key metrics
180
+
181
+ | Metric | Value | Trend |
182
+ | -------- | ------- | -------------- |
183
+ | {metric} | {value} | {trend or n/a} |
184
+
185
+ ### Detailed analysis
186
+
187
+ {Tables, breakdowns, and narrative. Group by the most relevant dimension for the report type.}
188
+
189
+ ### Recommendations
190
+
191
+ - {Data-driven recommendation}
192
+ - {Data-driven recommendation}
193
+
194
+ ### Methodology
195
+
196
+ - **Data source:** {description of what was provided}
197
+ - **Record count:** {N} employees
198
+ - **Date range:** {range if applicable}
199
+ - **Limitations:** {missing fields, small sample sizes, sparse data}
200
+ ```
201
+
202
+ ## Key principles
203
+
204
+ - **Adaptive, not rigid**: Work with whatever data is available; never refuse to run because of missing optional fields
205
+ - **Confirm ambiguity**: When column mappings are unclear, ask rather than assume
206
+ - **Context over numbers**: Raw metrics without interpretation are not useful; always explain what the numbers mean
207
+ - **Note limitations**: Be transparent about what the data can and cannot support
208
+ - **No external calls**: All analysis is performed on user-provided data; the skill does not integrate with any HRIS or messaging system
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: plan
3
+ description: Create an implementation plan from a ticket or task description
4
+ user-invocable: true
5
+ dependencies:
6
+ skills:
7
+ - testing-conventions
8
+ ---
9
+
10
+ # Plan
11
+
12
+ Create an implementation plan from a ticket or task. `plan` is the standalone plan-phase entry point: Given a good ticket, it produces the same implementation plan that `design-and-plan` produces with its design phase skipped. For interactive design exploration and ticket refinement before planning, use `design-and-plan`, which runs this same plan phase after its design phase.
13
+
14
+ ## Arguments
15
+
16
+ - Task source (required): Issue URL, shorthand reference (`#99`, `issue 99`), file path, or description of what to build
17
+
18
+ ## Resolve the task source
19
+
20
+ Resolve the task source using the [ticket source resolution](../_data/ticket-source-resolution.md) table, then read the resolved ticket or description and plan against it. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), and continue: A blocker does not stop planning. Then check the branch per [branch currency](../_data/branch-currency.md), reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names. `plan` does not run the staleness check or interactive design Q&A; that ceremony belongs to `design-and-plan`. The one exception is the project's declared stage: Read `project_maturity`, `project_sensitivity`, and `project_audience` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, treat them as the premises of every security, availability, and infrastructure decision per [project stage](../_data/project-stage.md), and ask for each undeclared value at the plan checkpoint, adding a task that declares each answered value. When the source is a free-form description rather than a ticket, plan directly from the description.
21
+
22
+ When the resolved source is a local artifact, read its `provenance.skill`: `design-and-plan` means an interactive design phase ran; another skill means the ticket was authored without one. Remote issues and free-form descriptions do not have provenance.
23
+
24
+ ## Output format
25
+
26
+ The plan begins with YAML frontmatter conforming to the canonical schema; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter) and the [plan provenance](../_data/artifact-conventions.md#plan-provenance) extension; field-resolution steps are in the [Frontmatter resolution](#frontmatter-resolution) section below. `provenance.model` is omitted: The plan is produced in an interactive, user-invoked session (the user supplies and vets the source ticket and approves the next step).
27
+
28
+ The body following the frontmatter uses the shared implementation-plan template, the same one inlined by `design-and-plan` Phase 4, so both skills emit an identical plan:
29
+
30
+ **Spike mode.** If the task is a spike, use the spike plan template in [spike conventions](../_data/spike-conventions.md) in place of the template below.
31
+
32
+ <!-- include: ../_partials/plan-template.md / -->
33
+
34
+ ## Guidance
35
+
36
+ - Focus on clarity and actionability
37
+ - Include concrete steps, not vague goals
38
+ - Call out risks and unknowns explicitly
39
+ - When comparing approaches, rank options per [design priorities](../_data/design-priorities.md)
40
+
41
+ ## Sweep for completeness
42
+
43
+ <!-- include: ../_partials/ticket-and-plan-completeness.md / -->
44
+
45
+ ## Saving
46
+
47
+ Resolve artifact directory based on context.
48
+
49
+ ### Frontmatter resolution
50
+
51
+ The artifact frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
52
+
53
+ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill plan --interactive true` via Bash. Prepend the output verbatim to the artifact body.
54
+
55
+ ### Ticket context
56
+
57
+ 1. 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. If the manifest does not contain a ticket ID, auto-generate: `{YYYYMMDD}-{4 random hex}`.
58
+ 2. Save as ticket-level artifact: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/{timestamp}_{slug}_plan.md`
59
+ 3. Slug per [artifact conventions](../_data/artifact-conventions.md#naming-conventions).
60
+
61
+ Follow [artifact conventions](../_data/artifact-conventions.md).
62
+
63
+ `mkdir -p` the target directory before writing.
64
+
65
+ Artifact type: `plan`. Filename format:
66
+
67
+ ```
68
+ {YYYYMMDD-HHMMSSZ}_{slug}_plan.md
69
+ ```
70
+
71
+ Example: `20260223-143000Z_migrate-auth-to-oauth2_plan.md`
72
+
73
+ ## Completion
74
+
75
+ Report the file path when done.
76
+
77
+ ```
78
+ Plan saved: {plan_path}
79
+ ```
80
+
81
+ <HARD-GATE>
82
+ Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. For recommendation context, supply the source's design provenance from the resolve step; `plan` does not add an interactive design phase of its own. Include both `{plan_path}` and `{ticket_source}` in each skill-invoking option line; omit the ticket path when the source was a free-form description rather than a ticket.
83
+ </HARD-GATE>
84
+
85
+ <!-- include: ../_partials/next-steps-after-plan.md / -->
86
+
87
+ <!-- include: ../_partials/option-format.md / -->
@@ -0,0 +1,178 @@
1
+ ---
2
+ name: prepare-prototype-brief
3
+ description: Compose the shared brief and the lens sections for a round of competing prototypes, check the brief against the rules that builders over-apply, dispatch one builder per lens, and once the round is judged, take the developer through a decision on every prototype idea. Use when a ticket calls for two or more prototypes of one idea built in parallel, or when the developer has judged such a round.
4
+ user-invocable: true
5
+ supported-harnesses: [claude]
6
+ ---
7
+
8
+ # Prepare prototype brief
9
+
10
+ Write the brief that a round of prototype builders receives, from the idea, the settled intent, and the lenses that the developer supplies. Every builder reads the brief and follows its words literally: A criterion written into a section's instruction becomes a refrain in every entry, a request to convince becomes a sales pitch, "show the view" becomes a paragraph about the view, and "a large clock" becomes a digital readout. Apply the rules below yourself, so that the developer states the ask and never has to check their own wording.
11
+
12
+ The round's artifacts follow {skill:index-prototypes}: each prototype at `{set_dir}/{slug}-v{n}.html` with its id, `{number}.{version}`, on the page, one index page with screenshots and verdicts, and a comparison afterwards. Once the developer has judged the round, an `idea-decisions` artifact records the decision on each of the round's ideas.
13
+
14
+ ## Inputs
15
+
16
+ - **The ticket**, which states the idea and whatever intent is already settled.
17
+ - **The developer's ask**, in their own words: what the prototypes are for, what is decided, what is out of scope, and what a reviewer will look for. Take it as given, and never quote it into the brief unedited: Its vocabulary is the developer's, and the rules below decide what the builders read.
18
+ - **The lenses**: one name and one paragraph each. When the ask does not supply them, propose three to five that diverge on purpose (the primary user, an operator, a hard constraint, a precedent, an audience) and ask.
19
+ - **The deliverable kind**: a self-contained HTML page unless the ask says otherwise.
20
+ - **The write allowance**: the files that a builder may write. By default, the output file alone. When the ask allows more, such as a directory in the repository when the repository keeps its prototypes, or a dependency to install, take the allowance from the ask and state it in the brief.
21
+
22
+ ## Rules of composition
23
+
24
+ Each rule names the failure that it prevents, because a reviewer sees the failure first.
25
+
26
+ ### Ask for a demonstration, not a pitch
27
+
28
+ Do not ask a builder to pitch, sell, convince, persuade, or argue. Ask for the demonstration that makes the case: a running mechanism, a scene played through the interface, a before and after. When the developer wants to be convinced, ask for the demonstration that would convince them, and cap any prose about purpose at one paragraph that describes what the tool does in one scene. Strike "the visuals must convince" and write what the visuals must do: work, be legible at the distance from which they are viewed, pass the accessibility floors.
29
+
30
+ The failure that this prevents: five builders writing superlatives and refrains in a pitch-man's voice, and a reader who cannot find the work under the sales copy.
31
+
32
+ ### Put every criterion in the judging section
33
+
34
+ Write every evaluation criterion (attention cost, consequence per tap, divergence, fidelity to the rules) once, in a closing section titled "How this round is judged," in the reviewer's voice. Do not place a criterion inside a section's instruction.
35
+
36
+ The failure that this prevents: a builder told that "the measure of each entry is cost per consequence" prices every entry in prose and explains the pricing.
37
+
38
+ ### Require rendered states, not descriptions
39
+
40
+ When a section would "show" a view, state, or scene, require rendered states of the prototype's own interface, each with a one-line caption, and state that prose standing in for a screen is a defect. Write a scene walkthrough as a sequence of rendered states. Treat a step that the prototype cannot render as a step that it has not built.
41
+
42
+ Allow tables and require the demo: A catalogue may be a table, and every row must be reachable from the running demo, so that tapping the thing in the demo shows the row's facts.
43
+
44
+ ### Name the information, not the instrument
45
+
46
+ A builder draws every noun in the brief. Say what the viewer must be able to learn and at what precision, and let the builder choose the instrument: "the hour, legible across the table, to the precision that a character would have" rather than "a large clock." For an audience-facing or in-world view, state what the audience may know and what it may never see, and state that any readout more precise than the fiction allows is a defect.
47
+
48
+ The same holds for the verbs `state`, `say`, `tell`, and `explain`. A requirement that the page states something before the first field is met most cheaply by a sentence under the heading. Write what the viewer must be able to learn and at what moment, such as "which scopes a preset grants, visible before a token is created", and let the builder choose whether a label, a column, or a control shows it.
49
+
50
+ ### Describe only what the audience sees
51
+
52
+ In an instruction for an audience-facing view, describe what the audience sees. When information is intended to be unknown to the audience, do not include or reference it in audience-facing material.
53
+
54
+ The failure that this prevents: an element on the audience view whose job is to point at or stand for the withheld information.
55
+
56
+ ### Keep the brief out of the page
57
+
58
+ Nothing in the brief is product copy. State in the brief that a builder never quotes the brief, the scenes, the lens, or an audit into the page, and that the text on the product surface follows {rulebook:ui-copy-conventions}.
59
+
60
+ The failure that this prevents: the lens paragraph reproduced as helper text under a field, and an intro paragraph under every page heading.
61
+
62
+ ### Require a salience order
63
+
64
+ Require a salience order in every working view: the current state in one place, the next thing to happen more prominent than the rest, and every action visibly an action. Name {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} as the floor, and state that usability outranks restraint. Require that a status repeated on every row be a mark, a column, or a style, not a sentence.
65
+
66
+ The failure that this prevents: a page in one colour, in which the operator hunts for the control, and "Hidden from the players." written out on every hidden row.
67
+
68
+ ### Write the brief in plain speech
69
+
70
+ The brief is documentation, so apply the plain-speech rules to it. Test each sentence by asking whether a builder would reproduce the phrase: A builder reproduces a figure as a figure, and a loaded word (cost, price, free, cheap) as a theme. Write the literal statement.
71
+
72
+ ### List the settled intent as final
73
+
74
+ List the decisions already taken under "Settled intent," and state that they are not to be reconsidered. A builder that spends its budget re-deciding the platform or the scope delivers less of the thing that the round exists to compare.
75
+
76
+ ## Structure of the brief
77
+
78
+ Write the brief in this order, with these headings:
79
+
80
+ 1. **Context.** The ticket, quoted. The developer's motivating picture, restated in plain speech.
81
+ 2. **Settled intent.** Bullets. Each is a decision, with its reason when the reason constrains the design.
82
+ 3. **Deliverable.** The file and its path per {skill:index-prototypes}; the constraints (self-contained, opens from `file://`, inline CSS and JavaScript, no framework, readable with JavaScript off, phone width); the mechanism that must run; the demo control that plays the written scene; a full-screen mode when the product has an audience view. The demo chrome (the demo control, scene captions, the lens note, the data-model note, the API list) is in a band visibly distinct from the product surface, and every part of it is inside an element that has the `data-demo` attribute. The band's first line is the id and the title from the dispatch block, `{id} {title}`.
83
+ 4. **Sections.** Numbered, each a noun phrase plus what it contains and a length bound. None asks for persuasion; one is the scene, exhibited; one is the data-model note when the product stores data; one is the API list when the product has an API.
84
+ 5. **Quality bar.** Works, legible, accessible, and within the copy rules, with {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} named, the design skill to invoke before markup, and the salience order required.
85
+ 6. **How this round is judged.** The criteria, in the reviewer's voice, with the divergence between lenses named as the point of the round. One criterion is the copy: "Read every string on the product surface as its user opening the page for the tenth time. A string that explains the page, reassures, or repeats the brief, and any copy over the budget in {rulebook:ui-copy-conventions}, is a defect."
86
+ 7. **Rules of engagement.** The write allowance from the inputs. The default: Write the output file and nothing else, modify nothing in the repository, install nothing. When the ask allows more, state what it allows. Then: Publish the prototype and report its artifact URL, a value for each of the set's note labels (listed here), and five lines of distinctive ideas.
87
+
88
+ Then add the lens sections, one per builder, in the developer's words after a plain-speech pass.
89
+
90
+ ## The idea table
91
+
92
+ The idea table lists every distinctive idea of the round, so that each one is kept or let go by the developer's decision rather than by default. The comparison contains it with the Decision column empty, because it is written before any verdict exists.
93
+
94
+ | Column | Contents |
95
+ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
96
+ | # | The row's number, starting at 1 in each comparison |
97
+ | Idea | One line |
98
+ | Source | Every prototype that has the idea, as `{id} {title}`, or `developer` for an idea that the developer states |
99
+ | Answers | The ticket criterion, the settled intent, or the audit finding or requirement in the ticket or the product's design doc that the idea answers; blank when none does |
100
+ | Decision | Empty in the comparison |
101
+
102
+ Take the rows from every builder's five lines of distinctive ideas, the builders of rejected and losing prototypes included, and add a row for a distinctive idea visible in a prototype whose builder did not list it. An idea that two prototypes share is one row that names both. Never invent an entry for the Answers column.
103
+
104
+ A decision is one of four:
105
+
106
+ - **Keep**: The idea goes into the design as it is.
107
+ - **Adapt**: The idea goes into the design changed; the decision states how.
108
+ - **Defer**: The idea waits; the decision states what unblocks it.
109
+ - **Drop**: The idea is let go; the decision states the reason.
110
+
111
+ ## Process
112
+
113
+ ### 1. Resolve the set
114
+
115
+ Resolve the set directory and the scratch directory per {skill:index-prototypes} step 1, and read back any verdicts from an earlier round: They say which slugs are revised (same slug, next version) and which are new. When the developer names a prototype to revise by its number, resolve it to its slug per {skill:index-prototypes} "The set".
116
+
117
+ ### 2. Gather the inputs
118
+
119
+ Take the ticket and the ask. Propose lenses when the ask lacks them. Take the write allowance from the ask, and apply the default when the ask does not state one. Choose a slug per lens and the set's note labels, per {skill:index-prototypes} "The set", before anything is built, and resolve the slugs' ids per the same section, in the order of the lens sections.
120
+
121
+ ### 3. Compose and check the brief
122
+
123
+ Write the brief to `{scratch_dir}/brief.md`. Then check it against each rule above, by search as well as by reading:
124
+
125
+ - The words `pitch`, `sell`, `convince`, `persuade`, `argue`, `compelling`: absent from every instruction to a builder.
126
+ - Every criterion: in "How this round is judged" and nowhere else.
127
+ - Every `show`, `display`, `present`: followed by a requirement to render.
128
+ - Every instrument noun in an audience-facing instruction (clock, gauge, meter, counter, bar): replaced by the information and its precision.
129
+ - Every `do not know`, `mystery`, `unknown to`, `without knowing` in an audience-facing instruction: rewritten as what the audience sees, without the withheld information.
130
+ - `cost`, `price`, `free`, `cheap`, `budget`: absent, or present once in the judging section.
131
+ - Every `state`, `say`, `tell`, `explain` in a requirement: rewritten as what the viewer can learn and at what moment.
132
+ - Salience order, the accessibility floor, and the copy rules: named in the quality bar, and the copy rules named again in "How this round is judged".
133
+ - The `data-demo` band: required in the deliverable.
134
+ - The write allowance: stated in the rules of engagement.
135
+ - The note labels: listed in the rules of engagement.
136
+
137
+ Report what the check changed, in one line per rule that fired.
138
+
139
+ ### 4. Checkpoint
140
+
141
+ Save the brief with {skill:save-artifact} as a ticket-level `brief` artifact, and show it to the developer. Do not post it to the ticket without their approval: Posting is remote state. Ask in one action-items block: approve the brief, and post it as a ticket comment or not.
142
+
143
+ <!-- include: ../_partials/action-items.md / -->
144
+
145
+ ### 5. Dispatch the builders
146
+
147
+ Send one {tool:Task} call per lens in one message, `subagent_type: general-purpose`, each with this prompt and nothing else composed into it:
148
+
149
+ ```dispatch
150
+ brief: {path to the saved brief}
151
+ lens: {lens name}
152
+ slug: {slug}
153
+ version: {n}
154
+ id: {number}.{n}
155
+ output: {set_dir}/{slug}-v{n}.html
156
+ ```
157
+
158
+ followed by:
159
+
160
+ > Read the brief in full and build the prototype for the lens named above. Write only the files that the brief's rules of engagement allow. Put the id above and the prototype's title on the first line of the page's `data-demo` band. Invoke the design skill that the brief names before writing markup. Publish the output with the Artifact tool. When done, reply with the artifact URL, a short title, the lens, the inputs that you drew on, a one-sentence description, one line per note label in the brief as `{label}: {value}`, and five lines of the system's distinctive ideas. Nothing else.
161
+
162
+ Dispatch a builder once more with the same block when it returns without the file, with a file that does not open, or without an artifact URL. Report a second failure in the summary and leave the lens out of the round.
163
+
164
+ ### 6. Index and compare
165
+
166
+ Continue with {skill:index-prototypes} steps 3 to 7 and the verdict check of step 8, for the screenshots, the registrations, the set's summary, and the index page. In step 3, list each prototype's product copy per its "List the product copy". Register each prototype with `--number` from its resolved id, so that the number on the page and the number in the manifest agree whatever the order in which the builders returned. Take each registration's URL, title, lens, inputs, description, and notes from the builder's reply. Then write the comparison, naming each prototype as `{id} {title}`: the points on which the prototypes agree, the points on which they diverge, the [idea table](#the-idea-table), a "Product copy" section, and the decisions that the round leaves open. The "Product copy" section names each prototype as `{id} {title}` and lists its strings from the probe. For a prototype without a `data-demo` band, add a one-line note directly under its name, before the list, that the listing includes the demo chrome. Save it with {skill:save-artifact} as a ticket-level `comparison` artifact. Give the developer the index link, the comparison path, and one line per prototype as `{id} {title}`, and nothing else.
167
+
168
+ ### 7. Decide the ideas
169
+
170
+ Run this step once the developer says that they have judged the round, in this session or a later one. A verdict on a prototype is never a decision on its ideas: Do not drop a row because its prototype lost or was rejected, and do not keep a row because its prototype won, without the developer's answer.
171
+
172
+ 1. Resolve the set directory per {skill:index-prototypes} step 1, and read back the verdicts per its "Read back the verdicts".
173
+ 2. Read the latest `comparison` artifact in the ticket directory. When an `idea-decisions` artifact is newer than it, resume from that artifact and walk only its open rows. When the latest comparison does not contain an idea table, report that the round does not have one and stop.
174
+ 3. Present every row in one action-items block, per the convention included at step 4: its number, idea, source, answers, the verdict of each source prototype by `{id} {title}` (winner, rank, or rejected), and a recommended decision with its reason in a clause. After a revised round, a row matching a row of the previous `idea-decisions` artifact takes that row's decision as its recommendation. A row for which you do not have a basis shows "no recommendation".
175
+ 4. Take the developer's answer by row number: `3 keep`, `5 adapt: {how}`, `7 defer: {what unblocks it}`, `9 drop: {reason}`. An explicit `accept the rest` decides every remaining row that has a recommendation with that recommendation. A row that the answer does not cover, and an adapt, defer, or drop that lacks its how, its condition, or its reason, stays open. When the developer states an idea that none of the rows contains, such as a combination of two prototypes, add it as a row whose source is `developer`. A bare number in an answer names a row; a prototype in a stated idea is named by its number with its title or slug. When an answer leaves unclear whether a number names a row or a prototype, ask before deciding the row.
176
+ 5. Present the open rows again, until none remain.
177
+
178
+ Save the table with {skill:save-artifact} as a ticket-level `idea-decisions` artifact that reuses the comparison's slug: the table with every decision filled, the index URL, and the comparison's path. When the developer stops before every row is answered, save it with `open` as each unanswered row's decision; the end vision does not cite an `idea-decisions` artifact that contains an open row. Give the developer the artifact's path.
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: pull-from-backlog
3
+ description: Recommend the next ticket to pull from a GitHub backlog, with the backlog's picture, its warnings, and a ranked menu of candidates with each one's reasons
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Pull from backlog
8
+
9
+ Recommend the next ticket to work on. A bundled helper reads GitHub, the repository's branches, and groom-backlog's ledger, and reports the picture, the warnings, and the ranked candidates. You present them, offer the grooms that the backlog needs, record the pick, and assign the user on consent.
10
+
11
+ The skill is re-entrant: Everything it reads is in GitHub and the ledger, so a fresh session and one already in progress produce the same menu. When the user says "merged #N" or "done with #N" after a pick, start again at step 1.
12
+
13
+ **Announce at start:** "Using pull-from-backlog to recommend the next ticket of {repository}."
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description | Default |
18
+ | ------------------- | ---------------------------------------------------------------- | ---------------------- |
19
+ | `--limit <N>` | Offer the top `N` candidates. | 3 |
20
+ | `--now <milestone>` | Take this open milestone as the Now set, over `ticket.pull.now`. | Resolved by the helper |
21
+
22
+ GitHub alone is supported, through `gh`. On any other platform, stop at step 1 and report that the skill does not support it.
23
+
24
+ ## Boundary
25
+
26
+ The skill's one write to GitHub is the assignee, with the user's consent or under `ticket.pull.assignOnPick`. It does not comment on, label, close, or edit any ticket, and its one ledger write is the `pull` record.
27
+
28
+ ## Process
29
+
30
+ Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`. Invoke the helper as:
31
+
32
+ ```bash
33
+ node {harness_home_dir}/skills/pull-from-backlog/pull-from-backlog.mjs {command} {flags}
34
+ ```
35
+
36
+ The ledger is `local/ticket-triage/ledger.jsonl` in the primary worktree, shared with groom-backlog; the helper reports its path. If the sandbox denies a write there, stop, and ask the user to allow that path.
37
+
38
+ ### 1. Preflight
39
+
40
+ 1. Run `gh auth status` and `gh repo view --json nameWithOwner`. If either fails, or the repository is not on GitHub, stop and report why.
41
+ 2. Run the survey, passing only the flags that the invocation names:
42
+
43
+ ```bash
44
+ node {harness_home_dir}/skills/pull-from-backlog/pull-from-backlog.mjs survey --limit {N} --now {milestone}
45
+ ```
46
+
47
+ ### 2. Present the picture and the warnings
48
+
49
+ Present, in this order, and omit a section that is empty rather than reporting a zero:
50
+
51
+ 1. **Now**: the milestone and its due date, with how it was resolved (`now.source`). For `backlog`, say in one line that the repository does not have an open milestone with open eligible issues, so the whole backlog is the Now set. When the milestone is not null and `counts.inNow` is 0, say that it has no eligible open tickets left, and suggest closing it or planning a new one; do not offer to change any ticket's milestone. When `counts.excluded` is not 0, add one line stating how many open tickets have a `ticket.pull.excludeLabels` label and are not offered.
52
+ 2. **Umbrellas**: each as `#N title: completed/total done`.
53
+ 3. **In progress**: each ticket with its branch (`ref`) and the days since its last commit, or its assignees when it does not have a branch. List the user's own (`yours`) first, under their own heading.
54
+ 4. **Blocked**: each blocked Now ticket with its open blockers.
55
+ 5. **Warnings**: one line each. `now-not-found`: the configured milestone is not open. `milestone-past-due`: the milestone and the days overdue. `stale-branch`: the ticket, the branch, and the days since its last commit. `blocked-outside-now`: the Now ticket and its blockers outside Now. `groom-stale`: the last groom's date and age, the open tickets created since it, or that the backlog has never been groomed.
56
+
57
+ ### 3. Present the candidates
58
+
59
+ Render `candidates` as a numbered gradient menu, per [Option format](#option-format), with every candidate's `reasons` as its `βž•` lines and its URL. The candidate ranked first takes the strongest marker. When a candidate has `inNow: false`, say in one line above the menu that Now was exhausted and the menu includes backlog tickets, and append `(outside Now)` to each such candidate's title. The menu is always rendered: Which ticket the user works on next is a preference about their time, which is in the gated class. When `candidates` is empty, say so, name the counts from `counts`, and skip step 4.
60
+
61
+ Close the turn with an action-items block that asks for the pick. When `groomStale.stale`, the block contains, before the pick, an offer to groom the backlog: `{skill:groom-backlog}` without arguments, which assesses every open ticket, applies its recommendations after one confirmation per digest page, and asks nothing per ticket. When the user takes it, run it, then start again at step 1: A groom can change the candidates.
62
+
63
+ ### 4. Record the pick
64
+
65
+ 1. Record it:
66
+
67
+ ```bash
68
+ node {harness_home_dir}/skills/pull-from-backlog/pull-from-backlog.mjs record --ticket {N}
69
+ ```
70
+
71
+ 2. Assign the user. When the survey's `assignOnPick` is `true`, run the command directly; otherwise ask first, with `πŸ‘πŸΌπŸ‘ŽπŸΌ`, and run it only on a clear yes:
72
+
73
+ ```bash
74
+ gh issue edit {N} --add-assignee @me
75
+ ```
76
+
77
+ If the command fails, report `gh`'s message and do not retry. The `pull` record stands: The pick happened, and only the assignment failed.
78
+
79
+ 3. Close with one line: "Start #{N} in its own session."
80
+
81
+ <!-- include: ../_partials/option-format.md / -->
82
+
83
+ <!-- include: ../_partials/action-items.md / -->