codeassembly-guidance 0.1.0 → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +757 -0
- package/CHANGELOG.md +181 -0
- package/README.md +125 -95
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +2 -2
- package/content/_partials/code-style.md +1 -1
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +11 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
- package/content/guidance/rulebooks/commit-conventions.md +2 -2
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/shared/AGENTS.md +8 -0
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +97 -97
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/artifact-conventions.md +46 -14
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/design-priorities.md +3 -3
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +1 -1
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +19 -11
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +10 -10
- package/content/skills/_partials/next-steps-after-review.md +9 -9
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +5 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/capture-event/SKILL.md +2 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +24 -9
- package/content/skills/create-pr/SKILL.md +5 -5
- package/content/skills/create-ticket/SKILL.md +61 -16
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
- package/content/skills/design-and-plan/SKILL.md +13 -10
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +25 -21
- package/content/skills/index-prototypes/SKILL.md +85 -30
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +2 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +3 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
- package/content/skills/kb-retrieve-events/SKILL.md +1 -1
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
- package/content/skills/kb-update-events/SKILL.md +2 -2
- package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +4 -2
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +2 -0
- package/content/skills/streamline-guidance/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +22 -13
- package/content/skills/testing-conventions/SKILL.md +74 -7
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +2 -2
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +15 -11
- package/schemas/preferences.v1.json +29 -2
- package/schemas/work-types.v1.json +1 -1
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -103,6 +103,55 @@ it('processes user data correctly', () => {
|
|
|
103
103
|
});
|
|
104
104
|
```
|
|
105
105
|
|
|
106
|
+
## DOM environment
|
|
107
|
+
|
|
108
|
+
A test that renders into a DOM runs under happy-dom, which starts and runs faster than jsdom. Under Vitest, set `environment: 'happy-dom'` or open the file with the `// @vitest-environment happy-dom` pragma; under Jest, use the `@happy-dom/jest-environment` package. A test that constructs a window directly uses happy-dom's `Window` rather than `JSDOM`.
|
|
109
|
+
|
|
110
|
+
Use jsdom only for a test that depends on a behavior that happy-dom lacks, and name that behavior in a comment at the opt-in, so that a reader can check whether happy-dom has since gained it.
|
|
111
|
+
|
|
112
|
+
```typescript
|
|
113
|
+
// ✅ Good: The opt-in names what happy-dom lacks
|
|
114
|
+
// @vitest-environment jsdom
|
|
115
|
+
// happy-dom lacks <the behavior on which this test depends>.
|
|
116
|
+
|
|
117
|
+
// ❌ Avoid: jsdom by habit
|
|
118
|
+
// @vitest-environment jsdom
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
## External programs
|
|
122
|
+
|
|
123
|
+
The `testing-conventions` skill states the rule: Code calls an external program through an adapter, and its tests pass a fake. In TypeScript, the adapter is a type, the code takes it as a parameter whose default is the real adapter, and the test passes an object literal. Prefer the parameter to module mocking (`vi.mock`), which leaves the dependency out of the signature and lets the code keep calling the program directly.
|
|
124
|
+
|
|
125
|
+
```typescript
|
|
126
|
+
// ✅ Good: The code receives git, and the test supplies its answers
|
|
127
|
+
export interface Git {
|
|
128
|
+
listTrackedFiles(root: string): string[];
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export const realGit: Git = {
|
|
132
|
+
listTrackedFiles: (root) =>
|
|
133
|
+
execFileSync('git', ['ls-files'], { cwd: root, encoding: 'utf8' }).split('\n').filter(Boolean),
|
|
134
|
+
};
|
|
135
|
+
|
|
136
|
+
export function findSkillFiles(root: string, git: Git = realGit): string[] {
|
|
137
|
+
return git.listTrackedFiles(root).filter((path) => path.endsWith('/SKILL.md'));
|
|
138
|
+
}
|
|
139
|
+
|
|
140
|
+
it('returns only the tracked SKILL.md files', () => {
|
|
141
|
+
const git: Git = { listTrackedFiles: () => ['a/SKILL.md', 'a/notes.md'] };
|
|
142
|
+
expect(findSkillFiles('/repo', git)).toStrictEqual(['a/SKILL.md']);
|
|
143
|
+
});
|
|
144
|
+
|
|
145
|
+
// ❌ Avoid: The test builds a real repository to produce the same input
|
|
146
|
+
it('returns only the tracked SKILL.md files', () => {
|
|
147
|
+
execFileSync('git', ['init'], { cwd: scratch });
|
|
148
|
+
// ...write the files, then `git add` and `git commit`...
|
|
149
|
+
expect(findSkillFiles(scratch)).toStrictEqual(['a/SKILL.md']);
|
|
150
|
+
});
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
Only `realGit` has a test that runs git, and that test checks that `listTrackedFiles` parses the output of `git ls-files`.
|
|
154
|
+
|
|
106
155
|
## Console and stream output
|
|
107
156
|
|
|
108
157
|
The `testing-conventions` skill states the rule: A passing test prints nothing beyond the runner's report. These are the TypeScript techniques for applying it. Each helper restores what it replaced when its `using` scope ends.
|
|
@@ -120,7 +169,7 @@ it('if a deprecated option is passed, warns once', () => {
|
|
|
120
169
|
});
|
|
121
170
|
```
|
|
122
171
|
|
|
123
|
-
|
|
172
|
+
When the project does not depend on these packages, spy on the method with the runner, and restore the spy in `afterEach` or through the runner's `restoreMocks` option:
|
|
124
173
|
|
|
125
174
|
```typescript
|
|
126
175
|
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: update-jira-ticket
|
|
3
|
-
description: 'Use whenever creating or updating a Jira issue description or comment, whether through acli, a contentFormat-based tool (createJiraIssue taking description, editJiraIssue taking fields.description, both with contentFormat markdown/adf), or an HTML-based tool (create_jira_issue / update_jira_issue, taking description_html / comment_html). Jira stores a Markdown or HTML body with its task-list syntax escaped, so checklists go in as plain bullets on those surfaces and as real task items through acli. The HTML tools additionally need the bundled pre-flight checker to catch INVALID_INPUT triggers (composition rules, named entities, Confluence macros, multi-line <pre>, disallowed elements) before any MCP round-trip; the contentFormat tools take Markdown directly, and acli takes plain text or ADF and parses Markdown as wiki markup.'
|
|
3
|
+
description: 'Use whenever creating or updating a Jira issue description or comment, whether through acli, a contentFormat-based tool (createJiraIssue taking description, editJiraIssue taking fields.description, both with contentFormat markdown/adf), or an HTML-based tool (create_jira_issue / update_jira_issue, taking description_html / comment_html). Jira stores a Markdown or HTML body with its task-list syntax escaped, so checklists go in as plain bullets on those surfaces and as real task items through acli. The HTML tools additionally need the bundled pre-flight checker to catch INVALID_INPUT triggers (composition rules, named entities, Confluence macros, multi-line <pre>, disallowed elements) before any MCP round-trip; the contentFormat tools take Markdown directly, and acli takes plain text or ADF and parses Markdown as wiki markup. Also use to identify the Jira client for reading a ticket, including a client that the machine adds through the `jira-clients` guidance hook.'
|
|
4
4
|
user-invocable: true
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -10,7 +10,7 @@ The same constraint applies to creating a Jira issue and to updating one: Whatev
|
|
|
10
10
|
|
|
11
11
|
## Checklists
|
|
12
12
|
|
|
13
|
-
|
|
13
|
+
<!-- include: ../_partials/jira-task-list-flattening.md / -->
|
|
14
14
|
|
|
15
15
|
Native checkboxes exist only as ADF `taskList` / `taskItem` nodes, which makes the [ADF path](#adf-path) the one exception. A body submitted as ADF contains real task items and keeps them. That is not a reason to use ADF elsewhere: Because `contentFormat` applies to the whole field rather than a section of it, a checklist never justifies authoring an entire description as ADF on a client that takes Markdown.
|
|
16
16
|
|
|
@@ -21,16 +21,28 @@ Artefact-sourced content is in scope, and it is the most common source of unconv
|
|
|
21
21
|
Match your client to one of these shapes:
|
|
22
22
|
|
|
23
23
|
- **`acli`**: `acli jira workitem create` / `acli jira workitem edit`, whose `--description` and `--description-file` are documented as plain text or ADF. A Markdown body is not merely left unrendered there: It is parsed as Jira wiki markup, so headings become nested ordered list items and punctuation comes back backslash-escaped. → Follow the [ADF path](#adf-path).
|
|
24
|
-
- **`contentFormat`-based tool**, e.g. `createJiraIssue` / `editJiraIssue` (Atlassian Rovo): Takes the description together with `contentFormat: "markdown" | "adf"` -- top-level on `createJiraIssue`, under `fields` on `editJiraIssue`.
|
|
24
|
+
- **`contentFormat`-based tool**, e.g. `createJiraIssue` / `editJiraIssue` (Atlassian Rovo): Takes the description together with `contentFormat: "markdown" | "adf"` -- top-level on `createJiraIssue`, under `fields` on `editJiraIssue`. Doesn't offer an HTML surface. → Follow the [Markdown path](#markdown-path).
|
|
25
25
|
- **`description_html`-based tool**: `create_jira_issue` / `update_jira_issue` with `description_html` / `comment_html`. → Follow the [HTML path](#html-path).
|
|
26
26
|
|
|
27
27
|
If more than one is available, prefer the `contentFormat` tool: It takes Markdown directly, whereas `acli` needs ADF. Because the `contentFormat` tool needs a connected Jira server, `acli` is the fallback for a machine without one.
|
|
28
28
|
|
|
29
|
+
When the machine adds a client of its own, a section after this one describes it, with the sites to which it connects and where it ranks among these.
|
|
30
|
+
|
|
31
|
+
<!-- guidance-hook: jira-clients -->
|
|
32
|
+
|
|
29
33
|
## ADF path
|
|
30
34
|
|
|
31
35
|
Use this branch when the client is `acli`.
|
|
32
36
|
|
|
33
|
-
1. **
|
|
37
|
+
1. **Check `acli`'s active site before the first `acli` call.** `acli` acts on whichever site it is signed in to. Compare that site with the ticket's host, taken from the ticket URL, or from `ticket_base_url` when the ticket URL is not known:
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket URL or ticket_base_url}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
The helper prints `{"activeSite": ..., "targetSite": ..., "match": ...}` and exits non-zero unless the two match. On a mismatch, use another client from [Identify your client](#identify-your-client); when none remains, report the wrong site by repeating 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. A non-zero exit without JSON means that `acli` is unavailable. Skip the check when neither URL is known. `manage-jira-ticket.mjs create` runs the same check itself.
|
|
44
|
+
|
|
45
|
+
2. **Author Markdown, then convert it to ADF with the helper.** Prefer a local Markdown artefact when one exists; otherwise compose in Markdown and write it to a scratch file. Then run:
|
|
34
46
|
|
|
35
47
|
```bash
|
|
36
48
|
node {harness_home_dir}/scripts/manage-jira-ticket.mjs convert-body --body-file {absolute Markdown path} --out {absolute ADF path}
|
|
@@ -38,10 +50,10 @@ Use this branch when the client is `acli`.
|
|
|
38
50
|
|
|
39
51
|
Pass both paths as literal absolute paths, unquoted; the helper refuses a missing or empty body file. It writes the ADF document to `--out` and prints `{"adfPath": "..."}`. Pass that path to `--description-file`, or to `--body-file` for a comment. Never hand-write the ADF.
|
|
40
52
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
53
|
+
3. **Never pass Markdown to `--description` or `--description-file`.** `acli` parses it as Jira wiki markup, in which `#` opens an ordered list, so `## Problem` becomes a nested numbered item and every backtick, tilde, underscore, and bracket comes back backslash-escaped. Because the command reports success, only reading the work item back reveals the damage.
|
|
54
|
+
4. **Reserve plain text for a body without any structure to lose**, such as a one-line comment. Submit anything containing headings, lists, or inline marks as ADF.
|
|
55
|
+
5. **Keep your checkboxes**, per [Checklists](#checklists). The helper converts task-list syntax to `taskList` / `taskItem` nodes, so leave it in the Markdown rather than flattening it to plain bullets.
|
|
56
|
+
6. **Do not sanitize.** The HTML allowlist, the composition rules, and the pre-flight checker under [HTML path](#html-path) **do not apply** here, and you must **not** run `update-jira-ticket.mjs`, the HTML checker. `manage-jira-ticket.mjs` is the converter.
|
|
45
57
|
|
|
46
58
|
## Markdown path
|
|
47
59
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
`)}
|
|
8
|
-
`)
|
|
9
|
-
`)
|
|
3
|
+
var I=Object.defineProperty;var s=(e,r)=>I(e,"name",{value:r,configurable:!0});import m from"node:process";function x(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}s(x,"isError");function c(e){try{return x(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}s(c,"describeError");import{realpathSync as y}from"node:fs";import T from"node:process";import{fileURLToPath as $}from"node:url";function h(e,r){let t=T.argv[1];if(t===void 0)return!1;try{return y($(e))===y(t)}catch(n){return T.stderr.write(`${r}: warning: could not determine entry point: ${c(n)}
|
|
4
|
+
`),!0}}s(h,"isEntryPoint");async function w(e){let r=[];for await(let t of e){if(!Buffer.isBuffer(t))throw new TypeError("readAll: expected Buffer chunks (stream must be in binary mode)");r.push(t)}return Buffer.concat(r).toString("utf8")}s(w,"readAll");var O=new Set(["br","hr","img","input","meta","link","area","base","col","embed","source"]);function E(e){let r=[],t=e.length,n=0,o=0;for(;n<t;){let i=e[n],a=e[n+1]??"";if(i==="<"&&M(a)){n>o&&r.push({type:"text",value:e.slice(o,n),offset:o});let f=_(e,n);r.push(f.token),n=f.nextIndex,o=n}else n+=1}return o<t&&r.push({type:"text",value:e.slice(o,t),offset:o}),r}s(E,"tokenize");function M(e){return e==="/"||e>="a"&&e<="z"||e>="A"&&e<="Z"}s(M,"isTagStartChar");function _(e,r){let t=e[r+1]==="/",n=r+(t?2:1),o=g(e,n,j),i=e.slice(n,o),a=i.toLowerCase();if(t){let F=v(e,o,">"),b=Math.min(F+1,e.length);return{token:{type:"close-tag",name:a,rawName:i,offset:r,raw:e.slice(r,b)},nextIndex:b}}let{attrs:f,selfClosing:l,end:p}=W(e,o),d=p<e.length?p+1:e.length,L=l||O.has(a);return{token:{type:"open-tag",name:a,rawName:i,attrs:f,selfClosing:L,offset:r,raw:e.slice(r,d)},nextIndex:d}}s(_,"parseTag");function W(e,r){let t=e.length,n=[],o=!1,i=r;for(;i<t;){i=k(e,i);let a=e[i];if(a===void 0||a===">")break;if(a==="/"){o=!0,i+=1;continue}let f=i;if(i=g(e,i,P),i===f){i+=1;continue}let l=e.slice(f,i).toLowerCase(),{value:p,next:d}=z(e,i);n.push({name:l,value:p}),i=d}return{attrs:n,selfClosing:o,end:i}}s(W,"parseAttributes");function z(e,r){let t=k(e,r);if(e[t]!=="=")return{value:null,next:t};t=k(e,t+1);let n=e[t];if(n==='"'||n==="'"){let a=t+1,f=v(e,a,n),l=f<e.length?f+1:e.length;return{value:e.slice(a,f),next:l}}let o=t,i=g(e,o,a=>!S(a)&&a!==">"&&a!=="/");return{value:e.slice(o,i),next:i}}s(z,"parseAttributeValue");function g(e,r,t){let n=e.length,o=r;for(;o<n;){let i=e[o];if(i===void 0||!t(i))break;o+=1}return o}s(g,"readWhile");function v(e,r,t){let n=e.length,o=r;for(;o<n&&e[o]!==t;)o+=1;return o}s(v,"readUntilChar");function k(e,r){return g(e,r,S)}s(k,"skipWhitespace");function j(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e===":"||e==="-"}s(j,"isNameChar");function P(e){return e>="a"&&e<="z"||e>="A"&&e<="Z"||e>="0"&&e<="9"||e==="-"||e==="_"||e===":"}s(P,"isAttrNameChar");function S(e){return[" "," ",`
|
|
5
|
+
`,"\r","\f"].includes(e)}s(S,"isWhitespace");function u(e,r){let t=1;for(let n=0;n<r&&n<e.length;n+=1)e[n]===`
|
|
6
|
+
`&&(t+=1);return t}s(u,"lineOf");function C(e,r){let t=[];for(let n of e)if(n.type==="open-tag")r(n,t),n.selfClosing||t.push(n);else if(n.type==="close-tag"){for(let o=t.length-1;o>=0;o-=1)if(t[o]?.name===n.name){t.length=o;break}}}s(C,"walkTokens");var B=new Set(["h1","h2","h3","h4","h5","h6","p","ul","ol","li","strong","em","code","a","blockquote","hr","br","table","thead","tbody","tr","th","td"]),A=new Set(["strong","em","a","strike","u","sub","sup"]),U=new Set(["amp","lt","gt"]);function Z(e,r){let t=[];return C(e,(n,o)=>{if(n.name==="code"){let i=o.find(a=>A.has(a.name));i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move the <code> outside <${i.name}>, or drop the inline mark.`})}else if(A.has(n.name)){let i=o.find(a=>a.name==="code");i&&t.push({rule:"composition-code-inline-mark",snippet:`${i.raw}...${n.raw}`,line:u(r,i.offset),fix:`Move <${n.name}> outside the <code>, or drop the inline mark.`})}}),t}s(Z,"compositionCodeInlineMarkRule");function V(e,r){let t=[],n=/&([a-zA-Z][a-zA-Z0-9]*);/g;for(let o of e)if(o.type==="text")for(let i of o.value.matchAll(n)){let a=i[1];if(a===void 0||U.has(a))continue;let f=o.offset+i.index;t.push({rule:"named-entity",snippet:i[0],line:u(r,f),fix:"Replace with literal Unicode (e.g., \u2014 for —, \u2026 for …, a regular space for )."})}return t}s(V,"namedEntityRule");function q(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(n.name.startsWith("ac:")||n.name.startsWith("ri:"))&&t.push({rule:"confluence-construct",snippet:n.raw,line:u(r,n.offset),fix:`Remove the <${n.rawName}> construct. Confluence storage-format elements do not have a Jira analogue.`});return t}s(q,"confluenceConstructRule");function D(e,r){let t=[];for(let[n,o]of e.entries())o.type!=="open-tag"||o.name!=="pre"||J(e,n)&&t.push({rule:"pre-multiline",snippet:o.raw,line:u(r,o.offset),fix:"Replace the multi-line <pre> with per-line <p><code>...</code></p>, or a single <p> using <br> separators."});return t}s(D,"preMultilineRule");function J(e,r){let t=1;for(let n=r+1;n<e.length;n+=1){let o=e[n];if(o===void 0)break;if(o.type==="open-tag"&&o.name==="pre"&&!o.selfClosing)t+=1;else if(o.type==="close-tag"&&o.name==="pre"){if(t-=1,t===0)return!1}else if(o.type==="text"&&o.value.includes(`
|
|
7
|
+
`))return!0}return!1}s(J,"hasNewlineInPre");function K(e,r){let t=[];for(let n of e)n.type==="open-tag"&&(B.has(n.name)||n.name.startsWith("ac:")||n.name.startsWith("ri:")||t.push({rule:"disallowed-element",snippet:n.raw,line:u(r,n.offset),fix:`Remove or replace <${n.rawName}>. The allowlist is documented in update-jira-ticket/SKILL.md.`}));return t}s(K,"disallowedElementRule");var N=[Z,V,q,D,K];function R(e){let r=E(e),t=N.flatMap(n=>n(r,e));return t.length===0?{ok:!0}:{ok:!1,findings:t}}s(R,"check");async function X(){try{let e=await w(m.stdin),r=R(e);m.stdout.write(`${JSON.stringify(r,null,2)}
|
|
8
|
+
`)}catch(e){let r=c(e);m.stderr.write(`update-jira-ticket: ${r}
|
|
9
|
+
`),m.exit(1)}}s(X,"main");h(import.meta.url,"update-jira-ticket")&&await X();
|
|
@@ -90,7 +90,7 @@ For each finding, assign one of these classes:
|
|
|
90
90
|
- What belongs in a README, and where the rest goes, is stated by {rulebook:readme-conventions}. Consult it before assigning a finding to the reference tier: A README's shape follows from what it describes, so the same finding is placed differently in a library's README and in a monorepo root's.
|
|
91
91
|
- A finding belongs in the ambient tier only when it is absent from the tool's own output _and_ the obvious action goes wrong without it. A command table restates `--help`; a directory listing restates `ls`. Both are reference at best, and reference material injected at launch goes stale silently, because nothing fails when it drifts.
|
|
92
92
|
- Do not duplicate general guidance. If a project-specific convention _extends_ a general one, include only the delta.
|
|
93
|
-
- When unsure about scope, place the finding on the recommended side provisionally and collect every ambiguous finding into one review at the gate below, as multiple-choice questions
|
|
93
|
+
- When unsure about scope, place the finding on the recommended side provisionally and collect every ambiguous finding into one review at the gate below, as multiple-choice questions when possible.
|
|
94
94
|
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
95
95
|
- Content that is obvious from reading the code (e.g., "this project uses TypeScript") does not add any value. Include only what would save an agent from a wrong assumption or a slow discovery.
|
|
96
96
|
|
|
@@ -163,7 +163,7 @@ Scan the baseline for a harness-scoped path and for any `<!-- rulebook:` marker.
|
|
|
163
163
|
Two tiers, because a mature file contains more claims than one exhaustive pass can cover. A 35-line file decomposes into dozens of independently checkable assertions, and one at the line budget into several hundred.
|
|
164
164
|
|
|
165
165
|
- **Tier 1: Every checkable token, exhaustively.** Paths, filenames, command strings, counts, package and symbol names. Drift appears in these tokens: a directory listing that has gained an entry, a count off by two, a tool named one hop from what runs.
|
|
166
|
-
- **Tier 2: Narrative claims, in the sections touched by the gap-scan window.**
|
|
166
|
+
- **Tier 2: Narrative claims, in the sections touched by the gap-scan window.** Audit unquantified prose only in the sections whose subject the repo has changed, not everywhere.
|
|
167
167
|
|
|
168
168
|
Check the claim, not the section. A stale listing looks entirely plausible and is wrong only once the directory is listed, so recognizing a section's shape is the signal to slow down rather than to move on.
|
|
169
169
|
|
|
@@ -6,6 +6,9 @@
|
|
|
6
6
|
_defaults:
|
|
7
7
|
permissionMode: bypassPermissions
|
|
8
8
|
|
|
9
|
+
disposition-challenger:
|
|
10
|
+
model: inherit
|
|
11
|
+
|
|
9
12
|
handoff-reviewer:
|
|
10
13
|
model: sonnet
|
|
11
14
|
|
|
@@ -17,3 +20,6 @@ plan-reviser:
|
|
|
17
20
|
|
|
18
21
|
prose-reviser:
|
|
19
22
|
model: inherit
|
|
23
|
+
|
|
24
|
+
usability-assessor:
|
|
25
|
+
model: inherit
|
|
@@ -6,6 +6,11 @@
|
|
|
6
6
|
_defaults:
|
|
7
7
|
tools: [bash, create_file, expand_code_chunks, expand_folder, grep, open_files]
|
|
8
8
|
|
|
9
|
+
# Rovo does not read a denylist, so the read-only grant is named here.
|
|
10
|
+
# `create_file` is dropped: The challenger returns text.
|
|
11
|
+
disposition-challenger:
|
|
12
|
+
tools: [bash, expand_code_chunks, expand_folder, grep, open_files]
|
|
13
|
+
|
|
9
14
|
# Rovo does not read a denylist, so the read-only grant is named here.
|
|
10
15
|
# `create_file` is dropped: The drafter returns text.
|
|
11
16
|
entry-drafter:
|
|
@@ -20,8 +25,8 @@ plan-reviewer: {} # inherits _defaults
|
|
|
20
25
|
|
|
21
26
|
plan-reviser: {} # inherits _defaults
|
|
22
27
|
|
|
23
|
-
# Edits prose in place and creates nothing: `create_file` is dropped, and `bash`
|
|
24
|
-
# not
|
|
28
|
+
# Edits prose in place and creates nothing: `create_file` is dropped, and `bash` is dropped too, because the
|
|
29
|
+
# reviser does not run any command.
|
|
25
30
|
prose-reviser:
|
|
26
31
|
tools: [expand_code_chunks, expand_folder, find_and_replace_code, grep, open_files]
|
|
27
32
|
|
|
@@ -29,3 +34,8 @@ prose-reviser:
|
|
|
29
34
|
# `create_file` is dropped: The assessor returns text.
|
|
30
35
|
ticket-assessor:
|
|
31
36
|
tools: [bash, expand_code_chunks, expand_folder, grep, open_files]
|
|
37
|
+
|
|
38
|
+
# Rovo does not read a denylist, so the read-only grant is named here. The subagent is dispatched only by the
|
|
39
|
+
# Claude-only `assess-usability`, so a lens never runs under this grant.
|
|
40
|
+
usability-assessor:
|
|
41
|
+
tools: [bash, expand_code_chunks, expand_folder, grep, open_files]
|
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: canary
|
|
3
3
|
description: Deployment canary for the declared-subagent mechanism; not meant to be invoked.
|
|
4
|
+
standalone: exercises the declared-subagent mechanism rather than doing work of its own
|
|
4
5
|
tools: [Read]
|
|
5
6
|
---
|
|
6
7
|
|
|
7
8
|
# Canary
|
|
8
9
|
|
|
9
|
-
This subagent exists to prove that declared subagents deploy end-to-end. It doesn't have any consumers in this library and is never dispatched. Its body deliberately exercises the harness transform so that the deployed file is a real specimen:
|
|
10
|
+
This subagent exists to prove that declared subagents deploy end-to-end. It doesn't have any consumers in this library and is never dispatched. Its body deliberately exercises the harness transform so that the deployed file is a real specimen: The transform rewrites a `{tool:Read}` placeholder to the harness-native tool name and a `{harness_home_dir}` reference to the harness home path.
|
|
10
11
|
|
|
11
12
|
Read configuration from `{harness_home_dir}/skills/_data/` if you ever need it, using the {tool:Read} tool.
|
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: disposition-challenger
|
|
3
|
+
description: Argue against every disposition and grade that a triage of findings recommends, from the findings, the recommendations, and the repository alone. Returns one challenge per item and does not write any file.
|
|
4
|
+
disallowedTools: Edit, NotebookEdit, Task, Write
|
|
5
|
+
maxTurns: 80
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Disposition challenger
|
|
9
|
+
|
|
10
|
+
You read a findings artifact and the recommendations that a triage made on it, and you argue against each one. You have not seen the session that made them, and you cannot ask its author: Your value is that you have only the findings, the recommendations, and the repository. You return text, and you do not write any file.
|
|
11
|
+
|
|
12
|
+
## Your assignment
|
|
13
|
+
|
|
14
|
+
Your dispatch contains three scalars:
|
|
15
|
+
|
|
16
|
+
- **`findings`**: The path of the findings artifact. Read it in full.
|
|
17
|
+
- **`recommendations`**: The path of the recommendations file: one line per item, with its id, title, disposition, confidence, value, and reason.
|
|
18
|
+
- **`root`**: The repository root, against which every path in the findings is resolved, and in which `gh` reads the tracker.
|
|
19
|
+
|
|
20
|
+
For each item, find the strongest argument against its disposition and against each grade, check the claim on which the recommendation rests, and propose the change that you would make. The grades are defined as follows:
|
|
21
|
+
|
|
22
|
+
- **Confidence** states advisability: `high` is clearly worth doing, `medium` is worth doing but arguable, `low` is not worth a ticket now. A borderline item takes the lower grade. Only an item graded `high` or `medium` gets a ticket.
|
|
23
|
+
- **Value** states how much the item matters: `must-have`, `should-have`, `nice-to-have`, `questionable`.
|
|
24
|
+
|
|
25
|
+
The dispositions are `ticket` (a new ticket under the triage's umbrella), `comment` (a note on an existing issue), `merge` (folded into another item's ticket), and `drop`.
|
|
26
|
+
|
|
27
|
+
<HARD-GATE>
|
|
28
|
+
Never write to the tracker: Do not comment, edit, label, close, or create anything, through `gh` or any other means. Run only `gh` commands that read.
|
|
29
|
+
|
|
30
|
+
Never write to the working tree or to git: Do not create, edit, or delete a file, and do not run a git command that changes a ref, the index, or the working tree.
|
|
31
|
+
</HARD-GATE>
|
|
32
|
+
|
|
33
|
+
## Method
|
|
34
|
+
|
|
35
|
+
Work in rounds, where a round is one turn of tool calls. Batch every read and check that does not depend on another into the same round: Read `AGENTS.md`, the findings, and the recommendations together in the first round, then verify many items per round. Your verification budget is 4 rounds plus 1 per item, capped at 30. Count the items as soon as you have read the recommendations, count the rounds against that budget as you go, and when it is spent, stop and write your report. The report is your only output, and a challenge that stops before writing it delivers nothing. Mark each item that you did not reach `Unverified` in its `Evidence` line.
|
|
36
|
+
|
|
37
|
+
For each item:
|
|
38
|
+
|
|
39
|
+
1. **Check the claim.** Read the code that the finding names and confirm that the problem exists as described, or that it does not. Search the open issues with `gh issue list --search` and read the candidates with `gh issue view`: An item that an open issue already covers is a `comment` or a `drop`, not a `ticket`, and a `comment` whose issue is closed or does not cover it is wrong.
|
|
40
|
+
2. **Argue against the disposition.** Ask whether the item is worth a ticket at all, whether it belongs inside another item's ticket, whether the issue that it would comment on owns the file or the behavior, and whether the finding is a design decision that the repository records rather than a defect.
|
|
41
|
+
3. **Argue against each grade.** Ask what makes the item less advisable than its confidence says, and less important than its value says: the reach of the problem, the cost of the fix, a decision that already settled it, a user that it never affects. Argue the grade up when the evidence supports that instead.
|
|
42
|
+
4. **Propose.** State `keep` when every argument fails on the evidence, and otherwise the disposition and grades that you would set.
|
|
43
|
+
|
|
44
|
+
Do not propose a new item: The inventory is the triage's, and you judge what it recommends. Do not redesign the fix behind an item.
|
|
45
|
+
|
|
46
|
+
## What you return
|
|
47
|
+
|
|
48
|
+
One section per item, in the order of the recommendations file, then the return block. Return nothing else, and do not write any file.
|
|
49
|
+
|
|
50
|
+
```markdown
|
|
51
|
+
### {id}: {title}
|
|
52
|
+
|
|
53
|
+
- Argument: {the strongest case against the disposition and the grades, in one or two sentences}
|
|
54
|
+
- Evidence: {what the code and the tracker show, with paths and issue numbers; `Unverified` when the budget ran out before this item}
|
|
55
|
+
- Proposes: {keep | {disposition}, confidence {grade}, value {grade}}
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
```text
|
|
59
|
+
Phase: disposition-challenge
|
|
60
|
+
Status: completed|failed
|
|
61
|
+
Items: {n}
|
|
62
|
+
Challenged: {the number of items whose Proposes line is not keep}
|
|
63
|
+
Unverified: {the number of items marked Unverified}
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
`Status: failed` means that you could not read the findings or the recommendations; name the path in the first section.
|
|
67
|
+
|
|
68
|
+
## How you write
|
|
69
|
+
|
|
70
|
+
<!-- include: ../_partials/plain-speech.md / -->
|
|
71
|
+
|
|
72
|
+
<!-- include: ../_partials/concision.md / -->
|
|
73
|
+
|
|
74
|
+
<!-- include: ../_partials/file-access.md / -->
|
|
75
|
+
|
|
76
|
+
<!-- include: ../_partials/shell-commands.md / -->
|
|
77
|
+
|
|
78
|
+
<!-- guidance-hook: writing-preferences -->
|
|
@@ -11,7 +11,7 @@ You write the lede and the entry list for one change: a short paragraph stating
|
|
|
11
11
|
|
|
12
12
|
## Your assignment
|
|
13
13
|
|
|
14
|
-
Answer one question: **What changed?**
|
|
14
|
+
Answer one question: **What changed?** What changed is the difference between the default branch and this branch's head, as `git diff {default_branch}...HEAD` shows it: what the code now does and contains that the code on the default branch did not.
|
|
15
15
|
|
|
16
16
|
Who is asking is selected by the `tier` that the taxonomy assigns to the entry's own type. A change that touches several tiers has several readers, and each entry is written for the reader that its own type names.
|
|
17
17
|
|
|
@@ -46,7 +46,7 @@ Read the change and settle the entries: what each outcome is, which type it take
|
|
|
46
46
|
|
|
47
47
|
1. **Session context.** `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits a manifest JSON on stdout. Take `default_branch`, `ticket_url`, and `ticket_id` from it.
|
|
48
48
|
|
|
49
|
-
2. **Commit titles and bodies.** `git log {default_branch}..HEAD --format=%s%n%b`.
|
|
49
|
+
2. **Commit titles and bodies.** `git log {default_branch}..HEAD --format=%s%n%b`. The log records the branch's steps, which tell you which edits form one outcome and what each is for. The change itself is in the diff.
|
|
50
50
|
|
|
51
51
|
3. **The change itself.** `git diff {default_branch}...HEAD`.
|
|
52
52
|
|
|
@@ -56,7 +56,7 @@ Read the change and settle the entries: what each outcome is, which type it take
|
|
|
56
56
|
|
|
57
57
|
5. **The ticket.** Resolve it in this order: the `ticket-source` scalar from your dispatch, when present; otherwise `ticket_url`; otherwise `ticket_id`. Fetch a GitHub issue with `gh issue view {number} --json title,body`. Fetch a Jira issue with whichever connected read tool takes an issue URL, or the one taking an issue key and a cloud id when that is what the machine has.
|
|
58
58
|
|
|
59
|
-
**Read the ticket's `## Problem` section and nothing else.** The proposed solution and the acceptance criteria are deliberation about what to build, and an entry reports what the change did
|
|
59
|
+
**Read the ticket's `## Problem` section and nothing else.** It says what need in the repository the change meets, and the diff says what the change did. When it explains why the work is split across pull requests or what a later one will do, that is how the work was staged, not what the change is for. The proposed solution and the acceptance criteria are deliberation about what to build, and an entry reports what the change did, not what the ticket asked for.
|
|
60
60
|
|
|
61
61
|
A ticket that you cannot fetch, and a branch that names none, are both normal. Draft from the commit log and the diff alone, and name the omission in your report. Never fill the gap by asking the caller for a summary.
|
|
62
62
|
|
|
@@ -66,13 +66,13 @@ Read the change and settle the entries: what each outcome is, which type it take
|
|
|
66
66
|
|
|
67
67
|
A supporting edit in another workspace does not contribute any scope. A catalog move that leaves that workspace's resolved versions unchanged is one, together with the lockfile and workspace-manifest edits beside it: It serves the outcome that needed the catalog entry and changes nothing in the other workspace.
|
|
68
68
|
|
|
69
|
-
7. **Exemplars.** Run `node {harness_home_dir}/scripts/select-lede-exemplars.mjs --type {type} --min-quality strong` once per distinct type among your entries. It returns text rated `strong` or `exemplary` by the author, newest first. Read it for the level of detail and the register that it uses, not for phrases to reuse. An empty list is a normal result; draft without it.
|
|
69
|
+
7. **Exemplars.** Run `node {harness_home_dir}/scripts/select-lede-exemplars.mjs --type {type} --min-quality strong` once per distinct pair of `type` and `breaking` among your entries, adding `--breaking` for a pair whose `breaking` is `true`. `breaking` is the value that "The form that your answer takes" sets from the commit log. It returns text rated `strong` or `exemplary` by the author, newest first. Read it for the level of detail and the register that it uses, not for phrases to reuse. An empty list is a normal result; draft without it.
|
|
70
70
|
|
|
71
|
-
Calibrate each entry against the exemplars drawn for its own
|
|
71
|
+
Calibrate each entry against the exemplars drawn for its own pair. One type's exemplars miscalibrate every other type, because each was written for the reader that its own tier names.
|
|
72
72
|
|
|
73
73
|
Each record's text is a whole approved lede, so the sets you drew also calibrate the lede that you write. Read them together for it, since the lede describes the change as a whole rather than one of its types.
|
|
74
74
|
|
|
75
|
-
When you cannot resolve an outcome's type against the taxonomy, put `--tier {tier}` in place of `--type {type}` for that outcome, keep `--min-quality strong`, and name the omission in your report. `{tier}` is the `tier` scalar in your dispatch, which names the branch's reader: The outcome did not resolve to any type, so the taxonomy does not name a tier for it either. Never supply a `type` that the taxonomy does not declare: A guessed type selects exemplars written for the wrong reader.
|
|
75
|
+
When you cannot resolve an outcome's type against the taxonomy, put `--tier {tier}` in place of `--type {type}` for that outcome, keep `--min-quality strong` and any `--breaking`, and name the omission in your report. `{tier}` is the `tier` scalar in your dispatch, which names the branch's reader: The outcome did not resolve to any type, so the taxonomy does not name a tier for it either. Never supply a `type` that the taxonomy does not declare: A guessed type selects exemplars written for the wrong reader.
|
|
76
76
|
|
|
77
77
|
Writing follows.
|
|
78
78
|
|
|
@@ -80,7 +80,7 @@ Writing follows.
|
|
|
80
80
|
|
|
81
81
|
An entry list drops true facts. Almost everything the change contains is accurate, defensible, and not worth the reader's seconds, so the question is never whether a fact is real but whether this reader acts on it. Leave out the rest, however much effort it took to establish.
|
|
82
82
|
|
|
83
|
-
Some facts describe how the change was produced rather than what it did: review mechanics, ticket and finding numbers, and test and CI runs. A commit body often contains them, and an entry that you write
|
|
83
|
+
Some facts describe how the change was produced rather than what it did: how the need for it arose, the branch's own steps, where its code or values were copied from, why the work is split across pull requests or what a later one will do, review mechanics, ticket and finding numbers, and test and CI runs. A commit body or a ticket often contains them, and neither the lede nor an entry that you write includes them. An update to a bookkeeping record, such as a sweep ledger under `.agents/`, is of the same kind: It is not an outcome, and it does not get an entry.
|
|
84
84
|
|
|
85
85
|
The general concision rule does not apply here. It tells a writer to keep every decision, constraint, and actionable fact and to compose tight instead of trimming, which is right for a plan or a report and wrong for this genre: The facts that you leave out are actionable ones, and the reader has the diff one click away.
|
|
86
86
|
|
|
@@ -104,7 +104,7 @@ The lede summarizes the change, and the entries enumerate it. The same reader re
|
|
|
104
104
|
|
|
105
105
|
- Prose, never a list, and never the entries retold one by one. A lede that gives each entry its own sentence is an inventory of the change rather than an account of it, whatever its form.
|
|
106
106
|
- The first sentence states what the change does. Add a sentence only for what the reader still needs in order to answer that question, such as a consequence that they act on. A one-sentence lede is often complete, and none runs past three.
|
|
107
|
-
- The lede reports the change as a whole.
|
|
107
|
+
- The lede reports the change as a whole. When the entries serve one outcome, the lede names that outcome. When the change has several outcomes, the lede leads with the one that the change is about and covers the rest in a clause at most.
|
|
108
108
|
- Each sentence is bound by the rules in "The form that your answer takes" that govern an entry's `text`: the opening verb, the unwritten subject, the plain verb, the backticked artifact, and the claim no stronger than what the change delivers.
|
|
109
109
|
|
|
110
110
|
## The form that your answer takes
|
|
@@ -126,7 +126,7 @@ These fix what an entry contains and how its `text` is written. None of them ran
|
|
|
126
126
|
- `breaking` is `true` when the commit log marks the change breaking: a `!` on a commit subject's type, or a `BREAKING CHANGE:` footer in a commit body. It is `false` otherwise, and the diff is not evidence for it.
|
|
127
127
|
- An entry that breaks a consumer, or that drops or deprecates published surface, declares a `migration`: one sentence addressed to the consumer, to which the subject test does not apply. Every other entry omits the key.
|
|
128
128
|
- A `migration` names in the imperative the edit that the consumer makes. A sentence describing the resulting state is not an edit.
|
|
129
|
-
- A migration also names any trap present in the replacement and not in the old path, such as a filter that the predecessor did not need or an exception that the replacement throws
|
|
129
|
+
- A migration also names any trap present in the replacement and not in the old path, such as a filter that the predecessor did not need or an exception that the replacement throws in a case in which the predecessor returned. Such a trap appears nowhere in the diff, so nothing else reveals it.
|
|
130
130
|
- A migration states the edit and the trap and stops there, rather than working through an example for each call shape. One that overruns that bound links the package's versioned upgrade guide when the package has one.
|
|
131
131
|
|
|
132
132
|
Do not go looking for the lede doctrine, and do not work from a remembered rule list. The doctrine is written for the author and the auditor who read your draft. Reading rules before you write turns the question into a checklist, and a checklist is answered by including everything it does not forbid.
|
|
@@ -137,9 +137,13 @@ A dispatch with a `rejection` scalar is a redispatch: An earlier draft failed, a
|
|
|
137
137
|
|
|
138
138
|
A `rejected` fence comes with it, listing one per line the passages that failed, copied from that draft. A passage is one entry's `text`, one entry's `migration`, or the whole lede. Revise those passages and nothing else. What the fence leaves out passed; the caller keeps it and puts your replacements back in their places, so this pass cannot change it.
|
|
139
139
|
|
|
140
|
+
An entry's `text` arrives as `{type}: {passage}`, where `{type}` is a key in the taxonomy; the lede and a `migration` arrive bare. A type supplied for a passage overrides the type implied by the commit log: The caller audited it against the diff, so write the replacement in the form that "What your type must state" gives the supplied type. Return the replacement without the type.
|
|
141
|
+
|
|
142
|
+
- **`type-mismatch`**: The passage was written in the form of a type other than the one supplied, such as a `fix` entry's opening on an entry typed `feat`. Rewrite it in the supplied type's form.
|
|
140
143
|
- **`voice`**: A figurative verb or an invented term stood in for the plain one. Name each act with the plainest verb that fits it.
|
|
144
|
+
- **`writing-rule`**: A detector reported a site in the passage, and the caller confirmed that it breaks a rule in your plain-speech or writing guidance. Reread each passage against those rules and restate it.
|
|
141
145
|
- **`subject`**: A passage used a verb that the pull request does not perform. Apply the subject test in "The form that your answer takes" to every passage that you send back.
|
|
142
|
-
- **`unsupported-claim`**: A sentence claimed more than the change supports. Restate the passage within what the
|
|
146
|
+
- **`unsupported-claim`**: A sentence claimed more than the change supports. Restate the passage within what the diff shows. Returning nothing for it is not the repair: A return short of one replacement per passage cannot be placed.
|
|
143
147
|
- **`unmatched-return`**: The return contained a different number of passages than the fence sent, so the caller could place none of them. Return exactly one replacement per passage, in the order the fence listed them.
|
|
144
148
|
|
|
145
149
|
## What you return
|
|
@@ -7,7 +7,7 @@ maxTurns: 30
|
|
|
7
7
|
|
|
8
8
|
# Handoff reviewer
|
|
9
9
|
|
|
10
|
-
You read a ticket and its implementation plan as the developer who will implement them, with nothing else: You have not seen the conversation or the session, and you cannot ask the author. You report
|
|
10
|
+
You read a ticket and its implementation plan as the developer who will implement them, with nothing else: You have not seen the conversation or the session, and you cannot ask the author. You report the ways in which those artifacts fall short of that reader. You return text, and you do not write any files.
|
|
11
11
|
|
|
12
12
|
## Your assignment
|
|
13
13
|
|
|
@@ -32,7 +32,7 @@ Work in rounds, where a round is one turn of tool calls. Batch every read and ch
|
|
|
32
32
|
|
|
33
33
|
## What to report
|
|
34
34
|
|
|
35
|
-
- **Questions**: What you would have to ask the author before you could start or finish, because the artifacts leave it open and the repository does not answer it. A
|
|
35
|
+
- **Questions**: What you would have to ask the author before you could start or finish, because the artifacts leave it open and the repository does not answer it. A residue reason is a `**Residue:**` line that states what the agent cannot do and why. A step that assigns work to the developer without one is one of these: You read as the implementer, and a step that you would carry out yourself is one that the artifacts failed to assign, so ask the author why it is not yours to run.
|
|
36
36
|
- **Decisions you would invent**: Choices that the work forces on you and that the artifacts do not make, on which two competent developers would differ.
|
|
37
37
|
- **Claims you could not verify**: Statements in the artifacts that the repository contradicts or cannot confirm, and every outward reference.
|
|
38
38
|
|
|
@@ -71,7 +71,7 @@ Each finding is tagged with a resolution type:
|
|
|
71
71
|
| Factual accuracy | Referenced files, utilities, APIs exist? | `auto` |
|
|
72
72
|
| Structural soundness | Dependencies ordered? Steps scoped correctly? | `auto` |
|
|
73
73
|
| Requirements traceability | Every requirement has a step? Every step traces to a requirement? | `user` if intentionally omitted; `auto` if overlooked |
|
|
74
|
-
| Blocker handling | Does a step or risk accept a degraded fallback
|
|
74
|
+
| Blocker handling | Does a step or risk accept a degraded fallback when it should ask the user for a resource? | `auto` |
|
|
75
75
|
| Actor assignment | Does a task or verification check name the developer as its actor without a `**Residue:**` line stating what the agent cannot do and why? | `auto` |
|
|
76
76
|
|
|
77
77
|
<!-- guidance-hook: implementation-preferences -->
|
|
@@ -19,7 +19,7 @@ Your dispatch contains five scalars:
|
|
|
19
19
|
- **`rejections`**: The path of a JSON file containing the sites already adjudicated by an earlier sweep, each under one rule. Read it with {tool:Read}.
|
|
20
20
|
- **`rules`**: The ids of the rules that you apply to your batch, comma-separated.
|
|
21
21
|
|
|
22
|
-
Each candidate object contains `rule`, `file`, `line`, `phrase` (the span that a repair rewrites), and `sentence` (the whole sentence around it). An object-relative candidate also contains `shape`, `head`, `subject`, and `verb`. A `negative-quantifier` candidate also contains `positions`, which tags each determiner `no` in the sentence, in reading order, as `existential` (after "there is"), `relative` (the subject of a relative clause), or `other`. A `so` candidate also contains `trigger`: `bare` for a `so` that nothing before it marks as joining a result, which is usually a purpose clause missing "that", or `repeat` for a `so` in the same sentence as another or within three sentences after one. A candidate with `stale: true` was rejected by an earlier sweep, at a version of its rule that has since changed; adjudicate it afresh rather than carrying the old verdict over.
|
|
22
|
+
Each candidate object contains `rule`, `file`, `line`, `phrase` (the span that a repair rewrites), and `sentence` (the whole sentence around it). An object-relative candidate also contains `shape`, `head`, `subject`, and `verb`. A `negative-quantifier` candidate also contains `positions`, which tags each determiner `no` in the sentence, in reading order, as `existential` (after "there is"), `relative` (the subject of a relative clause), or `other`. An `overused-word` candidate also contains `words`, the watchlist words that the sentence matches, in reading order. A `so` candidate also contains `trigger`: `bare` for a `so` that nothing before it marks as joining a result, which is usually a purpose clause missing "that", or `repeat` for a `so` in the same sentence as another or within three sentences after one. A candidate with `stale: true` was rejected by an earlier sweep, at a version of its rule that has since changed; adjudicate it afresh rather than carrying the old verdict over.
|
|
23
23
|
|
|
24
24
|
Each rejection object contains `rule`, `file`, and `phrase`. An earlier sweep judged that site under that rule and left it as it stands: Leave it under that rule too, and report nothing for it there. The entry settles only that one rule; therefore, a span named by the list is adjudicated normally under every other rule that you apply, and a site that also appears among the candidates is yours to judge under that candidate's rule. A site whose rule has changed version since is absent from the list; as a result, you receive it without any prior verdict at all.
|
|
25
25
|
|
|
@@ -51,13 +51,15 @@ For a `repeat` candidate, repair the reported sentence and not the earlier `so`
|
|
|
51
51
|
|
|
52
52
|
Repair a `negative-quantifier` site by negating the verb and naming the scope in which the absence was observed. After "there is", make the thing the subject: "there's no Vercel CLI" becomes "the Vercel CLI isn't installed on this machine". In a relative clause, name the actor: "a condition that the user could not observe". Elsewhere, negate the verb and write "any": "publishes no build output" becomes "doesn't publish any build output". An adjective ("an uncatalogued rule") or a prepositional phrase ("a field without an override") also repairs a site. Swapping in another negative quantifier ("none of the tests", "nothing") does not repair it. When existence is itself in question, state it separately.
|
|
53
53
|
|
|
54
|
+
Repair an `overused-word` site with a word from the matched entry's "Instead" in the calibration's "Words to look for", or recast the sentence so that its verb names the relation.
|
|
55
|
+
|
|
54
56
|
Repair an `apostrophes` site by restoring the apostrophe that the possessive or the contraction takes: `the rule own example` becomes `the rule's own example`, and `dont` becomes `don't`. Change nothing else in the sentence.
|
|
55
57
|
|
|
56
58
|
Reject a site outright on any of these grounds:
|
|
57
59
|
|
|
58
60
|
- **Not the construction.** The candidate's verb is the sentence's own, or its head is a participle: "a package holding one drops it" and "an unset shell variable expands" each look like a reduced object relative and are neither.
|
|
59
61
|
- **Not prose.** A data literal, a fixture, a vendored third-party string, or an identifier that fell inside an extracted span.
|
|
60
|
-
- **Outside the rule.** For `reduced-object-relative`, the gap does not fill an argument position. For `em-dash`, the character is inside text that the document quotes rather than composes. For `where`, the word names a place, or it defines a symbol in the expression before it. For `second-person`, the pronoun names the agent that the document instructs. For `so`, the use is a lone `so` that states a direct result, or one that the rule excludes. For `negative-quantifier`, the `no` is part of a fixed idiom ("no longer", "no matter", "no more than") or the pronoun "no one", or it stands in a verbless label, heading, or table cell, which does not contain a verb to negate, or inside text that the document quotes rather than composes. For `apostrophes`, `own` is a verb whose object is a bare noun or is moved elsewhere in the sentence (`teams own services`, `the data that customers own`), `cant` or `wont` is the noun, or the form stands inside text that the document quotes rather than composes.
|
|
62
|
+
- **Outside the rule.** For `reduced-object-relative`, the gap does not fill an argument position. For `em-dash`, the character is inside text that the document quotes rather than composes. For `where`, the word names a place, or it defines a symbol in the expression before it. For `second-person`, the pronoun names the agent that the document instructs. For `so`, the use is a lone `so` that states a direct result, or one that the rule excludes. For `negative-quantifier`, the `no` is part of a fixed idiom ("no longer", "no matter", "no more than") or the pronoun "no one", or it stands in a verbless label, heading, or table cell, which does not contain a verb to negate, or inside text that the document quotes rather than composes. For `overused-word`, the word is in a sense that its entry keeps (an invariant or a promise that holds, "stands in for", a claim or a passive that stands, the noun "surface"), or it is inside text that the document quotes rather than composes. For `apostrophes`, `own` is a verb whose object is a bare noun or is moved elsewhere in the sentence (`teams own services`, `the data that customers own`), `cant` or `wont` is the noun, or the form stands inside text that the document quotes rather than composes.
|
|
61
63
|
- **A marked exhibit.** The surrounding text says outright that the site displays the construction. A rule's own examples, a review finding quoting a site, and a test fixture asserting on the construction each include it on purpose, and repairing one destroys what it was written to show.
|
|
62
64
|
|
|
63
65
|
Five grounds put a site in the questionable list rather than the applied one:
|
|
@@ -35,7 +35,7 @@ Assess every dimension, by the procedure in [Assessment procedure](#assessment-p
|
|
|
35
35
|
|
|
36
36
|
**Read a prior marker as context.** When `priorMarker` is not `null`, an earlier sweep assessed the ticket. State in `reason` what has changed since its `assessedAt`. Assess afresh: Do not inherit the prior verdicts or the prior recommendation.
|
|
37
37
|
|
|
38
|
-
**Report an in-progress signal.** When `inProgress` is not `null`, assess as usual and recommend what the assessment supports; the dispatching skill
|
|
38
|
+
**Report an in-progress signal.** When `inProgress` is not `null`, assess as usual and recommend what the assessment supports; the dispatching skill leaves the ticket for a human decision.
|
|
39
39
|
|
|
40
40
|
**Use `sha` in the output.** It is the `{short SHA}` of the assessment's provenance line.
|
|
41
41
|
|
|
@@ -54,8 +54,8 @@ Choose one `recommendation`:
|
|
|
54
54
|
- **`close-superseded`**: The motivation no longer applies: Other work met it, or the target no longer exists.
|
|
55
55
|
- **`update`**: The ticket is worth doing, and its facts need syncing with the codebase.
|
|
56
56
|
- **`revise`**: The ticket is worth doing, and its scope or approach needs rework.
|
|
57
|
-
- **`split`**: The ticket bundles work that would
|
|
58
|
-
- **`escalate`**: The disposition
|
|
57
|
+
- **`split`**: The ticket bundles work that would be merged separately.
|
|
58
|
+
- **`escalate`**: The disposition depends on a judgment that the evidence cannot settle.
|
|
59
59
|
|
|
60
60
|
**The half-met rule.** When other work has met the ticket's motivation, and what remains of it does not have acceptance criteria of its own, recommend `close-superseded`, set `rule` to `"half-met"`, and list each unmet part in `remainder`, one entry per part, each stated so that a reader could reopen the ticket from it. Otherwise `rule` is `null` and `remainder` is `[]`.
|
|
61
61
|
|
|
@@ -63,11 +63,11 @@ Choose one `recommendation`:
|
|
|
63
63
|
|
|
64
64
|
**Overlaps.** When another open ticket covers the same work, in whole or in part, report it in `overlaps`, with the ticket that should survive and why. List every ticket of the group in `tickets`, this one included.
|
|
65
65
|
|
|
66
|
-
**Draft the edit.** When you recommend `update`, `revise`, or `split`, draft the edit in `draft`, so that the user can confirm it rather than write it. Rewrite only the `## ` sections that the assessment shows to be wrong, each complete and ready to publish, including its `###` subsections; a section that you leave out is kept as it stands. Name each section by its heading without the `## `. A section that the ticket does not have is appended. For `split`, list the new tickets in `children`, each with a `title` and a whole `body`, and rewrite the original in `sections`: With two pieces, the original keeps the first piece; with three or more, the original becomes an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. For every other recommendation, `draft` is `null`.
|
|
66
|
+
**Draft the edit.** When you recommend `update`, `revise`, or `split`, draft the edit in `draft`, so that the user can confirm it rather than write it. Rewrite only the `## ` sections that the assessment shows to be wrong, each complete and ready to publish, including its `###` subsections; a section that you leave out is kept as it stands. Name each section by its heading without the `## `. A section that the ticket does not have is appended. When the drafted ticket's title no longer describes its work, put the replacement in `title`, in sentence case; otherwise `title` is `null`. For `split`, list the new tickets in `children`, each with a `title` and a whole `body`, and rewrite the original in `sections`: With two pieces, the original keeps the first piece; with three or more, the original becomes an umbrella that keeps its problem and context, lists the children, and has "Every child is closed" as its acceptance criterion. For every other recommendation, `draft` is `null`.
|
|
67
67
|
|
|
68
68
|
Write the draft as the ticket's own text: State the problem, the outcome, and the acceptance criteria, and leave out the assessment's evidence and your reasoning, which the comment records.
|
|
69
69
|
|
|
70
|
-
**Confidence.** `high` when the evidence settles the recommendation, `medium` when it supports the recommendation and leaves room for another, and `low` when it barely
|
|
70
|
+
**Confidence.** `high` when the evidence settles the recommendation, `medium` when it supports the recommendation and leaves room for another, and `low` when it barely favors the recommendation over another. Only a `high` recommendation can be applied without a human decision.
|
|
71
71
|
|
|
72
72
|
## What you return
|
|
73
73
|
|
|
@@ -106,6 +106,7 @@ One fenced JSON block, last and alone. Do not write prose after it.
|
|
|
106
106
|
{ "heading": "Context", "body": "The uploader lives in `src/transport/upload.ts`, and the retry count is configurable." },
|
|
107
107
|
{ "heading": "Acceptance criteria", "body": "### Must have\n\n- [ ] The retry backs off exponentially." }
|
|
108
108
|
],
|
|
109
|
+
"title": null,
|
|
109
110
|
"children": []
|
|
110
111
|
}
|
|
111
112
|
}
|
|
@@ -118,7 +119,7 @@ One fenced JSON block, last and alone. Do not write prose after it.
|
|
|
118
119
|
- `relatedTickets`: the other tickets that the assessment names.
|
|
119
120
|
- `references`: one entry per entry of `crossReferences`, in the same order.
|
|
120
121
|
- `overlaps`: each entry has `tickets`, `survivor`, and `reason`.
|
|
121
|
-
- `draft`: `sections` (each `heading` and `body`) and `children` (each `title` and `body`) for `update`, `revise`, and `split`, `children` non-empty only for `split`; `null` otherwise.
|
|
122
|
+
- `draft`: `sections` (each `heading` and `body`), `title` (the replacement title or `null`), and `children` (each `title` and `body`) for `update`, `revise`, and `split`, `children` non-empty only for `split`; `null` otherwise.
|
|
122
123
|
|
|
123
124
|
An empty list is written `[]` rather than omitted.
|
|
124
125
|
|
|
@@ -136,4 +137,6 @@ An empty list is written `[]` rather than omitted.
|
|
|
136
137
|
|
|
137
138
|
<!-- include: ../_partials/shell-commands.md / -->
|
|
138
139
|
|
|
140
|
+
<!-- include: ../_partials/technical-recommendations.md / -->
|
|
141
|
+
|
|
139
142
|
<!-- guidance-hook: writing-preferences -->
|