codeassembly-guidance 0.5.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/.meta/changelog.json +306 -0
  2. package/CHANGELOG.md +73 -0
  3. package/README.md +55 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/collections/recommended.md +5 -2
  7. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  8. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  9. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  10. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  11. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  12. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  14. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  15. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  16. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  17. package/content/scripts/check-prose.mjs +1 -1
  18. package/content/scripts/describe-change.mjs +68 -68
  19. package/content/skills/_data/action-items.md +2 -2
  20. package/content/skills/_data/artifact-conventions.md +20 -10
  21. package/content/skills/_data/concision.md +1 -1
  22. package/content/skills/_data/entry-points.md +37 -0
  23. package/content/skills/_data/recommendation-gradient.md +6 -6
  24. package/content/skills/_data/spike-conventions.md +13 -3
  25. package/content/skills/_data/ticket-source-resolution.md +21 -4
  26. package/content/skills/_data/title-templates.md +4 -4
  27. package/content/skills/_partials/commit-title-rendering.md +2 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  29. package/content/skills/_partials/option-format.md +8 -8
  30. package/content/skills/_partials/plan-template.md +3 -1
  31. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  32. package/content/skills/_partials/split-launch-prompts.md +1 -1
  33. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  34. package/content/skills/analyze-performance/SKILL.md +102 -0
  35. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  36. package/content/skills/assess-code-health/SKILL.md +16 -14
  37. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  38. package/content/skills/assess-usability/SKILL.md +5 -3
  39. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  40. package/content/skills/create-commit/SKILL.md +10 -5
  41. package/content/skills/create-pr/SKILL.md +11 -11
  42. package/content/skills/create-ticket/SKILL.md +1 -0
  43. package/content/skills/design-and-plan/SKILL.md +2 -2
  44. package/content/skills/implement-plan/SKILL.md +1 -28
  45. package/content/skills/index-prototypes/SKILL.md +36 -17
  46. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  47. package/content/skills/investigate-spike/SKILL.md +48 -0
  48. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  49. package/content/skills/refine-plan/SKILL.md +7 -4
  50. package/content/skills/refine-prototype/SKILL.md +5 -5
  51. package/content/skills/review-branch/SKILL.md +7 -7
  52. package/content/skills/review-criteria/SKILL.md +3 -3
  53. package/content/skills/review-gh-pr/SKILL.md +1 -1
  54. package/content/skills/revise-prose/SKILL.md +9 -8
  55. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  56. package/content/skills/start-ticket/SKILL.md +27 -0
  57. package/content/skills/summarize-change/SKILL.md +17 -9
  58. package/content/skills/testing-conventions/SKILL.md +12 -1
  59. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  60. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  61. package/content/subagents/_data/claude.yaml +3 -0
  62. package/content/subagents/code-health-assessor.md +4 -4
  63. package/content/subagents/disposition-challenger.md +3 -4
  64. package/content/subagents/entry-drafter.md +2 -2
  65. package/content/subagents/handoff-reviewer.md +1 -1
  66. package/content/subagents/prototype-builder.md +69 -0
  67. package/content/subagents/usability-assessor.md +1 -1
  68. package/package.json +5 -4
  69. package/schemas/preferences.v1.json +1 -1
  70. package/schemas/work-types.v1.json +1 -1
  71. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -8,7 +8,7 @@ The render contract comes first; the doctrine behind it follows. Skills that clo
8
8
 
9
9
  ## Sweep before sending
10
10
 
11
- The failure prevented by this convention is not bad formatting. It is an ask that the agent never recognized as an ask. The formatting rules never applied to it. Before ending a turn, scan the draft for anything that invites a response and move every hit into the block.
11
+ This convention prevents an ask that the agent never recognized as an ask, and to which the formatting rules therefore never applied. Before ending a turn, scan the draft for anything that invites a response and move every hit into the block.
12
12
 
13
13
  Soft offers are the hardest form to spot. Each phrases a question as a statement:
14
14
 
@@ -25,7 +25,7 @@ Soft offers are the hardest form to spot. Each phrases a question as a statement
25
25
 
26
26
  Each is an action item. Restate it in the block as the concrete action that it proposes, and strike the offer from the prose. The observation that prompted it may stay; that is signal. The ask may not.
27
27
 
28
- The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already holds is a decision that it declined to make, and handing it back makes the user evaluate what a clause would have stated. Strike it, state the decision in the prose with its reason, and leave the block to the items that only the user can settle. An item that the agent could perform is a step that it declined to take: Run it, and leave in the block only the part that the agent cannot perform, named with its reason. A plan's "the owner exercises `/lab/book-row` by keyboard and on a touch device" is the counterexample: The agent drives the route through a debug browser, and the block holds at most how the control feels on a physical phone. A block emptied this way is a turn without an ask, which is a report rather than a failure.
28
+ The sweep runs in both directions. Having moved every ask into the block, read the block back and ask of each item whether it is really a question: An item whose answer follows from evidence that the agent already has is a decision that it declined to make, and handing it back makes the user evaluate what a clause would have stated. Strike it, state the decision in the prose with its reason, and leave the block to the items that only the user can settle. An item that the agent could perform is a step that it declined to take: Run it, and leave in the block only the part that the agent cannot perform, named with its reason. A plan's "the owner exercises `/lab/book-row` by keyboard and on a touch device" is the counterexample: The agent drives the route through a debug browser, and the block contains at most how the control feels on a physical phone. A block emptied this way is a turn without an ask, which is a report rather than a failure.
29
29
 
30
30
  An overload signal from the user, such as "I can't do this any more" or a count of the commands that they have run, empties the block in every turn until the user asks for something; the "Prompt formatting" section of the collaboration preferences states the rule.
31
31
 
@@ -4,7 +4,7 @@ Standards for AI-generated artifact storage, naming, and lifecycle.
4
4
 
5
5
  ## Purpose
6
6
 
