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.
- package/.meta/changelog.json +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +70 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +6 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +214 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +180 -0
- package/content/skills/_data/title-templates.md +632 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +85 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +148 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +71 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +317 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- 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 / -->
|