codeassembly-guidance 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +984 -0
- package/CHANGELOG.md +240 -0
- package/README.md +45 -99
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +21 -5
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +17 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +206 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
- package/content/guidance/rulebooks/commit-conventions.md +5 -4
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +39 -4
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +98 -98
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +64 -16
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +15 -4
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +22 -12
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +11 -11
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +7 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +98 -0
- package/content/skills/capture-event/SKILL.md +4 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +3 -3
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +28 -10
- package/content/skills/create-pr/SKILL.md +7 -6
- package/content/skills/create-ticket/SKILL.md +64 -23
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
- package/content/skills/design-and-plan/SKILL.md +17 -18
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +27 -23
- package/content/skills/index-prototypes/SKILL.md +86 -31
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +4 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +5 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
- package/content/skills/kb-retrieve-events/SKILL.md +20 -11
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
- package/content/skills/kb-update-events/SKILL.md +10 -7
- package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +2 -2
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +354 -3
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +3 -1
- package/content/skills/streamline-guidance/SKILL.md +11 -16
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +23 -14
- package/content/skills/testing-conventions/SKILL.md +81 -8
- package/content/skills/triage-feedback/SKILL.md +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +12 -12
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/feedback-triage-challenger.md +81 -0
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/lesson-clusterer.md +68 -0
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +21 -17
- package/schemas/preferences.v1.json +50 -7
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -17,7 +17,7 @@ Create an implementation plan from a ticket or task. `plan` is the standalone pl
|
|
|
17
17
|
|
|
18
18
|
## Resolve the task source
|
|
19
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. `plan` does not run the staleness check or interactive design Q&A; that ceremony belongs to `design-and-plan`. When the source is a free-form description rather than a ticket, plan directly from the description.
|
|
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
21
|
|
|
22
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
23
|
|
|
@@ -36,7 +36,7 @@ The body following the frontmatter uses the shared implementation-plan template,
|
|
|
36
36
|
- Focus on clarity and actionability
|
|
37
37
|
- Include concrete steps, not vague goals
|
|
38
38
|
- Call out risks and unknowns explicitly
|
|
39
|
-
- When comparing approaches, rank options per [design priorities](../_data/design-priorities.md)
|
|
39
|
+
- When comparing approaches, rank options per [design priorities](../_data/design-priorities.md), including [who applies the change](../_data/design-priorities.md#who-applies-the-change): A design that needs a person to act on each machine is a defect to raise, not a step to document
|
|
40
40
|
|
|
41
41
|
## Sweep for completeness
|
|
42
42
|
|
|
@@ -1,15 +1,15 @@
|
|
|
1
1
|
---
|
|
2
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,
|
|
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
4
|
user-invocable: true
|
|
5
5
|
supported-harnesses: [claude]
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Prepare prototype brief
|
|
9
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
|
|
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
11
|
|
|
12
|
-
The round's artifacts follow {skill:index-prototypes}: each prototype at `{set_dir}/{slug}-v{n}.html`, one index page with screenshots and verdicts, and a comparison afterwards.
|
|
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
13
|
|
|
14
14
|
## Inputs
|
|
15
15
|
|
|
@@ -21,7 +21,7 @@ The round's artifacts follow {skill:index-prototypes}: each prototype at `{set_d
|
|
|
21
21
|
|
|
22
22
|
## Rules of composition
|
|
23
23
|
|
|
24
|
-
Each rule names the failure that it prevents, because
|
|
24
|
+
Each rule names the failure that it prevents, because a reviewer sees the failure first.
|
|
25
25
|
|
|
26
26
|
### Ask for a demonstration, not a pitch
|
|
27
27
|
|
|
@@ -45,9 +45,23 @@ Allow tables and require the demo: A catalogue may be a table, and every row mus
|
|
|
45
45
|
|
|
46
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
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
|
+
|
|
48
62
|
### Require a salience order
|
|
49
63
|
|
|
50
|
-
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} 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.
|
|
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.
|
|
51
65
|
|
|
52
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.
|
|
53
67
|
|
|
@@ -65,23 +79,44 @@ Write the brief in this order, with these headings:
|
|
|
65
79
|
|
|
66
80
|
1. **Context.** The ticket, quoted. The developer's motivating picture, restated in plain speech.
|
|
67
81
|
2. **Settled intent.** Bullets. Each is a decision, with its reason when the reason constrains the design.
|
|
68
|
-
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.
|
|
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}`.
|
|
69
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.
|
|
70
|
-
5. **Quality bar.** Works, legible, accessible, with the design skill to invoke before markup and the salience order required.
|
|
71
|
-
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.
|
|
72
|
-
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 and five lines of distinctive ideas.
|
|
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.
|
|
73
87
|
|
|
74
88
|
Then add the lens sections, one per builder, in the developer's words after a plain-speech pass.
|
|
75
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
|
+
|
|
76
111
|
## Process
|
|
77
112
|
|
|
78
113
|
### 1. Resolve the set
|
|
79
114
|
|
|
80
|
-
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.
|
|
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".
|
|
81
116
|
|
|
82
117
|
### 2. Gather the inputs
|
|
83
118
|
|
|
84
|
-
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 before anything is built.
|
|
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.
|
|
85
120
|
|
|
86
121
|
### 3. Compose and check the brief
|
|
87
122
|
|
|
@@ -91,9 +126,13 @@ Write the brief to `{scratch_dir}/brief.md`. Then check it against each rule abo
|
|
|
91
126
|
- Every criterion: in "How this round is judged" and nowhere else.
|
|
92
127
|
- Every `show`, `display`, `present`: followed by a requirement to render.
|
|
93
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.
|
|
94
130
|
- `cost`, `price`, `free`, `cheap`, `budget`: absent, or present once in the judging section.
|
|
95
|
-
-
|
|
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.
|
|
96
134
|
- The write allowance: stated in the rules of engagement.
|
|
135
|
+
- The note labels: listed in the rules of engagement.
|
|
97
136
|
|
|
98
137
|
Report what the check changed, in one line per rule that fired.
|
|
99
138
|
|
|
@@ -112,15 +151,28 @@ brief: {path to the saved brief}
|
|
|
112
151
|
lens: {lens name}
|
|
113
152
|
slug: {slug}
|
|
114
153
|
version: {n}
|
|
154
|
+
id: {number}.{n}
|
|
115
155
|
output: {set_dir}/{slug}-v{n}.html
|
|
116
156
|
```
|
|
117
157
|
|
|
118
158
|
followed by:
|
|
119
159
|
|
|
120
|
-
> 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. 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, and five lines of the system's distinctive ideas. Nothing else.
|
|
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.
|
|
121
161
|
|
|
122
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.
|
|
123
163
|
|
|
124
164
|
### 6. Index and compare
|
|
125
165
|
|
|
126
|
-
Continue with {skill:index-prototypes} steps 3 to
|
|
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.
|
|
@@ -8,7 +8,7 @@ user-invocable: true
|
|
|
8
8
|
|
|
9
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
10
|
|
|
11
|
-
The skill is re-entrant: Everything it reads is in GitHub and the ledger, so a fresh session and
|
|
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
12
|
|
|
13
13
|
**Announce at start:** "Using pull-from-backlog to recommend the next ticket of {repository}."
|
|
14
14
|
|
|
@@ -48,7 +48,7 @@ The ledger is `local/ticket-triage/ledger.jsonl` in the primary worktree, shared
|
|
|
48
48
|
|
|
49
49
|
Present, in this order, and omit a section that is empty rather than reporting a zero:
|
|
50
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
|
|
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
52
|
2. **Umbrellas**: each as `#N title: completed/total done`.
|
|
53
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
54
|
4. **Blocked**: each blocked Now ticket with its open blockers.
|
|
@@ -74,7 +74,7 @@ Close the turn with an action-items block that asks for the pick. When `groomSta
|
|
|
74
74
|
gh issue edit {N} --add-assignee @me
|
|
75
75
|
```
|
|
76
76
|
|
|
77
|
-
If the command fails, report `gh`'s message and do not retry. The `pull` record stands: The pick happened, and only the
|
|
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
78
|
|
|
79
79
|
3. Close with one line: "Start #{N} in its own session."
|
|
80
80
|
|