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,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: assess-usability
|
|
3
|
+
description: Assess a product's usability through three to five lenses, one subagent per lens walking its use cases in a browser or a shell, and merge their reports into a ranked findings artifact that a triage pass can dispose of. Use when asked to evaluate a site's, an app's, or a CLI's usability, or to find the bugs, flaws, and obvious gaps that a user would meet.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
supported-harnesses: [claude]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Assess usability
|
|
9
|
+
|
|
10
|
+
Find where a product would lead its users to conclude that it is broken or unfinished. Each lens is a {subagent:usability-assessor} that walks its use cases in a browser or, for a command-line product, in a shell, without seeing any other lens's report. You prepare the targets, write the brief that every lens reads, dispatch the lenses one at a time, and merge their reports into one findings artifact.
|
|
11
|
+
|
|
12
|
+
The skill writes nothing remote: It does not create a ticket, post a comment, or edit an issue. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
|
|
13
|
+
|
|
14
|
+
## Inputs
|
|
15
|
+
|
|
16
|
+
- **The medium**: `browser` (default) or `cli`, as the developer names it.
|
|
17
|
+
- **The targets**: under `browser`, the URLs or local stacks to assess; under `cli`, the package whose binary is assessed.
|
|
18
|
+
- **The roles**: the kinds of user that the product serves, such as a signed-out visitor, a member, and an administrator. When the developer does not name them, derive them under `browser` from the repository's routes and its auth model, and under `cli` from the CLI's commands and documented workflows. Under `cli`, ask at the checkpoint for a routine-use role, such as the user who runs one command daily, which the command list does not show.
|
|
19
|
+
- **The ticket**, optional. Without one in session, `{skill:save-artifact}` saves the artifacts under the ticket ID that it generates.
|
|
20
|
+
|
|
21
|
+
Read the declared stage of the project under assessment from `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`. When `project_sensitivity` is `personal` or `confidential`, every lens uses seeded or test data only, and no target that holds real users' data is used for anything but reading public pages.
|
|
22
|
+
|
|
23
|
+
## Process
|
|
24
|
+
|
|
25
|
+
### 1. Prepare the targets
|
|
26
|
+
|
|
27
|
+
Resolve the ticket directory per {skill:save-artifact}, and create `{ticket_dir}/usability/`. Then prepare the targets for the medium.
|
|
28
|
+
|
|
29
|
+
Under `browser`:
|
|
30
|
+
|
|
31
|
+
- **The browser.** The lenses share one browser that the Playwright MCP server drives, so they run one after another. Confirm that the browser responds before anything else; when it does not, ask the developer for one and stop.
|
|
32
|
+
- **The local stack.** When a target is local, confirm that it runs, and start it by the repository's own scripts when it does not. Use a development build that connects only to the local stack, never a script that connects to a hosted service.
|
|
33
|
+
- **Sign-in state.** For each hosted target, find out whether the browser profile is signed in on it. A lens opens its own browser context for a signed-out view; nothing signs the profile out.
|
|
34
|
+
|
|
35
|
+
Under `cli`:
|
|
36
|
+
|
|
37
|
+
- **The build.** Build the package by the repository's own build script, never a shim that runs source, as a dev server is excluded under `browser`.
|
|
38
|
+
- **The invocation.** Choose how a lens runs the binary: the built binary by absolute path by default, or the packed package installed into each fixture when the product's documentation describes installation as how it is used.
|
|
39
|
+
- **The readiness check.** Create a scratch fixture as step 2 describes, and confirm that `<bin> --version` exits 0 from it. When the build or the check fails, report the failure to the developer and stop.
|
|
40
|
+
- **Network and credential state.** For each host that the product reaches, find out whether this machine can reach it and whether a credential is present. A lens never uses the developer's credentials; a host that it cannot reach is recorded as `not exercised`.
|
|
41
|
+
|
|
42
|
+
### 2. Write the brief
|
|
43
|
+
|
|
44
|
+
Compose the brief with these sections. Each names its `browser` form, then its `cli` form when the two differ.
|
|
45
|
+
|
|
46
|
+
1. **Product.** What the product is and whom it serves, in two or three sentences.
|
|
47
|
+
2. **Targets.** One row per target: its URL, its write rule, its sign-in state, and the method by which a lens grants itself a role or an approval there. A target is read-only unless it is on `localhost` or the developer names it as disposable, per {rulebook:shared-data-conventions}. Writes go to a writable target, with `@example.com` accounts that the lens creates. Under `cli`, one row per target: the binary and its invocation, its write rule, its network and credential state, and what a lens may install. The checkout and every remote source are read-only; each lens's fixture is writable, and its git author is the only identity.
|
|
48
|
+
3. **Lenses.** Three to five: one per role, and one for styling and access. Give each a unique ID prefix (two roles can share an initial), its targets, and its minimum use cases, each with its route. The styling-and-access lens covers light and dark mode, a 1440×900 and a 390×844 viewport, and keyboard-only use of the other lenses' core flows, against the floors in {rulebook:accessibility-conventions}. It runs last, so that it can reach every screen that the earlier lenses found. Under `cli`, each use case has its command lines, and the last lens is output-and-access: the CLI's `--style` or equivalent option, `NO_COLOR`, TTY versus pipe when the developer opted in to `script` and pipe output otherwise, 80 columns, and help and error text, of the other lenses' core flows. Each lens also has its fixture: Create it now with `mktemp -d "${TMPDIR:-/tmp}/usability-{lens slug}.XXXXXX"`, outside the checkout and the artifact directory, as a git repository with `user.name` `Usability Assessor` and `user.email` `assessor@example.com` set locally and one empty initial commit, and name its absolute path in the lens's row.
|
|
49
|
+
4. **Exclusions.** Routes, surfaces, and products out of scope, such as a developer-only page or a browser extension; under `cli`, commands, flags, and modes, such as one that runs source.
|
|
50
|
+
5. **Settled.** The decisions above, stated as final, so that a lens does not re-decide them. State the medium as `medium: browser` or `medium: cli`. Under `cli`, also state the pseudo-terminal rule: A lens measures line lengths in captured output rather than observing a terminal, and runs `script` only when the developer opts in at the checkpoint.
|
|
51
|
+
|
|
52
|
+
### 3. Checkpoint
|
|
53
|
+
|
|
54
|
+
Save the brief with {skill:save-artifact} as a ticket-level `usability-brief` artifact, and show it to the developer. Ask in one action-items block for approval of the brief, and for any target that the developer wants to mark disposable. Under `cli`, also ask whether a lens may run `script` for pseudo-terminal observation, and record the answer under **Settled**. Do not dispatch any lens before approval.
|
|
55
|
+
|
|
56
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
57
|
+
|
|
58
|
+
### 4. Dispatch the lenses
|
|
59
|
+
|
|
60
|
+
Dispatch one lens at a time, under either medium, in the order of the brief's lens table, and wait for each to return before dispatching the next. Create `{ticket_dir}/usability/{lens slug}/` before dispatching each lens. Send one {tool:Task} call, `subagent_type: usability-assessor`, with this block and nothing else composed into it:
|
|
61
|
+
|
|
62
|
+
```dispatch
|
|
63
|
+
brief: {path to the saved brief}
|
|
64
|
+
lens: {lens name}
|
|
65
|
+
output: {ticket_dir}/usability/{lens slug}/
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
Never pass one lens's report, or anything learned from it, to a later lens: Each lens's value is its independent view, and the synthesis removes the duplicates.
|
|
69
|
+
|
|
70
|
+
**A reply that lacks the `Phase: usability-assessment` line is a lens stopped by its turn limit.** Resume that lens once, asking only for its report; on Claude Code, send it a message with `SendMessage`, addressed by the agent ID that its dispatch returned. When the resumed lens still does not return a report, do not dispatch it again: Record the lens as not reported, and continue with the next.
|
|
71
|
+
|
|
72
|
+
Save each report as `{ticket_dir}/usability/{lens slug}-report.md` as soon as it returns.
|
|
73
|
+
|
|
74
|
+
### 5. Synthesize
|
|
75
|
+
|
|
76
|
+
Merge the reports into one findings document:
|
|
77
|
+
|
|
78
|
+
- **Ranked findings.** Merge findings that describe one problem across lenses, keeping every source ID and every evidence path. Rank by effect (blocks, slows, confuses, polish), then by reach: the number of distinct use cases, across all lenses, in whose flow the finding was reported. A merged finding takes the strongest effect of its sources and states `Reproduced: yes` when any source does.
|
|
79
|
+
- **Use cases.** Each lens's use cases with their outcomes.
|
|
80
|
+
- **Ideas.** Every lens's ideas, with duplicates merged and each one's source IDs kept. An idea never enters the ranked findings.
|
|
81
|
+
- **Proposed groupings.** Findings that one change would fix, grouped, each group with a one-line title and its finding IDs. Do not search the tracker or file anything: `triage-spike-findings` checks each group against the open issues.
|
|
82
|
+
- **Residual unknowns.** Every use case marked `not exercised`, every entry under a report's **Limits**, and every lens recorded as not reported.
|
|
83
|
+
- **Method.** One paragraph: the lenses, the targets with their write rules, and the order of the runs.
|
|
84
|
+
- **Lens reports.** Each report, appended unedited.
|
|
85
|
+
|
|
86
|
+
Write every evidence path relative to `{ticket_dir}`, so that a later session can open the evidence that a finding cites.
|
|
87
|
+
|
|
88
|
+
### 6. Save and publish
|
|
89
|
+
|
|
90
|
+
Save the document with {skill:save-artifact} as a ticket-level `usability-findings` artifact.
|
|
91
|
+
|
|
92
|
+
Then publish it as an artifact page: Load the artifact-design skill, and render the ranked findings as a table that can be filtered by effect, followed by the ideas and the residual unknowns. List each finding's evidence paths; do not embed the screenshots or the transcripts.
|
|
93
|
+
|
|
94
|
+
### 7. Report
|
|
95
|
+
|
|
96
|
+
Give the developer the findings artifact's path, the page's URL, and one line of counts: use cases exercised, findings by effect, and ideas. Name `triage-spike-findings` as the next step, with the findings artifact's path as its input.
|
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: brainstorming
|
|
3
|
+
description: 'You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.'
|
|
4
|
+
user-invocable: false
|
|
5
|
+
supported-harnesses: [rovo]
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
<!-- Extracted verbatim from the superpowers plugin. Do not edit. -->
|
|
9
|
+
|
|
10
|
+
# Brainstorming Ideas Into Designs
|
|
11
|
+
|
|
12
|
+
## Overview
|
|
13
|
+
|
|
14
|
+
Help turn ideas into fully formed designs and specs through natural collaborative dialogue.
|
|
15
|
+
|
|
16
|
+
Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.
|
|
17
|
+
|
|
18
|
+
<HARD-GATE>
|
|
19
|
+
Do NOT use any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.
|
|
20
|
+
</HARD-GATE>
|
|
21
|
+
|
|
22
|
+
## Anti-Pattern: "This Is Too Simple To Need A Design"
|
|
23
|
+
|
|
24
|
+
Every project goes through this process. A todo list, a single-function utility, a config change — all of them. "Simple" projects are where unexamined assumptions cause the most wasted work. The design can be short (a few sentences for truly simple projects), but you MUST present it and get approval.
|
|
25
|
+
|
|
26
|
+
## Checklist
|
|
27
|
+
|
|
28
|
+
You MUST create a task for each of these items and complete them in order:
|
|
29
|
+
|
|
30
|
+
1. **Explore project context** — check files, docs, recent commits
|
|
31
|
+
2. **Ask clarifying questions** — one at a time, understand purpose/constraints/success criteria
|
|
32
|
+
3. **Propose 2-3 approaches** — with trade-offs and your recommendation
|
|
33
|
+
4. **Present design** — in sections scaled to their complexity, get user approval after each section
|
|
34
|
+
5. **Write design doc** — save to `docs/plans/YYYY-MM-DD-<topic>-design.md` and commit
|
|
35
|
+
6. **Transition to implementation** — use writing-plans skill to create implementation plan
|
|
36
|
+
|
|
37
|
+
## Process Flow
|
|
38
|
+
|
|
39
|
+
```dot
|
|
40
|
+
digraph brainstorming {
|
|
41
|
+
"Explore project context" [shape=box];
|
|
42
|
+
"Ask clarifying questions" [shape=box];
|
|
43
|
+
"Propose 2-3 approaches" [shape=box];
|
|
44
|
+
"Present design sections" [shape=box];
|
|
45
|
+
"User approves design?" [shape=diamond];
|
|
46
|
+
"Write design doc" [shape=box];
|
|
47
|
+
"Use writing-plans skill" [shape=doublecircle];
|
|
48
|
+
|
|
49
|
+
"Explore project context" -> "Ask clarifying questions";
|
|
50
|
+
"Ask clarifying questions" -> "Propose 2-3 approaches";
|
|
51
|
+
"Propose 2-3 approaches" -> "Present design sections";
|
|
52
|
+
"Present design sections" -> "User approves design?";
|
|
53
|
+
"User approves design?" -> "Present design sections" [label="no, revise"];
|
|
54
|
+
"User approves design?" -> "Write design doc" [label="yes"];
|
|
55
|
+
"Write design doc" -> "Use writing-plans skill";
|
|
56
|
+
}
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
**The terminal state is using writing-plans.** Do NOT use frontend-design, mcp-builder, or any other implementation skill. The ONLY skill you use after brainstorming is writing-plans.
|
|
60
|
+
|
|
61
|
+
## The Process
|
|
62
|
+
|
|
63
|
+
**Understanding the idea:**
|
|
64
|
+
|
|
65
|
+
- Check out the current project state first (files, docs, recent commits)
|
|
66
|
+
- Ask questions one at a time to refine the idea
|
|
67
|
+
- Prefer multiple choice questions when possible, but open-ended is fine too
|
|
68
|
+
- Only one question per message - if a topic needs more exploration, break it into multiple questions
|
|
69
|
+
- Focus on understanding: purpose, constraints, success criteria
|
|
70
|
+
|
|
71
|
+
**Exploring approaches:**
|
|
72
|
+
|
|
73
|
+
- Propose 2-3 different approaches with trade-offs
|
|
74
|
+
- Present options conversationally with your recommendation and reasoning
|
|
75
|
+
- Lead with your recommended option and explain why
|
|
76
|
+
|
|
77
|
+
**Presenting the design:**
|
|
78
|
+
|
|
79
|
+
- Once you believe you understand what you're building, present the design
|
|
80
|
+
- Scale each section to its complexity: a few sentences if straightforward, up to 200-300 words if nuanced
|
|
81
|
+
- Ask after each section whether it looks right so far
|
|
82
|
+
- Cover architecture, components, data flow, error handling, testing
|
|
83
|
+
- Be ready to go back and clarify if something doesn't make sense
|
|
84
|
+
|
|
85
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
86
|
+
|
|
87
|
+
## After the Design
|
|
88
|
+
|
|
89
|
+
**Documentation:**
|
|
90
|
+
|
|
91
|
+
- Write the validated design to `docs/plans/YYYY-MM-DD-<topic>-design.md`
|
|
92
|
+
- Use elements-of-style:writing-clearly-and-concisely skill if available
|
|
93
|
+
- Commit the design document to git
|
|
94
|
+
|
|
95
|
+
**Implementation:**
|
|
96
|
+
|
|
97
|
+
- Use the writing-plans skill to create a detailed implementation plan
|
|
98
|
+
- Do NOT use any other skill. writing-plans is the next step.
|
|
99
|
+
|
|
100
|
+
## Key Principles
|
|
101
|
+
|
|
102
|
+
- **One question at a time** - Don't overwhelm with multiple questions
|
|
103
|
+
- **Multiple choice preferred** - Easier to answer than open-ended when possible
|
|
104
|
+
- **YAGNI ruthlessly** - Remove unnecessary features from all designs
|
|
105
|
+
- **Explore alternatives** - Always propose 2-3 approaches before settling
|
|
106
|
+
- **Incremental validation** - Present design, get approval before moving on
|
|
107
|
+
- **Be flexible** - Go back and clarify when something doesn't make sense
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: capture-event
|
|
3
|
+
description: 'Capture an event into the shared knowledge substrate. Use when noticing something worth recording for later recall: an observation, a pattern, a refinement, a surprising API surface, a workaround, or a problem that you hit and resolved. A fast pure append, without a survey, recall, or dedup.'
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Capture an event
|
|
8
|
+
|
|
9
|
+
Append an event record to the shared knowledge substrate, or amend an existing one. A bundled helper does the mechanical work: It resolves the event store by name, auto-fills the record's context (a ULID `id`, the capture timestamp, the working directory, and a best-effort `session` and `repo`), validates the event record's required fields, and writes the record atomically. You supply the `summary` and the event body.
|
|
10
|
+
|
|
11
|
+
This is a pure append. Unlike `kb-add`, it does not run a survey, `kb-retrieve` cross-referencing, or dedup. The point is to capture the event cheaply and move on; a later pass recalls and triages the record via `kb-retrieve`.
|
|
12
|
+
|
|
13
|
+
**Announce at start:** "Using capture-event to record this event."
|
|
14
|
+
|
|
15
|
+
## When to capture
|
|
16
|
+
|
|
17
|
+
Capture anything worth recalling later: a behavior, a pattern, a refinement, a surprising API surface, a workaround. Problem→solution and pattern-plus-refinement are useful shapes, but an event may simply be an observation; do not force it into a template.
|
|
18
|
+
|
|
19
|
+
A **solved-problem episode**, a problem that you hit and resolved, is worth tagging so that you can recall past fixes as a group: Capture it with `--tags fix` (plus any topical tags), putting the problem and its resolution in the body. The `fix` tag lets you recall past fixes together later.
|
|
20
|
+
|
|
21
|
+
A **skill-caused mistake**, an error that a clearer skill definition would have prevented, is worth tagging the same way: Capture it with `--tags mistake` and `--skill <skill-at-fault>`, putting what went wrong and what the skill should have said in the body. The `mistake` tag lets you recall skill mistakes as a group when deciding which skills to revise.
|
|
22
|
+
|
|
23
|
+
## Arguments
|
|
24
|
+
|
|
25
|
+
| Argument | Description | Required |
|
|
26
|
+
| ----------- | ------------------------------------------------------------------------------------- | -------- |
|
|
27
|
+
| `--summary` | A human-readable one-line summary; becomes the record's label on recall. | Yes |
|
|
28
|
+
| `--store` | Registry name, `@default` for the `default_kb`, or `@feedback` for the `feedback_kb`. | Yes |
|
|
29
|
+
| `--skill` | The skill to which the event relates. | No |
|
|
30
|
+
| `--model` | The model identifier in play. | No |
|
|
31
|
+
| `--harness` | The agent platform (`claude`, `rovo`); install-injected. Keep as-is. | Injected |
|
|
32
|
+
| `--tags` | Comma-separated tag list. | No |
|
|
33
|
+
| `--impact` | Impact rating: one of `low`, `medium`, `high`, `critical`. Omit to leave unrated. | No |
|
|
34
|
+
| `--amend` | Id of an existing event to rewrite in place instead of capturing a new one. | No |
|
|
35
|
+
|
|
36
|
+
A value-bearing flag accepts both `--summary text` and `--summary=text`. The event body is read from stdin to EOF; an empty body is allowed.
|
|
37
|
+
|
|
38
|
+
### Auto-filled vs agent-supplied
|
|
39
|
+
|
|
40
|
+
- **Auto-filled by the helper:** `recordType` (`event`), `id` (ULID), `captured-at`, `cwd`, `session` (`CLAUDE_CODE_SESSION_ID`, best-effort; omitted silently on a harness that does not expose a session id), and `repo` (the `owner/name` git remote at `cwd`, best-effort; omitted silently when the helper cannot resolve a remote at `cwd`).
|
|
41
|
+
- **Template-injected:** `harness`. `codeassembly` writes the agent platform (`claude` or `rovo`) into the `--harness` flag when it installs this skill. Unlike `model`, which varies per session and is self-reported, the harness is fixed at install time; keep the injected `--harness` flag verbatim rather than filling in a value yourself.
|
|
42
|
+
- **Agent-supplied:** `summary`, the optional `skill`/`model`/`tags`/`impact`, and the body.
|
|
43
|
+
|
|
44
|
+
### Store selection
|
|
45
|
+
|
|
46
|
+
`--store` is required: Every capture names its destination. The helper resolves the store by registry name only. It never walks the working directory for a `.kb/` folder, so a capture goes to the named store and never to a project-local KB near which it happened to be invoked. The store must be registered in `kb.yaml`. The helper refuses a capture that omits `--store`, with an error that lists the registered stores, rather than defaulting silently.
|
|
47
|
+
|
|
48
|
+
Choose the destination deliberately. When the lesson is specific to a project, pass that project's KB with `--store <name>`. Only when the lesson is environment-level, meaning an observation or refinement that applies across every project in the current environment, send it to the registry's `default_kb` by passing `--store @default`. Selecting the default is an explicit act, not what happens when the flag is forgotten.
|
|
49
|
+
|
|
50
|
+
A caller whose destination is a configured role rather than a per-lesson judgment passes that role's sentinel: `--store @feedback` sends a record to the registry's `feedback_kb`, the KB that receives feedback about agent guidance.
|
|
51
|
+
|
|
52
|
+
### Amending an event
|
|
53
|
+
|
|
54
|
+
`--amend <id>` rewrites an existing capture in place (for example, an event that a `capture-feedback` pass got wrong). Prefer amending over capturing a near-duplicate. Amend always rewrites `summary` and the body from the invocation. It overwrites `--skill`, `--model`, `--tags`, or `--impact` only when you pass that flag; any that you omit keep their existing value, as do the provenance fields (`id`, `captured-at`, `session`, `cwd`, `repo`, `harness`) and any `addressed-by` marks. To clear a curatorial field rather than edit content, use its `kb-update-events` mutator.
|
|
55
|
+
|
|
56
|
+
Amend is a plain in-place edit and does not consult push state. To correct an event that may already have been shared, prefer appending a supersession with `kb-update-events --add-addressed-by` over rewriting it, so that the correction becomes a new record rather than a change to history.
|
|
57
|
+
|
|
58
|
+
## Runtime dependencies
|
|
59
|
+
|
|
60
|
+
- **`node` ≥ 24**: The bundled helper inherits the Node version floor of `@williamthorsen/kb`.
|
|
61
|
+
- **A `kb.yaml` registry naming the store**: The helper resolves `--store` through `.agents/kb.yaml` in the project or `~/.agents/kb.yaml`. When the named store is not declared in either registry, every capture is refused rather than written somewhere else.
|
|
62
|
+
|
|
63
|
+
## Process
|
|
64
|
+
|
|
65
|
+
### 1. Compose the summary and body
|
|
66
|
+
|
|
67
|
+
Write a one-line `--summary` that reads well on its own (it is the record's recall label). Put the detail (context, the problem and its resolution, the pattern and its refinement) in the body on stdin. Capture enough context that the event is intelligible months later without the surrounding conversation.
|
|
68
|
+
|
|
69
|
+
Optionally rate `--impact` (`low`, `medium`, `high`, or `critical`): your subjective read of how much addressing the event matters, which applies equally to a bug and to a beneficial change. Omit it when you do not have a clear read; an unrated event is left for a later triage pass. The rating is revisable later with `kb-update-events`.
|
|
70
|
+
|
|
71
|
+
### 2. Invoke the helper
|
|
72
|
+
|
|
73
|
+
Pipe the body to the bundled helper. A heredoc keeps multi-line bodies legible:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
cat <<'EOF' | node {harness_home_dir}/skills/capture-event/capture-event.mjs \
|
|
77
|
+
--summary "<one-line summary>" \
|
|
78
|
+
--store <name|@default|@feedback> \
|
|
79
|
+
--harness {harness_id} \
|
|
80
|
+
[--skill <skill>] [--model <model>] [--tags <comma,separated>] [--impact <level>]
|
|
81
|
+
<event body, may span multiple lines and contain any characters>
|
|
82
|
+
EOF
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
The helper prints a JSON object to stdout:
|
|
86
|
+
|
|
87
|
+
- `ok: true` with `id`, `capturedAt`, `path`, `store` on success.
|
|
88
|
+
- `ok: false` with `error`, `message`, and optional `errors` on a recoverable failure.
|
|
89
|
+
|
|
90
|
+
### 3. Handle the result
|
|
91
|
+
|
|
92
|
+
On `ok: true`, report the captured `id` and `path`.
|
|
93
|
+
|
|
94
|
+
On `ok: false`, handle the `error` code as follows:
|
|
95
|
+
|
|
96
|
+
- `invalid-args`: Report the helper's message and propose a corrected invocation.
|
|
97
|
+
- `missing-store`: `--store` was omitted. Re-run with `--store <name>` for the KB named by the user, or `--store @default` for an environment-level lesson; the message lists the registered stores.
|
|
98
|
+
- `store-not-registered`: The named store is not in `kb.yaml`. Confirm the store name or register it.
|
|
99
|
+
- `readonly-store`: The store is marked readonly; captures are refused.
|
|
100
|
+
- `no-default-store`: `--store @default` was given but `kb.yaml` does not configure a `default_kb`. Name a store explicitly or configure a default with `kb set-default`.
|
|
101
|
+
- `no-feedback-store`: `--store @feedback` was given but `kb.yaml` does not configure a `feedback_kb`. Set `feedback_kb` in `kb.yaml` to the KB that receives feedback about agent guidance.
|
|
102
|
+
- `schema-validation`: Report the `errors`, then supply the missing field and retry.
|
|
103
|
+
- `amend-not-found`: `--amend` named an id that does not match an event in the store. Confirm the id and store.
|
|
104
|
+
- `amend-parse`: The event to amend is not a valid event record. Inspect the file.
|
|
105
|
+
|
|
106
|
+
## Completion
|
|
107
|
+
|
|
108
|
+
A written record at the reported path, validated as an event record. A fresh capture never overwrites an existing event; use `--amend` to rewrite one in place.
|