codeassembly-guidance 0.5.0 → 0.7.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 +491 -0
- package/CHANGELOG.md +118 -0
- package/README.md +33 -4
- package/content/_partials/finding-grades.md +4 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/codeassembly-content.yaml +4 -0
- package/content/collections/recommended.md +5 -2
- package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
- package/content/guidance/rulebooks/cli-conventions.md +17 -2
- package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
- package/content/guidance/shared/AGENTS.md +1 -1
- package/content/scripts/check-prose.mjs +1 -1
- package/content/scripts/describe-change.mjs +88 -88
- package/content/scripts/manage-jira-ticket.mjs +113 -113
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +38 -38
- package/content/skills/_data/action-items.md +2 -2
- package/content/skills/_data/artifact-conventions.md +20 -10
- package/content/skills/_data/concision.md +1 -1
- package/content/skills/_data/entry-points.md +37 -0
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/recommendation-gradient.md +6 -6
- package/content/skills/_data/spike-conventions.md +20 -7
- package/content/skills/_data/ticket-source-resolution.md +21 -4
- package/content/skills/_data/title-templates.md +4 -4
- package/content/skills/_partials/commit-title-rendering.md +2 -1
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/next-steps-after-plan.md +6 -5
- package/content/skills/_partials/option-format.md +8 -8
- package/content/skills/_partials/plan-template.md +5 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
- package/content/skills/_partials/split-launch-prompts.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +1 -1
- package/content/skills/analyze-performance/SKILL.md +102 -0
- package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
- package/content/skills/assess-code-health/SKILL.md +16 -14
- package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
- package/content/skills/assess-usability/SKILL.md +5 -3
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +122 -122
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/convert-agent-prompt/SKILL.md +60 -0
- package/content/skills/create-commit/SKILL.md +10 -5
- package/content/skills/create-pr/SKILL.md +11 -11
- package/content/skills/create-ticket/SKILL.md +1 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +107 -107
- package/content/skills/design-and-plan/SKILL.md +6 -4
- package/content/skills/implement-plan/SKILL.md +4 -29
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +36 -17
- package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
- package/content/skills/investigate-spike/SKILL.md +48 -0
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +31 -8
- package/content/skills/merge-gh-pr/SKILL.md +25 -12
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +55 -20
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +3 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +20 -14
- package/content/skills/refine-plan/SKILL.md +9 -4
- package/content/skills/refine-prototype/SKILL.md +5 -5
- package/content/skills/review-branch/SKILL.md +8 -8
- package/content/skills/review-criteria/SKILL.md +4 -4
- package/content/skills/review-gh-pr/SKILL.md +1 -1
- package/content/skills/revise-prose/SKILL.md +9 -8
- package/content/skills/revise-prose/revise-prose.mjs +111 -111
- package/content/skills/save-plan/SKILL.md +2 -0
- package/content/skills/start-ticket/SKILL.md +27 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +76 -76
- package/content/skills/summarize-change/SKILL.md +27 -9
- package/content/skills/testing-conventions/SKILL.md +14 -3
- package/content/skills/triage-feedback/SKILL.md +4 -0
- package/content/skills/triage-spike-findings/SKILL.md +36 -12
- package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
- package/content/skills/wrap-up/SKILL.md +4 -0
- package/content/subagents/_data/claude.yaml +3 -0
- package/content/subagents/code-health-assessor.md +4 -4
- package/content/subagents/disposition-challenger.md +3 -4
- package/content/subagents/entry-drafter.md +2 -2
- package/content/subagents/handoff-reviewer.md +1 -1
- package/content/subagents/prototype-builder.md +69 -0
- package/content/subagents/usability-assessor.md +1 -1
- package/package.json +11 -10
- package/schemas/preferences.v1.json +74 -8
- package/schemas/work-types.v1.json +1 -1
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
**Confirm that the menu is needed before rendering it.** Mark the options first, check the leader as "Check the leader before rendering" below states, then read the markers: Render the menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class below. Decide every other field: State the decision in one line with its reason, record it, and proceed. Decide an all-■□□ field too. An unmarked list is a pure-preference call, and a preference is in the gated class. The rejected alternative belongs in a clause ("X rather than Y, because Z"), never as a numbered option awaiting selection.
|
|
4
4
|
|
|
5
|
-
A determination that has one right answer under a governing document, such as a change's work type under the work-type test, is not a fork. Resolve doubt about which answer the test yields by applying the test and picking: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact. The developer
|
|
5
|
+
A determination that has one right answer under a governing document, such as a change's work type under the work-type test, is not a fork. Resolve doubt about which answer the test yields by applying the test and picking: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact. The developer has less of the evidence than the agent, so handing the doubt back produces a worse-informed answer.
|
|
6
6
|
|
|
7
7
|
The gated class is closed. Ask about these decisions whatever the markers say:
|
|
8
8
|
|
|
@@ -10,9 +10,9 @@ The gated class is closed. Ask about these decisions whatever the markers say:
|
|
|
10
10
|
- remote shared state: a ticket edit, a push, a merge, the creation of a branch or a ticket
|
|
11
11
|
- data loss, or any action that cannot be undone
|
|
12
12
|
- spend or budget
|
|
13
|
-
- a preference for which you do not
|
|
13
|
+
- a preference for which you do not have any evidence
|
|
14
14
|
|
|
15
|
-
Decide everything else yourself by default. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer;
|
|
15
|
+
Decide everything else yourself by default. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; do not take the gated action itself until the developer authorizes it. A templated next-steps menu is in the class, because what to do next is a preference about the developer's time, for which you do not have any evidence. Verification is never in the gated class: Run a check that a command, a test, or a browser could settle.
|
|
16
16
|
|
|
17
17
|
**Proceed provisionally.** Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the skill's checkpoint. When a gated decision has a strong recommendation, build on it, mark it 🔲 as "Record what you did not ask" states, and ask at the checkpoint; revise if overruled. In a skill without a phase structure, treat the skill's own approval gate, or the end of its work, as the checkpoint.
|
|
18
18
|
|
|
@@ -20,9 +20,9 @@ Decide everything else yourself by default. Never decide a gated action in your
|
|
|
20
20
|
|
|
21
21
|
**Record what you did not ask.** Write every decision that the gate let you take into the plan's `## Decisions taken` section, with a one-line reason; when the work does not have a plan, write it into the turn's summary. Always record: A silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with 🔲, wherever you state it: in the record, and in a turn's narrative, such as a checkpoint summary or a list of decisions. The marker lets the developer find what they may overrule without reading every line. Drop it once the developer approves the checkpoint at which the decision was presented.
|
|
22
22
|
|
|
23
|
-
**Never rank the options by your own elapsed time, round trips, or effort.** You measure
|
|
23
|
+
**Never rank the options by your own elapsed time, round trips, or effort.** You measure all three yourself, and that measure counts the user's context switch and review cycles as nothing. Measuring one does not make the call yours, and a more accurate measurement still cannot rank the options.
|
|
24
24
|
|
|
25
|
-
Ordering follows from the gate. When the order changes the code or the total effort -- upstream before downstream, a refactor before the feature that would otherwise be written twice -- recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved. When the outcomes are identical and only the timing differs, such as when queued work is picked up, present the
|
|
25
|
+
Ordering follows from the gate. When the order changes the code or the total effort -- upstream before downstream, a refactor before the feature that would otherwise be written twice -- recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved. When the outcomes are identical and only the timing differs, such as when queued work is picked up, present the delay that each option causes, render the options unmarked, and put the choice at the checkpoint.
|
|
26
26
|
|
|
27
27
|
Asking is not neutral. It costs the developer a context switch, and it idles the session until the answer arrives. A wrong-but-stated recommendation costs them a word to correct; a decision handed back costs them an evaluation and costs the session the wait.
|
|
28
28
|
|
|
@@ -51,19 +51,19 @@ Stop nesting at one level: Never put a sub-option in an option or a sub-pro in a
|
|
|
51
51
|
|
|
52
52
|
- **Falsifiability.** A `➖` must be false for at least one other option on the menu, and a `➕` likewise. Anything that would still be true if this were the only option is a mechanic of carrying it out rather than a tradeoff; it belongs on the invocation line or nowhere.
|
|
53
53
|
- **Decision weight.** Would a reader who believed this bullet choose differently? Bookkeeping, mechanically-implied, and trivially-reversible consequences (a doc line to update, a criterion to reword, a rename to propagate) are real, specific, and decision-irrelevant. Restatements of an option's inherent properties ("longer wall time", "structured review pass", "ships faster") are one instance of the same failure.
|
|
54
|
-
- **Session context.** Cut a bullet that cites the conversation, what the session
|
|
54
|
+
- **Session context.** Cut a bullet that cites the conversation, what the session's context contains, or what is "already in context". Every handoff goes through a saved artifact, so session context does not distinguish one option from another, and a bullet that rests on it tells the reader that the artifact is incomplete. When the bullet is true, the artifact has a gap: Add the fact to the artifact rather than citing the session.
|
|
55
55
|
- **Consequence.** State in a `➖` what breaks or what it costs, and for whom, concretely enough that the reader can weigh it without investigating. Cut a con that cannot be stated that way.
|
|
56
56
|
- **The qualifier tell.** A bullet undercut by its own qualifier ("negligible", "inert", "harmless") is filler. The only repair is to cut the bullet: Deleting the qualifier leaves the same minor con, now looking weighty.
|
|
57
57
|
- **One tradeoff, stated once.** When one option's `➕` restates another option's `➖`, the two options are the sides of one tradeoff. State it once, in a line above the list, rather than as bullets split between the options, which the reader counts as separate reasons.
|
|
58
58
|
- **Check before you hedge.** If a cheap check would settle whether a con is real, run the check. Presenting the uncertainty as a bullet transfers the check to the user.
|
|
59
59
|
|
|
60
|
-
Asymmetry is a report, not a defect. Give an option that has three real pros but lacks a real con its three pros, and do not give it a con. Never add a bullet to fill a slot,
|
|
60
|
+
Asymmetry is a report, not a defect. Give an option that has three real pros but lacks a real con its three pros, and do not give it a con. Never add a bullet to fill a slot, balance the options, or avoid looking one-sided; when an honest con is hard to find, that difficulty is itself evidence the option is strong. When every option lacks a real bullet, omit them all and let the markers alone convey the recommendation. Do not add tiebreaker text for equal-strength options; the developer picks the number.
|
|
61
61
|
|
|
62
62
|
Keep on a `□□□` option the `➖` that explains why you ruled it out. Under the falsifiability test that bullet is real by construction, and without it the reader is left with a veto that they cannot check.
|
|
63
63
|
|
|
64
64
|
**Check the leader before rendering.** Once you have drafted the bullets, and before you read the markers against the gate, run this check. It applies to a gated decision as fully as to any other: The menu renders whatever the markers say, and the marker tells the developer how much deliberation the ask needs.
|
|
65
65
|
|
|
66
|
-
1. For each alternative, look for a
|
|
66
|
+
1. For each alternative, look for a drawback that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand. When you find one, state it as the alternative's `➖`.
|
|
67
67
|
2. For each `➖` on the strongest-marked option, name the reader who would choose differently because of it. Cut the bullet if there is none.
|
|
68
68
|
3. Re-mark the options. When every alternative has a disqualifying `➖`, mark the leader ■■■. The observed bias is a marker set too weak, not one set too strong.
|
|
69
69
|
4. Re-apply the gate. Outside the gated class, a leader marked above every other option means that the field is decided: State the decision in one line, and do not render a menu. Inside the class, render the menu with the leader's marker as the check set it.
|
|
@@ -52,16 +52,20 @@
|
|
|
52
52
|
|
|
53
53
|
**Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
|
|
54
54
|
|
|
55
|
+
**Per-task verification guidance:** When the work's output is unsettled per [project stage](../_data/project-stage.md), each task that produces the output verifies it through a reading round rather than a golden reference, an answer key, or an eval gate: The agent runs the output on real inputs, starting from the user's own example of the output when one exists, and presents it, and the developer's judgment of it is the task's `**Residue:**`, because only the developer can approve a target. Plan a golden reference or an eval only as a task that follows the developer's approval of an output, and freeze it from that output.
|
|
56
|
+
|
|
55
57
|
**Per-task documentation criterion:** When a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include updating documentation, help text, and usage examples, including removal of references to anything that no longer exists.
|
|
56
58
|
|
|
57
59
|
**Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
|
|
58
60
|
|
|
59
61
|
**Per-task documentation placement:** When a task writes or revises guidance or documentation, its key decisions name the source that defines each fact that the task documents, and the task writes a pointer to that source rather than a copy, per the "Documentation placement" section of the shared agent instructions.
|
|
60
62
|
|
|
61
|
-
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
|
|
63
|
+
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, the model, the placement, and the state attribute of each control that reveals a region or toggles a setting, the cue that marks each state for which a reader scans a list, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook's browser check of each new or changed interactive element.
|
|
62
64
|
|
|
63
65
|
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge. When a verdict from an agent decides such a write, the acceptance criteria of the task that implements the verdict name the evidence and the script that checks it before the write. When the work adds or changes a skill that writes to shared state, `## Verification` runs the skill against the real data up to its approval checkpoint or as a dry run, and reviews each verdict that the run would act on.
|
|
64
66
|
|
|
67
|
+
**Per-task findings-batch guidance:** When a task runs an assessment or a triage of findings, scope it to one batch, as [findings batches](../_data/spike-conventions.md#findings-batches) states.
|
|
68
|
+
|
|
65
69
|
**Per-task invoked-skill guidance:** When a task invokes a skill, read that skill while planning the task and record in the task's key decisions what the skill declares under three headings: its ordering relative to other skills, its default target when the task does not pass an argument, and the preconditions that it states. Read every skill that the plan's tasks name, and record a skill declaring none of the three as declaring none, so that a reader can tell a completed check from an absent one. A skill that cannot be read is recorded as unread, never as declaring none. When an ordering constraint names a skill that the plan's tasks do not invoke, add the task rather than record the constraint alone.
|
|
66
70
|
|
|
67
71
|
**Who performs a step.** Every task and every `## Verification` check names the agent as its actor. A part that only the developer can perform is written as a `**Residue:**` line under the task, after **What:** and in the same position as **Key decisions:**, in the form "**Residue:** {what the developer alone can do}: {why the agent cannot}", and the task's other parts stay the agent's. A residue that a person must perform on each machine is one script per machine, run once, which checks its own result and prints only the facts that the agent needs; the agent writes and commits the script. A record of the work, such as a log entry or a ticket comment, is never residue, and the residue is never shipped as documentation for a person to follow. Check a resource's availability before naming it as a risk; when a step needs something that only the developer can supply, such as a credential or a running service, the step states the ask for that resource, never a degraded fallback and never the step as the developer's. A manual check is cut when an automated test or a check in `## Verification` asserts the same observable outcome, and stays, as the agent's, when it would show something that the tests do not assert. A check proposed against a deployed branch accounts for a `live` worktree, which runs the merged tree rather than the branch.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `branch_name`, `default_branch`, `ticket_id`, `ticket_ref`, `ticket_url`, `scm`, `project_slug`, and `artifact_base_dir` from it.
|
|
2
|
+
|
|
3
|
+
2. **Resolve the plan**: Stop at the first source that yields one:
|
|
4
|
+
- **Explicit `--plan=<path>`**: Read it.
|
|
5
|
+
- **Already in context**: This session produced or read the plan. Use it as-is; do not re-read the file.
|
|
6
|
+
- **Newest plan for the ticket**: The newest of `*_plan.md` and `*_plan-v*.md` under `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/` (run subdirectories included), by the greatest `YYYYMMDD-HHMMSSZ` filename prefix. Both forms have that prefix, so they sort chronologically together and the lexicographically greatest is the newest across the two. Because `refine-plan` writes its revision as `_plan-v2.md` under a later prefix than the plan that it revises, matching both forms lets a refined plan take precedence over the original that it supersedes. Do not widen to `*_plan*.md`, which also matches the `_plan-review.md` artifact written beside the revision.
|
|
7
|
+
- **Ask**: The sources above do not resolve a plan. Ask the user for a path rather than working from the ticket alone: A caller who invoked this skill has a plan in mind.
|
|
8
|
+
|
|
9
|
+
Announce the resolved path and its timestamp before executing anything. Several plans can exist for one ticket, and the newest is not always the intended one: This announcement is how the user catches a superseded plan while the choice can still change without cost. It is not ceremony, and it is not skippable when the resolution was unambiguous.
|
|
10
|
+
|
|
11
|
+
3. **Resolve the ticket**: Stop at the first source that yields one:
|
|
12
|
+
- **Explicit `--ticket=<source>`**: Resolve per [ticket source resolution](../_data/ticket-source-resolution.md).
|
|
13
|
+
- **Already in context**: This session already resolved the ticket. Use it as-is.
|
|
14
|
+
- **Stored URL**: `ticket_url` from step 1, fetched per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url).
|
|
15
|
+
- **Plan provenance**: The plan's frontmatter `ticket_ref` / `ticket_id`, resolved per [auto-resolve](../_data/ticket-source-resolution.md#auto-resolve).
|
|
16
|
+
- **No ticket**: Every source failed; the plan was produced from a free-form description, or the ticket is unreachable. Announce that a ticket does not govern the run and execute against the plan as the sole contract. Do not stall on a missing ticket; do not silently substitute the plan for one without saying so.
|
|
17
|
+
|
|
18
|
+
4. **Read the plan and the ticket** in full before starting the work, including the plan's section on risks: It names the parts of the work that the author expected to need adaptation.
|
|
19
|
+
|
|
20
|
+
Then, when a ticket governs the run, read its open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers). When it has one, report it and ask the user to confirm that the work should start despite it, as a `👍🏼👎🏼` confirmation. Do not start the work without a clear affirmation.
|
|
21
|
+
|
|
22
|
+
Then check the branch per [branch currency](../_data/branch-currency.md), passing the paths that the plan names, such as the paths in a feature plan's **Files:** lists. Do not start the work while a question about the gap is unanswered.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
**Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}
|
|
1
|
+
**Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. When two or more tickets keep work, print the list for them above the prompts, per [implementation-order list](#implementation-order-list), passing an `--edge` for each `--blocked-by` between pieces outside GitHub: The helper reads GitHub's native blockers, which `{skill:create-ticket}` recorded for the GitHub pieces, and not a Jira link. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}**`, followed by a fenced block that contains only the text to paste. The list states each ticket's readiness, so the heading does not repeat it:
|
|
2
2
|
|
|
3
|
-
- The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, and omitting the plan when the ticket does not have one.
|
|
3
|
+
- The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, omitting any argument that the rule omits, and omitting the plan when the ticket does not have one.
|
|
4
4
|
- The scope notes that the session needs and that the artifacts do not state, such as "only tasks 2 and 3" or "merge only after `live` contains #N".
|
|
5
5
|
- The ticket's blockers, by reference.
|
|
@@ -4,4 +4,6 @@
|
|
|
4
4
|
|
|
5
5
|
**Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must be merged before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
|
|
6
6
|
|
|
7
|
+
**Findings-batch criterion convention:** When writing a ticket that schedules an assessment or a triage of findings, shape it as [findings batches](../_data/spike-conventions.md#findings-batches) states.
|
|
8
|
+
|
|
7
9
|
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration. When the ticket adds or changes a skill that writes to shared state, include a criterion that the skill runs against the real data before merge and stops before the write, and when a verdict from an agent decides that write, a criterion that a script checks the verdict's evidence before the write.
|
|
@@ -51,7 +51,7 @@ What the skill does depends on whether a prior ticket exists, not on how the cal
|
|
|
51
51
|
|
|
52
52
|
**Alignment, when a prior ticket exists.** `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the ticket was written. Reproduce all three verbatim from the source ticket and revise `## Acceptance criteria` alone, because the criteria alone are the contract that an implementation can falsify. A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. A section missing from the source ticket stays omitted: Alignment revises the record and adds nothing to it. The saved artifact is still a complete ticket; only its revision is partial.
|
|
53
53
|
|
|
54
|
-
When the implementation diverges from what was proposed, report
|
|
54
|
+
When the implementation diverges from what was proposed, report the divergence in the pull-request description's `## Notes for reviewers` only when it changes what a reviewer checks, under the reader test that `summarize-change` states, and state it as the current fact rather than as a departure from the ticket; otherwise leave it out. Do not raise it as a ticket edit, and do not offer it as an option. A reviewer reads the diff to learn what the code does, so an implementation outgrowing its proposal is an ordinary finding rather than a defect in the ticket.
|
|
55
55
|
|
|
56
56
|
The source ticket is the one that the caller names. A review names it in its `## Specification compliance` section, which records the source against which the review measured, the remote issue or the local snapshot.
|
|
57
57
|
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: analyze-performance
|
|
3
|
+
description: Measure a site's web performance as field data and lab data for mobile and desktop, diagnose the pages that fail a Core Web Vitals threshold from Lighthouse's insights and the repository, and write a findings artifact of improvements ranked by expected effect, each with its evidence, the metric that it moves, and its effort. Use when asked how well a site performs, why it is slow, or what would make it faster.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Analyze performance
|
|
8
|
+
|
|
9
|
+
Report how a site performs today and which changes would make it faster. A bundled helper measures each page and reduces the runs to medians, threshold classes, field data, and the failing Lighthouse insights merged across pages; you resolve the targets, diagnose what the measurements show, inspect the repository for the causes, and rank the improvements in one findings artifact.
|
|
10
|
+
|
|
11
|
+
The skill does not write anything remote: It does not create a ticket, comment on an issue, or change a deployment. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
|
|
12
|
+
|
|
13
|
+
## Inputs
|
|
14
|
+
|
|
15
|
+
- **The targets**: one or more URLs, or the current repository, as the developer names them.
|
|
16
|
+
- **The private URLs**, optional: URLs that PSI must not be sent, such as a staging site.
|
|
17
|
+
- **The ticket**, optional. Without one in session, {skill:save-artifact} saves the artifacts under the ticket ID that it generates.
|
|
18
|
+
|
|
19
|
+
The Lighthouse CLI needs Node 22.19 or later, `pnpm`, and a local Chrome. Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`. Invoke the helper as:
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
node {harness_home_dir}/skills/analyze-performance/analyze-performance.mjs {command} {flags}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
The helper's commands, its tool-selection rule, its thresholds, and its output shapes are documented in the guidance package's `docs/analyze-performance-helper.md`.
|
|
26
|
+
|
|
27
|
+
## Tools
|
|
28
|
+
|
|
29
|
+
| Tool | Role | Target |
|
|
30
|
+
| ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
|
|
31
|
+
| PageSpeed Insights API | Lab data from a remote Lighthouse run, with CrUX field data, without a key | A public URL; the helper falls back to the Lighthouse CLI when PSI refuses |
|
|
32
|
+
| Lighthouse CLI | Lab data from a local Chrome | A local or preview URL, a private URL, or a public URL that PSI refused |
|
|
33
|
+
| CrUX API | Field data at the 75th percentile for the URL and the origin | A public URL, when `CRUX_API_KEY` is set |
|
|
34
|
+
| Lighthouse insights | The trace-derived diagnosis in every Lighthouse report: LCP breakdown, render-blocking requests, layout-shift culprits, and the rest | Every measured page |
|
|
35
|
+
| Chrome DevTools MCP server | An interactive trace of one page, for a closer look than the insights give | A page whose insights do not explain a failing metric, when the server is connected |
|
|
36
|
+
| The framework's bundle analyzer, or `source-map-explorer` through an ephemeral runner | The modules that dominate shipped JavaScript | The repository's production build |
|
|
37
|
+
| `curl --head` | Caching, compression, and protocol headers | The production URL, or the local server labelled as local |
|
|
38
|
+
|
|
39
|
+
WebPageTest and sitespeed.io are out of scope: They need a key or a hosted account, and the tools above measure what the findings rank on.
|
|
40
|
+
|
|
41
|
+
## Process
|
|
42
|
+
|
|
43
|
+
### 1. Prepare
|
|
44
|
+
|
|
45
|
+
Resolve the ticket directory per {skill:save-artifact}, and create `{ticket_dir}/performance/`. Read the declared stage from `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`. When `project_sensitivity` is `personal` or `confidential`, pass every URL that is not publicly reachable as `--private`, so that it is never sent to PSI.
|
|
46
|
+
|
|
47
|
+
### 2. Resolve the targets
|
|
48
|
+
|
|
49
|
+
For a repository target:
|
|
50
|
+
|
|
51
|
+
- **The local build.** Build and serve it by the repository's own production build and serve scripts, such as `build` then `start` or `preview`. Never measure a dev server, whose unminified, unbundled output misreports every metric. When the repository does not have a serve script, serve the build output with a static file server through an ephemeral runner.
|
|
52
|
+
- **The production URL.** When the developer did not name one, look for it in the repository's declarations: a framework's site setting (such as Next.js `metadataBase` or Astro's `site`), a sitemap configuration, `homepage` in `package.json`, a GitHub Pages `CNAME`, or the domains of a linked Vercel project. Record the URL with the file that declares it. When none is declared, measure the local build now and ask for the production URL at the checkpoint.
|
|
53
|
+
|
|
54
|
+
Then choose the pages: one per template, from the sitemap or the routes, at most six unless the developer names more. Record each choice with its template. Pass as `--private` every URL that the developer marks private, every preview deployment URL, and every URL whose page requires sign-in; the helper's host rule covers local addresses.
|
|
55
|
+
|
|
56
|
+
### 3. Measure
|
|
57
|
+
|
|
58
|
+
Run `collect` with every chosen URL, then `summarize`:
|
|
59
|
+
|
|
60
|
+
```bash
|
|
61
|
+
node {harness_home_dir}/skills/analyze-performance/analyze-performance.mjs collect \
|
|
62
|
+
--url {url} [--url {url}]... [--private {url}]... --out {ticket_dir}/performance/raw/
|
|
63
|
+
node {harness_home_dir}/skills/analyze-performance/analyze-performance.mjs summarize --in {ticket_dir}/performance/raw/
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Save the summary as `{ticket_dir}/performance/summary.json`. `collect` reaches the hosts that the helper doc lists; when the sandbox refuses one, retry through the permission gate rather than measuring less. A page's `fallbackReason` and every line of the summary's `unmeasured` go into the artifact's **Unmeasured** section as they stand.
|
|
67
|
+
|
|
68
|
+
### 4. Diagnose
|
|
69
|
+
|
|
70
|
+
For each page and form factor, take each metric classed `poor` or `needs-improvement`, in field data first and lab data otherwise, and find its causes:
|
|
71
|
+
|
|
72
|
+
- **Insights.** Read the merged insights whose `savings` name the metric. Open the raw report that an insight's `files` names when the summary does not give enough detail, such as the LCP element or the subparts of the LCP breakdown.
|
|
73
|
+
- **The repository**, when one is in scope. Trace each culprit resource to the source that produces it: a bundle to its dominant modules through the bundle analyzer, an image or a font to where the code loads it and how, and a response to the headers that the server or the hosting configuration sets. Name each source by its path relative to the repository root.
|
|
74
|
+
- **A trace**, when the Chrome DevTools MCP server is connected and a failing metric's insights do not account for it. Record what the trace shows; when the server is not connected, record the gap under **Unmeasured**.
|
|
75
|
+
|
|
76
|
+
Lab TBT stands in for INP, which only field data measures: Report it as a proxy, never as INP.
|
|
77
|
+
|
|
78
|
+
### 5. Compose the findings
|
|
79
|
+
|
|
80
|
+
Write the findings document with these sections, in this order:
|
|
81
|
+
|
|
82
|
+
1. **Summary.** One table per page of field data, at URL and origin level for each form factor, and one of lab data, with each metric's value and class. Never merge the two: Field data is what real users met, and lab data is one simulated device. State each page's field-data source, or that field data is unavailable and why.
|
|
83
|
+
2. **Improvements.** One entry per change, each with:
|
|
84
|
+
- its title;
|
|
85
|
+
- its evidence: the insight ids and culprits, the raw files relative to `{ticket_dir}`, and the repository paths;
|
|
86
|
+
- the metric that it is expected to move, the pages and form factors on which that metric fails, and the expected effect, taken from the insight's estimated saving where one exists;
|
|
87
|
+
- its effort, with its reason: `S` for one file or setting, `M` for several files in one area, `L` for a cross-cutting change or one that needs a design decision.
|
|
88
|
+
|
|
89
|
+
Rank the improvements by the class of the metric that each moves, `poor` before `needs-improvement`, then by estimated saving in the metric's own unit (milliseconds for LCP, FCP, and TBT; the shift score for CLS), then by the number of pages. A byte saving breaks a remaining tie only. An improvement drawn from the repository alone, without an insight, ranks after the insight-backed ones of its class. An improvement that the insights of one page alone support says so.
|
|
90
|
+
|
|
91
|
+
3. **Unmeasured.** What each missing key, missing production URL, private target, failed run, and unconnected tool left out. When the production URL is unknown, state that field data and production delivery (CDN caching, compression, and time to first byte) were not measured.
|
|
92
|
+
4. **Method.** The tools with the Lighthouse version, the runs per form factor, each page with its template and its tool, the build and serve commands for a local target, and the date.
|
|
93
|
+
|
|
94
|
+
### 6. Checkpoint
|
|
95
|
+
|
|
96
|
+
Save the document with {skill:save-artifact} as a ticket-level `performance-findings` artifact, and present the summary tables and the ranked improvements. Ask in one action-items block for approval of the findings, and for the production URL when step 2 did not find one. When the developer supplies a URL, measure it as in step 3, revise the findings, and save the revision before asking again. Revise the ranking on the developer's feedback.
|
|
97
|
+
|
|
98
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
99
|
+
|
|
100
|
+
### 7. Report
|
|
101
|
+
|
|
102
|
+
Once the developer approves the findings, give the artifact's path and one line of counts: pages measured, metrics failing by class, and improvements by effort. Name {skill:triage-spike-findings} as the next step, with the artifact's path as its input. Improvements above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
|