7
- The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it stood at the moment of writing (see [Mutability](#mutability)). The directory is not a source of truth, and it is not a home for durable content:
7
+ The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it was at the moment of writing (see [Mutability](#mutability)). The directory is not a source of truth, and it is not a home for durable content:
8
8
 
9
9
  - **Durable content.** Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories. A later session looks there, not in the artifact directory.
10
10
  - **Authority.** An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests.
@@ -33,6 +33,9 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
33
33
  │ │ ├── sense.json
34
34
  │ │ ├── {lens}/report.md
35
35
  │ │ └── {lens}/proposals.json
36
+ │ ├── performance/ ← a performance analysis's measurements and summary, kept by `analyze-performance`
37
+ │ │ ├── summary.json
38
+ │ │ └── raw/ ← the helper's run directory: `manifest.json` and each page's raw responses
36
39
  │ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
37
40
  │ │ ├── findings.md
38
41
  │ │ ├── inventory.md
@@ -86,6 +89,10 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
86
89
 
87
90
  `code-health/` contains the working files of the ticket's code-health assessment: the sense document with each check's log beside it, the test reports that the sensors read, each lens's report and checked proposals, and the merged proposals. The `code-health-findings` artifact cites code by paths relative to the repository root, so it does not depend on these files; they record what the run measured.
88
91
 
92
+ ### Performance measurements
93
+
94
+ `performance/` contains the working files of the ticket's performance analysis: `raw/`, the run directory that the `analyze-performance` helper writes, with its manifest and every PSI response, Lighthouse report, and CrUX record, and `summary.json`, the helper's summary of that directory. The `performance-findings` artifact cites raw files by paths relative to the ticket directory, so the measurements stay in the ticket directory.
95
+
89
96
  ### Triage working files
90
97
 
91
98
  `triage/` contains the working files of a triage of the ticket's findings: a local copy of the findings when they came from an artifact URL, the inventory, the recommendations that the challenger reads, the challenger's reply, the dispositions record from which the `dispositions` artifact is rendered, and the comments rendered from that record: `preview/` with placeholders for the confirmation, `rendered/` with every number for posting. The record stays here as a working file; the artifact is the rendered text.
@@ -230,7 +237,7 @@ Keys inside the `provenance:` block use **camelCase** (e.g., `baseSha`, `isInter
230
237
 
231
238
  ### Field definitions
232
239
 
233
- The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
240
+ The table below lists only the universal fields. Artifact-specific extensions (`provenance.iteration`, `provenance.parent`, `session_type`, `tickets_created`, `title`, `scope`, `type`, `responding_to`, etc.) are documented in the per-artifact sections below.
234
241
 
235
242
  | Field | Required | Description |
236
243
  | -------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -261,7 +268,7 @@ The table below lists only the universal fields. Artifact-specific extensions (`
261
268
 
262
269
  Most skills and subagents produce frontmatter by running `resolve-frontmatter.sh` in its default YAML mode and prepending the output verbatim. Two sites are deliberate exceptions and compose the YAML block themselves:
263
270
 
264
- - `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance). The shell flag surface cannot express this conditional logic cleanly.
271
+ - `refine-plan`: The `provenance:` block is case-branched on the input artifact's existing provenance (preserving `skill`, `baseSha`, `isInteractive`, and `iteration` from the original authoring skill, with fallbacks when the input does not have provenance), and `parent` is set from the input's file name. The shell flag surface cannot express this conditional logic cleanly.
265
272
  - `wrap-up` (deferred-findings artifact): `tickets_created` is a list of `{id, items}` objects, a structure that does not have a clean CLI expression and is best composed in the skill's own logic.
266
273
 
267
274
  Both read the script's JSON output and write the YAML frontmatter themselves. The pattern is intentional, not a workaround; keep new skills on the YAML mode path unless they have a similarly structural reason to deviate.
@@ -284,11 +291,12 @@ When authoring a new skill that needs session-context fields: Invoke the bundled
284
291
 
285
292
  ## Plan provenance
286
293
 
287
- This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extension:
294
+ This artifact uses the [universal artifact frontmatter](#universal-artifact-frontmatter) plus the following artifact-specific extensions:
288
295
 
289
- | Field | Required | Description |
290
- | ---------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------- |
291
- | `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
296
+ | Field | Required | Description |
297
+ | ---------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
298
+ | `provenance.iteration` | no | Refinement iteration counter. Absent on first authoring; set to `2` on first refinement, incremented on subsequent refinements. |
299
+ | `provenance.parent` | no | File name of the plan that this plan was revised from. Absent on first authoring; set by `refine-plan` on every revision and never carried forward, so that each revision names its own predecessor. |
292
300
 
293
301
  Plan-specific `provenance.skill` values include `design-and-plan`, `plan`, `plan-mode`, and `unknown` (when the authoring skill cannot be determined). `refinedBy` is the skill that last processed the plan (typically `refine-plan`).
294
302
 
@@ -393,15 +401,17 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
393
401
  - `dispositions`: The rendered dispositions of a triage of findings, the text that `triage-spike-findings` posts on the triage ticket: every item with its disposition, its confidence and value, where it went, and its reason, with the challenge's summary; the JSON record from which it is rendered stays in `triage/`
394
402
  - `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
395
403
  - `feedback-curation`: The record of a `curate-feedback` run: the count of events in each bin, the guidance commits against which the judges read, each mark with its result, and every event with its bin, reference, and reason; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
396
- - `feedback-triage`: The record of a `triage-feedback` run: each surfaced cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
404
+ - `feedback-triage`: The record of a `triage-feedback` run: each reported cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
397
405
  - `idea-decisions`: The idea table of a round of prototypes with the decision on each idea filled; `prepare-prototype-brief` saves it after the developer decides each idea, and the end vision cites it
398
406
  - `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
407
+ - `performance-findings`: The measured performance of a site and the improvements ranked by expected effect, with field and lab data reported separately, each improvement's evidence, metric, and effort, what was left unmeasured, and the method; `analyze-performance` saves it, and `triage-spike-findings` reads it
399
408
  - `plan`: Implementation plan document
400
409
  - `plan-review`: Plan review findings (completeness and correctness analysis)
401
410
  - `plan-v2`: Refined implementation plan after review and revision
402
411
  - `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
403
412
  - `refinement-log`: The accepted changes of one session of `refine-prototype`, grouped under the id of the version that each one entered, with the transplants' sources and the open forks; the end vision reads it with the `idea-decisions` artifact
404
413
  - `review`: Code review (ticket-level, commit scope)
414
+ - `spike-findings`: The findings and recommendation of a spike: the answer to each of the ticket's questions to answer, the recommendation on each decision to enable, the residual unknowns, the evidence, and any proposed work; `investigate-spike` saves it, and `triage-spike-findings` reads it
405
415
  - `ticket`: Issue ticket
406
416
  - `usability-brief`: The brief that every lens of a usability assessment reads: the medium, the targets and their write rules, the lenses with their minimum use cases, and the exclusions; `assess-usability` saves it at its checkpoint
407
417
  - `usability-findings`: The merged findings of a usability assessment, ranked by effect and reach, with the use-case outcomes, the ideas, the proposed groupings, the residual unknowns, and the lens reports; `assess-usability` saves it, and `triage-spike-findings` reads it
@@ -476,9 +486,9 @@ A finding therefore has one of exactly two shapes, and consumers may rely on the
476
486
 
477
487
  A named change still has to be worth making. Decide at this gate whether it is, having established at the [Proposed-change gate](#proposed-change-gate) that a change exists.
478
488
 
479
- A finding costs more than its line length: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as taking on a burden of proof, weighed against that full cost, never against its line length.
489
+ A finding consumes more than its line length: the reader's time, the tokens spent asking you to reconsider it, the author's triage, and every later reader who reads both the finding and its rejection. Treat emitting any finding as taking on a burden of proof, weighed against everything that it consumes, never against its line length.
480
490
 
481
- This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, costs every reader attention once that cost outweighs the decision that it enables.
491
+ This gate is the [concision principle](./concision.md) applied to findings: A finding, like any detail, wastes every reader's attention once the attention that it takes outweighs the decision that it enables.
482
492
 
483
493
  **Hedging language is a delete trigger, not a softening device.** If a finding's own qualifiers make it irrelevant, it does not belong. Drop it. If the condition genuinely holds now, drop the qualifier instead and state the finding plainly. Disqualifying signs include:
484
494
 
@@ -12,7 +12,7 @@ A load-bearing decision is worth elaborating; a routine one is worth a clause. A
12
12
 
13
13
  ## What to cut
14
14
 
15
- Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work or decision was reached) when only the conclusion serves the reader.
15
+ Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work was done or how the decision was made) when only the conclusion serves the reader.
16
16
 
17
17
  ## Self-test
18
18
 
@@ -0,0 +1,37 @@
1
+ # Entry points
2
+
3
+ The skill that opens the work in a ticket's worktree follows from the ticket's state and the artifacts in its ticket directory. This file states that rule once; {skill?:start-ticket} applies it when a session starts, and the split report of every plan skill names that skill rather than choosing an entry point of its own.
4
+
5
+ ## Inputs
6
+
7
+ - **The ticket's state**: open or closed, from the platform fetch in [ticket source resolution](ticket-source-resolution.md#platform-specific-fetch).
8
+ - **The branch's pull request**: `pr_url` from the session-context manifest, or else the pull request whose head is `branch_name` in any state (on GitHub, `gh pr list --head {branch_name} --state all --json url,state`). `pr_url` is usually null on a ticket branch, so the lookup is the common case.
9
+ - **The ticket directory**: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`, and the artifact types that [artifact conventions](artifact-conventions.md) defines. The newest plan is the one that the plan resolution of {skill?:implement-plan} selects (its [process](../implement-plan/SKILL.md#process), step 2): the greatest filename prefix across `*_plan.md` and `*_plan-v*.md`, never `*_plan-review.md`. The newest artifact of any other type is the one with the greatest filename prefix.
10
+
11
+ ## Routes
12
+
13
+ Check the routes in order and stop at the first match. Each route names the skill, the arguments that it passes, and the reason that the announcement states.
14
+
15
+ 1. **Done.** The ticket is closed, or the branch has a pull request that is open or merged: Stop, and report in one line `{ticket_ref} is {state}; PR {url} is {state}.`, with each clause only when it applies. A closed pull request that was not merged does not match, because the work may restart.
16
+
17
+ 2. **Unsettled plan.** The newest plan contains a list entry inside its `## Decisions taken` section whose text starts with 🔲: {skill?:refine-plan} with the plan path and the ticket. Reason: the plan contains a decision that no checkpoint approved. A 🔲 elsewhere in the plan, or one that a decision mentions rather than starts with, does not match.
18
+
19
+ 3. **Spike.** The ticket body, in its newest ticket artifact or on the platform, contains the `## Question` section and the `### Questions to answer` tier of the [spike ticket template](spike-conventions.md#spike-ticket-template), or the newest plan contains `## Investigation steps`:
20
+ - The ticket directory contains a `dispositions` artifact, which {skill?:triage-spike-findings} saves once its last write succeeds: Stop, and report the findings artifact and the dispositions. The spike is finished.
21
+ - The ticket directory contains `triage/dispositions.json` without a `dispositions` artifact: {skill?:triage-spike-findings} with the findings path, which resumes the interrupted triage from that record.
22
+ - A `spike-findings` artifact newer than the plan proposes work, judged by reading it with the test of {skill?:investigate-spike} step 8: {skill?:triage-spike-findings} with the findings path.
23
+ - A `spike-findings` artifact newer than the plan does not propose any work: Stop, and report it, with the closing post as the step that remains, which {skill?:investigate-spike} offers.
24
+ - The newest plan is a spike plan: {skill?:investigate-spike} with `--plan={path}` and `--ticket={ticket_ref}`.
25
+ - Otherwise: routes 5c and 5d, with `as a spike` after the ticket ref. That phrase is the explicit entry into spike mode that [spike conventions](spike-conventions.md) requires.
26
+
27
+ 4. **Prototype round.** The ticket directory contains a prototype set (`prototypes/manifest.json`, per [the set](../index-prototypes/SKILL.md#the-set)), or a `brief`, `comparison`, `idea-decisions`, or `refinement-log` artifact, or the ticket calls for two or more competing prototypes of one idea, judged by reading it:
28
+ - A `refinement-log` artifact: {skill?:design-and-plan} with the ticket ref, for the end vision and the ticket. {skill?:refine-prototype} saves the log when the refinement closes, so the log marks the refinement as done.
29
+ - An `idea-decisions` artifact that is newer than the newest `comparison` and does not contain an `open` row: {skill?:refine-prototype}.
30
+ - A `comparison` artifact, with an `idea-decisions` artifact newer than it that contains an `open` row, or none newer than it: {skill?:prepare-prototype-brief} with the ticket ref and the scope note `decide the ideas (step 7)`.
31
+ - Otherwise: {skill?:prepare-prototype-brief} with the ticket ref, adding the scope note `resume the round from the saved brief` when a `brief` artifact exists.
32
+
33
+ 5. **Feature.**
34
+ - a. Route 2 covers a plan that contains an unsettled decision.
35
+ - b. Any other plan: {skill?:implement-plan} with `--plan={path}` and `--ticket={ticket_ref}`.
36
+ - c. The ticket is ready: It states a problem, a proposed solution, and acceptance criteria, and applying [ticket evaluation](ticket-evaluation.md) does not find any divergence that needs a design conversation. This is a judgment, and the announcement states its reason. {skill?:plan} with the ticket ref.
37
+ - d. Otherwise: {skill?:design-and-plan} with the ticket ref.
@@ -8,11 +8,11 @@ The render contract comes first; the doctrine behind it follows. Skills that ask
8
8
 
9
9
  ## Why the gate comes first
10
10
 
11
- Asking is not a neutral act. It is cheap for the agent (it discharges responsibility for the call, rules out being wrong, and takes one paragraph) and expensive twice over: The developer must switch context to load the context, weigh the options, and answer, and the session that asked idles until the answer arrives. Across a dozen concurrent sessions those costs compound into decision fatigue and a stalled pipeline. A menu that the agent could have resolved itself transfers cost from the cheap side to the expensive one, and it looks like diligence while it happens, which is why it goes unnoticed and recurs.
11
+ Asking is not a neutral act. It is cheap for the agent (it discharges responsibility for the call, rules out being wrong, and takes one paragraph) and expensive twice over: The developer must switch context to load the context, weigh the options, and answer, and the session that asked idles until the answer arrives. Across a dozen concurrent sessions, those context switches and idle waits add up to decision fatigue and a stalled pipeline. A menu that the agent could have resolved itself moves the work of the decision from the agent, for which it is cheap, to the developer, for whom it is expensive, and it looks like diligence while it happens, which is why it goes unnoticed and recurs.
12
12
 
13
13
  The gate reads the markers rather than asking for judgment, because a step that says to ask overrides a judgment gate: An agent following a step list executes the step, and a rendered ■■■ makes the ask feel legitimate. The gate is only as reliable as the markers that it reads, and the observed bias is a marker set too weak: An option whose alternatives have disqualifying flaws gets ■■□, and the menu renders. The contract's leader check corrects that before the gate reads the markers. Two ■■□ at the top is a real fork, an unmarked list is a preference, and every other field is decided. The gated class is a closed list for the same reason: "consequential" is read generously, and a list is not.
14
14
 
15
- The leader check is not only for the gate. A gated decision renders its menu whatever the markers say, so a check read as deciding whether a menu renders looks pointless there and is skipped. The marker still does its other job: It tells the developer how much deliberation the ask needs. A leader marked ■■□ above a disqualified alternative reads as a close call, and the developer must re-derive the analysis to find out that the alternative was never viable before approving. An honest ■■■ lets them approve at a glance. A cost that disqualifies an alternative often follows from the constraints or the acceptance criteria of the work at hand rather than from the option itself, which is why the check searches each alternative for such a cost before marking.
15
+ The leader check is not only for the gate. A gated decision renders its menu whatever the markers say, so a check read as deciding whether a menu renders looks pointless there and is skipped. The marker still does its other job: It tells the developer how much deliberation the ask needs. A leader marked ■■□ above a disqualified alternative reads as a close call, and the developer must re-derive the analysis to find out that the alternative was never viable before approving. An honest ■■■ lets them approve at a glance. A drawback that disqualifies an alternative often follows from the constraints or the acceptance criteria of the work at hand rather than from the option itself, which is why the check searches each alternative for such a drawback before marking.
16
16
 
17
17
  A real fork is a choice between acceptable options, not doubt about a fact. On one change, the agent applied the work-type test and resolved the change to `feat`, then rendered one entry's typing, `feat` against `fix`, as a menu marked ■■□ on both options. The agent had the diff, the commits, the taxonomy, and the test that decides the type; the developer had the summary bullets, and answering meant reloading all of it to give a worse-informed answer than the agent's. The type has one right answer under the test, and the closeness of the two candidates was doubt about which one the test yields. The correct handling is a decision: Apply the test, pick, state the reason in one line, and let the pull-request body show the type before anything is published.
18
18
 
@@ -20,13 +20,13 @@ A wrong-but-stated recommendation is cheaper to correct than a decision handed b
20
20
 
21
21
  The gate and the marker are one rule seen twice. A menu that passes the gate is one that the markers could not settle or one that the developer authorizes, and the agent may still have a strong evidence-based ranking inside an authorization menu, which is exactly when ■■■ is honest. A marker set below the strength actually available tells the developer nothing, and leaves them investigating every menu to find the few that are real forks.
22
22
 
23
- ## Why a manufactured bullet costs more than none
23
+ ## Why a manufactured bullet is worse than none
24
24
 
25
25
  Bullets in an option list are weighted equally by construction; the format does not provide a minor bullet. Placing a line under `➖` asserts that the reader should weigh it, so they spend attention deciding how much it matters. For a manufactured con the answer is none, and the reader spends that attention before discovering that the con is worthless. That makes it waste rather than merely noise.
26
26
 
27
27
  The menu's existence also depends on the con: Because an option recommended without a drawback reads as a decision rather than an option, presenting a settled call as a fork requires inventing a drawback. A fabricated con is the sign that the gate above was skipped, not an independent formatting slip.
28
28
 
29
- When the honest cost is hard to find, that difficulty is itself evidence the option is strong. Spend the effort on finding the real cost or on omitting the bullet, never on manufacturing a plausible-sounding one.
29
+ When the honest drawback is hard to find, that difficulty is itself evidence the option is strong. Spend the effort on finding the real drawback or on omitting the bullet, never on manufacturing a plausible-sounding one.
30
30
 
31
31
  A menu that looks balanced when the options are not misreports the analysis: It tells the developer that the agent found a close call. The developer relies on the menu for objective advice, and an even-handed look is the opposite of that when one option is sound and the others are flawed. A con whose size the reader cannot see does the same damage in a smaller form, since the reader has to investigate to learn that it is trivial. Both failures recur after being named, because a menu with a con on every option looks diligent while it misleads.
32
32
 
@@ -51,7 +51,7 @@ Same surface phrasing, two correct renderings:
51
51
  > 1. ■■□ Close #412 as superseded by this change:
52
52
  > - ➖ the alias request closes with it, and it is not tracked by any other ticket
53
53
  > 2. ■■□ Leave #412 open, retitled to the alias:
54
- > - ➖ its 30 comments about the shipped flag bury the one about the alias
54
+ > - ➖ its 30 comments about the flag that this change adds bury the one about the alias
55
55
 
56
56
  Both "yes" (close) and "no" (retitle) are concrete agent actions with their own tradeoffs. The decision edits a remote ticket, so it is in the gated class and is asked whatever the markers say.
57
57
 
@@ -88,5 +88,5 @@ Multiple questions in one response (Q1/Q2 identifiers):
88
88
  1. ■■□ Co-locate with its only consumer:
89
89
  - ➕ the check changes together with the form that it validates
90
90
  2. ■■□ Place in the shared utility package:
91
- - ➕ the billing package needs the same check once #588 lands
91
+ - ➕ the billing package needs the same check once #588 is merged
92
92
  ```
@@ -4,7 +4,7 @@ Spike work is an investigation, not a build: Its artifacts answer questions and
4
4
 
5
5
  The ticket is the record of a spike, and the findings artifact is its log: The artifact holds the full findings and the evidence, and the ticket holds what the spike concluded. See [Purpose](artifact-conventions.md#purpose) for the artifact directory's role.
6
6
 
7
- Spike mode is entered explicitly (the invocation signals it) and is not auto-detected from ticket type, label, or title. Everything outside the two templates below (source resolution, staleness, Q&A, saving) is unchanged from the feature flow.
7
+ Spike mode is entered explicitly (the invocation signals it) and is not auto-detected from ticket type, label, or title. {skill?:start-ticket} signals it for a ticket or a plan written in the shape of a template below, per [entry points](entry-points.md). Everything outside the two templates below (source resolution, staleness, Q&A, saving) is unchanged from the feature flow.
8
8
 
9
9
  The concision and content-placement doctrines for feature tickets and plans apply unchanged; only what differs for a spike is stated here.
10
10
 
@@ -44,7 +44,7 @@ Deliverable: a findings & recommendation artifact, and the closing post on this
44
44
 
45
45
  `Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
46
46
 
47
- Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved via the standard `save-artifact` conventions (without a dedicated artifact type), and the [closing post](#closing-post) on the ticket.
47
+ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved as a `spike-findings` artifact via the standard `save-artifact` conventions, and the [closing post](#closing-post) on the ticket.
48
48
 
49
49
  ## Spike plan template
50
50
 
@@ -86,6 +86,8 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
86
86
 
87
87
  Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior, and it names the [closing post](#closing-post); a step does not have a test or documentation criterion.
88
88
 
89
+ The `investigate-spike` skill carries out a spike plan.
90
+
89
91
  ## Closing post
90
92
 
91
93
  The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
@@ -95,10 +97,18 @@ The agent that ends a spike posts its conclusion on the ticket as a comment. The
95
97
  - The counts and the proposed groupings, when the spike produced them.
96
98
  - Links to the published page, when the spike published one, and to the findings artifact, with the artifact's path written `~/`-relative, so that the post does not publish a home-directory path.
97
99
 
98
- Offer the post as an item in the closing action-items block, show its body, and post it only on consent: It is a remote write, and the developer is the one who can tell whether a finding is fit for the ticket's tracker. When the session does not have a ticket, do not offer it.
100
+ The skill that ends the spike offers the post. When the findings leave an item without a disposition, the triage round that disposes of them on the same ticket ends the spike: `triage-spike-findings` offers the post, and the skill that produced the findings names the triage as its next step without offering the post, which could not yet answer the decisions to enable. When the findings leave nothing to triage, the skill that produced them offers it. A follow-up triage ticket for a later batch does not take a closing post, because its dispositions comment is its record; the post on the original ticket names the follow-ups.
101
+
102
+ Offer the post as an item in the closing action-items block of that skill, show its body, and post it only on consent: It is a remote write, and the developer is the one who can tell whether a finding is fit for the ticket's tracker. When the session does not have a ticket, do not offer it.
99
103
 
100
104
  Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the post's first line, so that a rerun does not post it twice.
101
105
 
106
+ ## Findings batches
107
+
108
+ A batch is the set of items that one triage round inventories: the proposals, findings, and ideas of a findings artifact, with a grouping counted as one item. A batch holds at most 10 items, so that the developer can review it in one sitting.
109
+
110
+ Each batch has a ticket of its own, which covers the assessment that produced the batch and the triage round that disposes of it, so the ticket's [closing post](#closing-post) follows the triage round. An assessment that spans more than one unit is an umbrella with one child per unit, each child covering that unit's assessment and triage round and blocked by the child before it, so that each round runs after the earlier rounds have posted their dispositions and can read them. A findings artifact that holds more than 10 items is triaged in several batches, each on its own ticket, as `triage-spike-findings` states.
111
+
102
112
  ## Aligning a spike
103
113
 
104
114
  When `align-ticket-with-implementation` reconciles a spike, the branch's "implementation" is the findings: Reconcile whether the investigation answered its questions and reached a recommendation, not whether the branch met acceptance criteria. Align the ticket's questions and decisions to what the investigation actually concluded.
@@ -9,7 +9,7 @@ Resolve a ticket source argument into ticket content and metadata. Skills that a
9
9
  | URL to a known platform (GitHub, Jira, etc.) | Use the platform CLI or a connected read tool if available; otherwise, fetch the URL content |
10
10
  | Other URL | Fetch the URL content |
11
11
  | Shorthand reference (`#99`, `issue 99`, `GitHub issue #99`) | Resolve platform (see below), then fetch per [platform-specific fetch](#platform-specific-fetch) |
12
- | File path | Read the file |
12
+ | File path | Read the file, then read its remote comments per [Comments](#comments) |
13
13
  | Plain text | Use as-is |
14
14
  | _(no source provided)_ | Auto-resolve from environment (see [auto-resolve](#auto-resolve)) |
15
15
 
@@ -66,10 +66,10 @@ Determine which platform `#99` refers to using the [platform resolution cascade]
66
66
  ### GitHub
67
67
 
68
68
  ```
69
- gh issue view --json number,title,body,labels,updatedAt {number}
69
+ gh issue view --json number,title,body,comments,labels,updatedAt {number}
70
70
  ```
71
71
 
72
- Skills may request a subset of these fields. The `updatedAt` field is needed by skills that perform temporal analysis (e.g., staleness checks) and may be omitted by skills that only need the ticket content.
72
+ Skills may request a subset of these fields, and a subset that includes `body` also includes `comments`. The `updatedAt` field is needed by skills that perform temporal analysis (e.g., staleness checks) and may be omitted by skills that only need the ticket content.
73
73
 
74
74
  ### Jira
75
75
 
@@ -89,6 +89,12 @@ Read the ticket body with the default view, which renders the description as tex
89
89
  acli jira workitem view {key}
90
90
  ```
91
91
 
92
+ The view does not include the comments. Read them with a second call, which also renders as text, and treat its non-zero exit as the view's:
93
+
94
+ ```
95
+ acli jira workitem comment list --key {key} --paginate
96
+ ```
97
+
92
98
  When the source is a Jira URL rather than a key, the key is its `PROJECT-NUMBER` segment, which is the final segment of a `/browse/` URL.
93
99
 
94
100
  When a skill needs structured metadata, such as the `updated` timestamp for a staleness check, add `--json --fields '*navigable,-description'`. The `--json` flag returns the raw REST v3 response, in which the description is Atlassian Document Format rather than Markdown, so exclude it there and take the body from the default view. First-time setup is `acli jira auth login --web`, a browser flow that does not mint an API token.
@@ -98,12 +104,22 @@ When a skill needs structured metadata, such as the `updated` timestamp for a st
98
104
  - **Takes an issue URL**: Pass the ticket URL. Prefer this shape when both are connected, since it does not need site resolution.
99
105
  - **Takes an issue key and a cloud ID**: Resolve the cloud ID first, from the same server's tool listing accessible Atlassian sites. It is the `id` of the site whose URL matches the ticket URL's host, or of the sole site listed when the ticket URL is not known. If neither settles it, ask the user which site hosts the ticket. Resolve it once and reuse it for the rest of the session.
100
106
 
107
+ A tool of either shape that takes a field list is asked for the `comment` field with the issue; one that returns every field does not need it.
108
+
101
109
  **A client that the machine adds.** {skill?:update-jira-ticket} lists any Jira client that this machine adds to the cascade, with the sites that it can access and its rank. Read through it as its entry states.
102
110
 
103
111
  **Last resort.** When no client can read the ticket and `check-site` reported a mismatch, report the wrong site rather than a missing ticket: Repeat the helper's stderr line, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine. When no client is available, present the Jira key and ask the user for the ticket content. When `ticket.base_url` is configured, the ticket URL is reconstructed from the base and `ticket_id` (per [auto-resolve](#auto-resolve) step 4d), so it does not have to be supplied or re-pasted. A caller with a sound default source may substitute it for that prompt, as [When auto-resolve fails](#when-auto-resolve-fails) allows.
104
112
 
105
113
  The stored URL applies throughout: A Jira ticket URL resolved once is reused on later sessions, and it is invalidated like any other stored URL when it does not yield the expected ticket (see [Stored ticket URL](#stored-ticket-url)). A site mismatch does not invalidate the stored URL, because it does not show that the ticket is missing.
106
114
 
115
+ ## Comments
116
+
117
+ A ticket's comments are part of its content: A comment can record an assessment, a decision, a scope change, or a correction that the body does not contain. Both platform fetches above return them oldest first.
118
+
119
+ **The body stays the ticket of record.** A comment that extends or contradicts the body is a divergence. Report it through the divergence report that the reading skill already makes, and when the skill does not make one, name the comment and how it diverges in the skill's own output. Never apply such a comment silently, and never ignore it.
120
+
121
+ **A file.** A ticket artifact copies the body at one moment, so a comment posted after the copy is missing from it. When the file's frontmatter names a `ticket_ref`, read that remote ticket's comments per [platform-specific fetch](#platform-specific-fetch), as [Open blockers](#open-blockers) reads its blockers. A file without a `ticket_ref` does not have any comments to read.
122
+
107
123
  ## Open blockers
108
124
 
109
125
  A ticket's open blockers are the tickets recorded natively as blocking it that are not yet done. Read them each time a skill resolves the ticket, even when the ticket is already in context, because a blocker can close or appear during a session.
@@ -118,7 +134,7 @@ Name a blocker `#N` when its URL has the same `owner/repo` as the ticket's, and
118
134
 
119
135
  **Jira.** Read the links through the Jira clients that [platform-specific fetch](#platform-specific-fetch) ranks, after the same site check: `acli jira workitem view {key} --json --fields issuelinks`, or a connected read tool asked for the `issuelinks` field. A blocker is a link whose `type.name` is `Blocks`, or whose `type.inward` reads `is blocked by`, and that has an `inwardIssue`. It is open while `inwardIssue.fields.status.statusCategory.key` is not `done`. Name it by its key and `fields.summary`.
120
136
 
121
- **A file.** A ticket artifact copies a remote ticket, so a ticket that resolved from a file is checked against the remote ticket that its frontmatter `ticket_ref` names, resolved per [shorthand reference resolution](#shorthand-reference-resolution). A file without a `ticket_ref` is not checked.
137
+ **A file.** A ticket artifact copies a remote ticket, so a ticket that resolved from a file is checked against the remote ticket that its frontmatter `ticket_ref` names, resolved per [shorthand reference resolution](#shorthand-reference-resolution). A file without a `ticket_ref` is not checked. [Comments](#comments) reads the same remote ticket's comments.
122
138
 
123
139
  **Other sources.** A ticket that resolved from plain text or from another platform is not checked, and the skill says nothing about blockers. Because a project hosted on Bitbucket keeps its tickets in Jira, its tickets are checked as Jira tickets.
124
140
 
@@ -174,6 +190,7 @@ After resolution, store the following metadata for use by the calling skill:
174
190
  - **Issue number**: The numeric identifier, if applicable
175
191
  - **Last-updated date**: The ticket's last-modified timestamp, if available from the platform
176
192
  - **Ticket content**: The title, body, labels, and any other retrieved fields
193
+ - **Comments**: Each comment's author, date, and body, oldest first, read per [Comments](#comments)
177
194
  - **Open blockers**: For a skill that checks them, each open blocker's reference and title, read per [Open blockers](#open-blockers)
178
195
  - **Ticket URL**: Persisted across sessions in the branch manifest's `ticket_url` field, written through the deriver's mutation flags; see [Stored ticket URL](#stored-ticket-url)
179
196
 
@@ -125,7 +125,7 @@ For a subject not matched by the template, the run reports `{"matched":false}` a
125
125
 
126
126
  **Under a template that does not name `{ticket_ref}`, the bundle strips one first.** The bundle removes three leading forms before the match: `## `, `#123 ` (with an optional `.1` or `-1` suffix), and `ABC-123 `. These are the forms that release-kit strips, which lets a commit template that does not name `{ticket_ref}` read a subject that contains one.
127
127
 
128
- **When a parse could read a group as present or absent, present wins.** This is release-kit's reading, and it makes `agents|feat: Add foo` parse as scoped and typed rather than as a bare title. See [What the grammar does not support](#what-the-grammar-does-not-support) for the cost.
128
+ **When a parse could read a group as present or absent, present wins.** This is release-kit's reading, and it makes `agents|feat: Add foo` parse as scoped and typed rather than as a bare title. See [What the grammar does not support](#what-the-grammar-does-not-support) for the misreadings that this allows.
129
129
 
130
130
  The run refuses a surface whose template is empty, since there is nothing to read the subject through, and refuses if the taxonomy cannot be read.
131
131
 
@@ -499,7 +499,7 @@ node {harness_home_dir}/scripts/describe-change.mjs resolve-scopes \
499
499
 
500
500
  **`path_scopes` maps each path as given to its scope**, under the spelling that the invocation passed, so a caller can look a result up by the path that it asked about. **`scopes` is the sorted set** of the scopes that those paths name between them.
501
501
 
502
- **The derivation**: `@williamthorsen/nmr/workspace` resolves the repository root's workspace directories, honoring the `packages` patterns that `pnpm-workspace.yaml` declares, negative patterns included; each is named by its basename. The repository adds scope directories of its own under `project.scopes` in its `.agents/preferences.yaml`, each named by its `name` or else by its basename. A path's scope is the name of the longest of those directories that contains it, so a nested directory wins over the one enclosing it, whether either is a package or a declared directory. A path outside every scope directory resolves to `root`.
502
+ **The derivation**: `@williamthorsen/nmr/workspace` resolves the repository root's workspace directories, honoring the `packages` patterns that `pnpm-workspace.yaml` declares, negative patterns included; each is named by its basename. The repository root is never one of them, even when `pnpm-workspace.yaml` declares it as a package (`'.'`), so a path in a root package resolves to `root` rather than to the checkout directory's name. The repository adds scope directories of its own under `project.scopes` in its `.agents/preferences.yaml`, each named by its `name` or else by its basename. A path's scope is the name of the longest of those directories that contains it, so a nested directory wins over the one enclosing it, whether either is a package or a declared directory. A path outside every scope directory resolves to `root`.
503
503
 
504
504
  ```yaml
505
505
  project:
@@ -509,7 +509,7 @@ project:
509
509
  name: ios
510
510
  ```
511
511
 
512
- **A declared directory owns a scope without becoming a workspace**, so a deliverable that is not a Node package, such as a SwiftPM app, can own one without a placeholder manifest that nmr and release-kit would then act on. A declared directory that is also a package directory takes its declared name. Only the project preferences file declares scopes; `project.scopes` in the global file does not have any effect. An entry that is not a mapping, that does not have a string `path`, that has a `name` that is not a non-empty string, or whose path is absolute, outside the repository, missing, or not a directory is skipped with a warning, and a `project.scopes` that is not a list is ignored with one.
512
+ **A declared directory owns a scope without becoming a workspace**, so a deliverable that is not a Node package, such as a SwiftPM app, can own one without a placeholder manifest that nmr and release-kit would then act on. A declared directory that is also a package directory takes its declared name. Only the project preferences file declares scopes; `project.scopes` in the global file does not have any effect. An entry that is not a mapping, that does not have a string `path`, that has a `name` that is not a non-empty string, that names the repository root without a `name`, or whose path is absolute, outside the repository, missing, or not a directory is skipped with a warning, and a `project.scopes` that is not a list is ignored with one.
513
513
 
514
514
  **A repository without scope directories yields `root` for every path.** A root that is not a pnpm workspace and does not declare scopes discovers none, as does one whose patterns do not match any directory, and this is how a consumer detects that the repository does not have a scope vocabulary. A repository on another package manager reads the same way unless it declares scopes.
515
515
 
@@ -614,7 +614,7 @@ A template that round-trips every well-formed record but loses a token for some
614
614
 
615
615
  **Value-dependent ambiguity passes the check.** The check runs over well-formed values, so it accepts a template whose ambiguity depends on what a value happens to contain. Under `[{ticket_ref} ]{title}`, the title `#466 Add foo` reads back as ticket reference `#466` and title `Add foo`. Because that matches how release-kit reads it, the behavior is compatibility rather than a defect, but a caller that keeps both halves separately should not rely on a round trip to recover them.
616
616
 
617
- The same cost applies to the piped-scope convention, in which a present group wins. `Rename kb|docs: the shared layer` reads back as scope `Rename kb`, type `docs`, title `the shared layer`. The type check prevents the misreading when the type is nonsense, so `Support a|b: syntax` is unmatched, but not when the type is real.
617
+ The same misreading affects the piped-scope convention, in which a present group wins. `Rename kb|docs: the shared layer` reads back as scope `Rename kb`, type `docs`, title `the shared layer`. The type check prevents the misreading when the type is nonsense, so `Support a|b: syntax` is unmatched, but not when the type is real.
618
618
 
619
619
  ## Scope values
620
620
 
@@ -4,10 +4,11 @@ node {harness_home_dir}/scripts/describe-change.mjs render-titles \
4
4
  --scope "{scope}" \
5
5
  --type "{type}" \
6
6
  --ticket-ref "{ticket_ref}" \
7
+ --project-root "{project_root}" \
7
8
  | python3 -c "import sys,json; print(json.load(sys.stdin).get('commit_title',''))"
8
9
  ```
9
10
 
10
- Pass `--ticket-ref` from the bundled session-context deriver so that a project whose `commit.title_format` references `{ticket_ref}` renders the ref. Omit any flag whose value is empty or null, `--ticket-ref` included when session context reports it as `null`.
11
+ Pass `--ticket-ref` from the bundled session-context deriver so that a project whose `commit.title_format` references `{ticket_ref}` renders the ref. Omit any flag whose value is empty or null, `--ticket-ref` included when session context reports it as `null`. Pass `--project-root` only when the invoking skill names the directory in which it works: The renderer reads `commit.title_format` from the project that contains the directory in which it runs, unless the flag names another.
11
12
 
12
13
  Parse the output with a JSON parser (`python3` above; `jq -r '.commit_title'` if `jq` is available) rather than `grep` or `cut`: A rendered title may contain backslash-escaped double quotes, which a regex extractor silently truncates.
13
14
 
@@ -16,12 +16,13 @@ Present all three options as a numbered list per [option format](#option-format)
16
16
 
17
17
  **One `➕` line is mandatory rather than omitted.** When Refine plan is the selected option, it must include a `➕` line naming the specific unsettled decision that the pass would raise (rule 1). The line names an open decision, never a reassurance about work already done: "a refine pass is the cheap way to find out whether I missed something" is the shape that this requirement exists to forbid. When Split the ticket is the selected option, it must include a `➕` line naming the plan's size and the pieces (rule 2). Selecting either without its line is a defect: If the line cannot be written, the rule did not match and the cascade continues.
18
18
 
19
- **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff, and `implement-plan` reads only the feature shape. Render option 3 as 🔬 Investigate, without invoking a skill; the agent works the investigation steps directly and ends the run with the plan's `## Deliverable`, which includes offering the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and making it on consent. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
19
+ **Spike plans.** A spike plan has `## Investigation steps` rather than `## Tasks` (see [spike conventions](../_data/spike-conventions.md)). It is carried out to produce findings rather than implemented to produce a diff. Render option 3 as 🔬 Investigate, invoking {skill?:investigate-spike} with plan: {plan_path}, ticket: {ticket_source}; that skill works the investigation steps and ends the run with the plan's `## Deliverable`: the offer of the [closing post](../_data/spike-conventions.md#closing-post) on the ticket or, when the findings propose work, the recommendation of the triage round that offers it. Option 1 renders unchanged. Option 2 renders at □□□ with the `➖` that a spike produces findings rather than pieces that ship. In the recommendation rules below, rule 2 never matches on a spike plan, so Investigate is the fallthrough whenever rule 1 does not match.
20
20
 
21
21
  Options that invoke a skill include context-clearing guidance:
22
22
 
23
23
  - **Refine plan**: Prepend "Clear context, then..." because the plan artifact is self-contained; prior conversation wastes tokens and can introduce bias.
24
24
  - **Split the ticket**: No "Clear context" prefix, and no pasted invocation line; the split runs in this session because the library doesn't have a skill for it, and it cuts the pieces from the saved plan. See [Splitting the ticket](#splitting-the-ticket).
25
+ - **Investigate**: No "Clear context" prefix, for the same reason as Implement: `investigate-spike` re-resolves the plan and ticket from the environment.
25
26
  - **Implement**: No "Clear context" prefix. The ticket and plan are self-contained, so `implement-plan` works the same in this session or in a fresh one, and clearing gains nothing: Unlike a refine or review pass, implementation is not harmed by sharing the planner's view. The user can also paste the same line into a fresh session, or into the other harness with its own skill sigil, in which the skill re-resolves the plan and ticket from the environment.
26
27
 
27
28
  Example (rendered for the default case, in which the recommendation rules below select Implement):
@@ -40,7 +41,7 @@ Skill names for each option:
40
41
 
41
42
  - 🧠 **Refine plan** -> `refine-plan`
42
43
  - ✂️ **Split the ticket** -> `{skill:create-ticket}`, once per piece, in this session
43
- - 🚀 **Implement** -> `implement-plan`; on a spike plan the option is 🔬 **Investigate** and does not invoke a skill
44
+ - 🚀 **Implement** -> `implement-plan`; on a spike plan the option is 🔬 **Investigate** -> `investigate-spike`
44
45
 
45
46
  ### Recommendation rules
46
47
 
@@ -92,7 +93,7 @@ Each skill supplies its own recommendation context (e.g., whether the plan was d
92
93
 
93
94
  **Save the first piece's plan.** With two pieces, save the first piece's plan in the originating ticket's directory per `{skill:save-artifact}`. Its timestamp is later than the approved plan's, so `implement-plan` resolves it rather than the unsplit plan.
94
95
 
95
- **Report.** Report the ticket references and the plan paths. Choose each ticket's entry point from what its artifacts settle: `{skill?:design-and-plan}` when the piece's design needs a closer look; `{skill?:plan}` when the ticket is ready but does not have a plan; `{skill?:refine-plan}` when its plan leaves a decision unsettled, by the test in rule 1 above; `{skill?:implement-plan}` otherwise, which is the default for a plan cut from an approved one.
96
+ **Report.** Report the ticket references and the plan paths. Every piece enters at `{skill?:start-ticket}`, invoked without arguments, which chooses the skill that opens the work from the piece's artifacts per [entry points](../_data/entry-points.md). A fact that the choice needs and that the artifacts do not state belongs in the piece's ticket or plan, not in its prompt.
96
97
 
97
98
  <!-- include: split-launch-prompts.md / -->
98
99
 
@@ -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 holds less of the evidence than the agent, so handing the doubt back produces a worse-informed answer.
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 hold any evidence
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; hold 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 hold any evidence. Verification is never in the gated class: Run a check that a command, a test, or a browser could settle.
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 these costs 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.
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 cost, render the options unmarked, and put the choice at the checkpoint.
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 holds, 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.
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, reach parity between options, or avoid looking one-sided; when the honest cost 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.
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 cost 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 `➖`.
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.
@@ -58,10 +58,12 @@
58
58
 
59
59
  **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
60
 
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.
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, 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
62
 
63
63
  **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
64
 
65
+ **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.
66
+
65
67
  **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
68
 
67
69
  **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.