codeassembly-guidance 0.0.0 → 0.1.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 +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
## Comment discipline
|
|
2
|
+
|
|
3
|
+
These rules apply to every comment that you write **into source**: writing new code, revising it, editing after a review, or **proposing** replacement comment text inside a review finding. A comment drafted for someone else's file is a source comment, and the same audit applies to it.
|
|
4
|
+
|
|
5
|
+
The reader is an engineer six months from now who does not have the transcript, the session, or any memory of the change. Write for that reader.
|
|
6
|
+
|
|
7
|
+
### The baseline
|
|
8
|
+
|
|
9
|
+
Every function, method, class, and component **must** have a description. One line is often enough. Exceed that length only when a reader would be substantially helped by a longer explanation (and don't include anything readily apparent from a quick glance at the code). If in doubt, be terse.
|
|
10
|
+
|
|
11
|
+
The description of a function or method describes what it **does** and leads with a verb; any other opening is nonstandard and should not be emulated. The verb's mood is a project preference and is not set here.
|
|
12
|
+
|
|
13
|
+
The description of a class or component describes what it **is**.
|
|
14
|
+
|
|
15
|
+
Add descriptions of constants only if the description helps a reader understand the code. Constants on which the code's correctness depends are good candidates for description. Most other constants are not; rely on good variable names instead. Do not describe an interface or type unless its purpose is nonobvious.
|
|
16
|
+
|
|
17
|
+
### Four tests
|
|
18
|
+
|
|
19
|
+
Apply all four to every comment that you write or keep. A comment that fails one is cut or rewritten, not softened. Comments are code: read, maintained, and trusted. Each one must justify its place.
|
|
20
|
+
|
|
21
|
+
**1. The stranger test: Would this interest only someone who watched the change happen?** Then cut it.
|
|
22
|
+
|
|
23
|
+
Tells: _rather than_, _instead of_, _deliberately_, _used to_, _previously_, _replaces_, _we discussed_, _as agreed_, _see PR #N_, _added by TICKET-123_, _matches the X precedent_, _future readers should note_. So is any defense of the edit, any counterfactual whose other branch was never possible, and any narration of how or where the code is run.
|
|
24
|
+
|
|
25
|
+
State the code as it **is**, in the present tense; never as it was, as it might have been, or as it is not.
|
|
26
|
+
|
|
27
|
+
**2. The deletion test: Would a reader lose anything if the comment were gone?** Then cut it.
|
|
28
|
+
|
|
29
|
+
A comment tells the reader nothing if it paraphrases the line below it, restates the test's own name, or re-describes what a well-named function that it calls already documents. Inline comments answer _why_, never _what_. One line by default; exceed it only when a genuinely multi-part constraint will not compress.
|
|
30
|
+
|
|
31
|
+
**3. The one-location test: Is this fact already documented where it belongs?** Then cut it.
|
|
32
|
+
|
|
33
|
+
The library's behavior belongs in the library's docs. A helper's contract belongs on the helper. A consumer's name belongs nowhere near the shared code that it consumes. An invariant belongs in a type or an assertion, not in prose about a case that cannot happen.
|
|
34
|
+
|
|
35
|
+
**4. The derivation test: Do the listed cases follow from one rule?** Then state the rule.
|
|
36
|
+
|
|
37
|
+
A comment that enumerates the cases below it copies each case's own description, and the copy drifts: The enumeration keeps a name that the code has since renamed, or it places one case on both sides of a distinction. State the invariant that generates the cases, and let each case's own description carry its specifics. An exception is worth naming once, beside the rule.
|
|
38
|
+
|
|
39
|
+
Tells: The same name appearing in two of the comment's lists, a run of backticked member names already documented at their own declarations below, and a list whose length tracks the number of members or branches below it.
|
|
40
|
+
|
|
41
|
+
### Carve-outs
|
|
42
|
+
|
|
43
|
+
These pass the tests. They are permissions, not requirements.
|
|
44
|
+
|
|
45
|
+
- **Test comments**: Non-obvious setup not conveyed by the test name; an indirect assertion, naming the reason for the indirection; the rationale for a skip.
|
|
46
|
+
- **`eslint-disable` rationales**: Why _this_ rule is suppressed _here_, and nothing more: `// eslint-disable-next-line no-explicit-any -- third-party Stripe type ships as any.` The carve-out applies to the comment, not to the suppression; whether to suppress at all is an `anti-patterns` question.
|
|
47
|
+
|
|
48
|
+
### Before and after
|
|
49
|
+
|
|
50
|
+
**Written for the reviewer**: Fails the stranger test. The comment defends the edit and describes what the code is _not_.
|
|
51
|
+
|
|
52
|
+
Before:
|
|
53
|
+
|
|
54
|
+
```ts
|
|
55
|
+
// `stdout` is deliberately absent: nothing here reads a captured stdout, so the type does not offer one.
|
|
56
|
+
// Returns null rather than a false pass.
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
After:
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
// `spawnSync` returns null for a stream redirected to a file descriptor; `runAttw` reads the output back from the file.
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Restating the call below it**: Fails the deletion test. The helper's own contract, re-narrated at the call site.
|
|
66
|
+
|
|
67
|
+
Before:
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
// Builds the document title from the page title and employee name, dropping empties and falling back to the app name.
|
|
71
|
+
useDocumentTitle(buildDocumentTitle(EMPLOYEE_COMP_TITLE, data.employee.name));
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
After:
|
|
75
|
+
|
|
76
|
+
```ts
|
|
77
|
+
// Overrides the route wrapper's static title once the name is available.
|
|
78
|
+
useDocumentTitle(buildDocumentTitle(EMPLOYEE_COMP_TITLE, data.employee.name));
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**Proposed inside a review finding**: A suggested replacement comment is a source comment. This one restates the lookup already expressed by the code and copies an example ID out of the source.
|
|
82
|
+
|
|
83
|
+
Before:
|
|
84
|
+
|
|
85
|
+
> Looks up the employee by id (e.g. `EMP034`) through the `employees` search query, then maps each row to a `CompRow`.
|
|
86
|
+
|
|
87
|
+
After:
|
|
88
|
+
|
|
89
|
+
> todo: Update stale doc comment; the header still describes the lookup as "via the `employees` search query", which this change replaces.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
## Concision
|
|
2
|
+
|
|
3
|
+
Detail adds value up to a peak, then wastes the reader's attention and hides the signal. Compose tight from the start: Lead with the minimal skeleton and add a sentence only when it changes what the reader does. Never drop a decision, constraint, or actionable fact for brevity. If you find yourself trimming, you started too loose. Full principle: `{harness_home_dir}/skills/_data/concision.md`.
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
## Diff audit
|
|
2
|
+
|
|
3
|
+
Before reporting what a change did, read the change back, and repair what you find before writing the report. The input is the hunks that you just wrote, not the change under review: This audit is bounded by your own edit, and one that grows past it becomes a second review pass.
|
|
4
|
+
|
|
5
|
+
- **Claims.** Every statement about the change is read from the diff, not from what you set out to do. A claim that something was left unchanged needs the same evidence as a claim that something changed, and it is the one most often written from memory.
|
|
6
|
+
- **Reach.** What the edit moved beyond its target: a parallel enumeration of the same list elsewhere, such as a README mirroring the edited source doc; sibling wording invalidated by a rename or re-framing, in a test title, a function header, or a neighboring doc; declaration ordering after an insertion; and adjacent behavior that a changed guard now covers or stops covering.
|
|
7
|
+
- **Class.** When the change corrects a defect, the site that you were pointed at is a sample of its class. Audit the other members before reporting, or the next reviewer finds the one that you left.
|
|
8
|
+
|
|
9
|
+
A green gate is not this audit: A suite that passes reports that nothing broke, not that the record which you are about to write is true.
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
## File access
|
|
2
|
+
|
|
3
|
+
- When given an exact file path, use the read tool directly. Do not search for the file first.
|
|
4
|
+
- If the read attempt returns "file does not exist", STOP and report the missing path; do not attempt to find the file by searching. A missing file at an exact path usually indicates a configuration or environment problem, not a wrong filename.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
## Don't test write operations against a live repo
|
|
2
|
+
|
|
3
|
+
Never exercise destructive or side-effecting operations against the user's working repo as verification. If a script's behavior requires running a command that mutates git state (`git tag`, `git commit`, `git push`, `git branch`, `git reset`, `git rebase`), file state, package state, or any other shared resource, exercise it in a disposable environment: a scratch directory (`mktemp -d "${TMPDIR:-/tmp}/probe.XXXXXX"`, since bare `mktemp -d` picks a path denied by the agent sandbox and then leaves the variable empty), a fresh `git init` with minimal fixtures, or a container.
|
|
4
|
+
|
|
5
|
+
Write absolute paths beneath that directory rather than changing into it and writing relative ones, unless the change of directory is chained to the creation succeeding, as `enter_tmpdir` is. `cd ""` returns 0, so a failed `mktemp` otherwise sends every later write into the working repo, which is the outcome that this rule exists to prevent.
|
|
6
|
+
|
|
7
|
+
Why it matters:
|
|
8
|
+
|
|
9
|
+
- Other sessions, file watchers, CI, release tooling, or IDE extensions on the user's machine can observe in-progress mutations, even if you intend to clean up after.
|
|
10
|
+
- Some projects treat new tags/commits as release signals. Once the artifact exists, downstream effects may fire before you can undo it; some release configurations are immutable (published tags produce permanent artifacts).
|
|
11
|
+
- "I can just clean up afterward" is not a substitute for never creating the artifact: Between create and cleanup, anything else on the machine can act on it.
|
|
12
|
+
|
|
13
|
+
Read-only exercises (`--dry-run`, help text, preview tables, `--list`, exit-code checks on pure-read commands) are safe in the working repo. Anything that writes, even "just for a second", is not.
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
<!-- unit-version: plain-speech 9 -->
|
|
2
|
+
|
|
3
|
+
## Plain-speech sweep calibration
|
|
4
|
+
|
|
5
|
+
How one sweep applies the rule above, so that two sweepers give the same verdict on the same sentence. The rule decides what counts as plain; this section decides what a sweeper rewrites and what it leaves.
|
|
6
|
+
|
|
7
|
+
### Rewrite these
|
|
8
|
+
|
|
9
|
+
1. **A figurative verb when a plain one exists.** "detail taxes the reader" becomes "detail wastes the reader's attention". "the lede writes itself" becomes "the lede follows".
|
|
10
|
+
2. **A verb that does not fit its subject.** "the file carries a section" becomes "the file contains a section". "the block governs" becomes "the block takes precedence".
|
|
11
|
+
3. **A subject that does not perform the action, or a missing actor that the reader needs.** Rewrite when the sentence gives an action to something that does not perform it, or omits an actor that the reader must know and cannot recover from context. "Findings arrive as warnings" becomes "The function reports warnings": Findings arrive nowhere, and the original drops the function that produced them. In a skill body, "the parent rides the creation call" becomes "Set the parent in the creation call", because the agent sets it. "Refinement happens later, in bulk" becomes "A later pass refines them in bulk", because the point is which pass does it.
|
|
12
|
+
4. **A constructed figure when a literal phrase exists.** The rule's mannered-prose test, applied to a site. Only a figure is a candidate under this case, so plain technical vocabulary ("renders as a subsection", "inlines the partial", "the test fails") is not one. `gate`, `sweep`, `tier`, `lede`, `drift`, and `live` are figures on which this corpus has settled, and they stay.
|
|
13
|
+
|
|
14
|
+
Passive voice is not a defect on its own, and case 3 does not license converting it. Keep the passive when the actor is obvious or beside the point, when the patient is the paragraph's topic, or when it puts a long phrase at the end of the sentence.
|
|
15
|
+
|
|
16
|
+
### Leave these
|
|
17
|
+
|
|
18
|
+
- A term on the settled list in case 4 above. That list is closed: A term absent from it is a candidate. Neither its frequency, nor a neighboring file, nor its survival of an earlier sweep settles a term, and a sweeper citing one is reporting what the corpus does rather than what the rule requires. Extending the list is the author's decision, taken in this calibration, never a sweeper's.
|
|
19
|
+
- Any rewrite that would change what the text directs. When the plain wording would resolve an ambiguity that the original left open, leave the text and report the site as questionable.
|
|
20
|
+
|
|
21
|
+
### Worked example
|
|
22
|
+
|
|
23
|
+
A paragraph of this library's own guidance. Before:
|
|
24
|
+
|
|
25
|
+
> Behavioral rules that govern an agent's output -- such as the recommendation gradient and the action-items block -- are stated once in `AGENTS.md` and the shared `_data` specs. Where the boundary below calls for a restatement, it lands at the step that produces the output. An agent follows a rule more reliably when it sits beside the action it governs than when it must be fetched through a link.
|
|
26
|
+
|
|
27
|
+
After:
|
|
28
|
+
|
|
29
|
+
> Behavioral rules for an agent's output -- such as the recommendation gradient and the action-items block -- are stated once in `AGENTS.md` and the shared `_data` specs. When the boundary below requires a restatement, put it at the step that produces the output. An agent follows a rule more reliably when the rule appears next to the action that it governs than when the agent must follow a link to read it.
|
|
30
|
+
|
|
31
|
+
Three edits fall under cases 1 and 2, and two under case 3: "lands" gives the placement to the restatement rather than to the agent that places it, and "must be fetched" drops the agent from a sentence whose point is which party fetches. The first sentence's passive stands, because the paragraph's topic is the rules rather than the files that state them. Two edits do not belong to any case here: The "When" that replaces "Where" and the relativizer restored in "the action that it governs" come from the writing preferences, which a sweep applies in the same pass.
|
|
32
|
+
|
|
33
|
+
### Shapes to look for
|
|
34
|
+
|
|
35
|
+
Nine shapes recur in this corpus. Each is a search pattern rather than a rule: A sentence matching one is a candidate for the rule's tests, and a sentence matching none can still fail them.
|
|
36
|
+
|
|
37
|
+
1. **The cleft construction.** "Segment anchoring is what admits the branch form" becomes "Segment anchoring admits the branch form".
|
|
38
|
+
2. **Appositives stacked on the subject.** "The record, a file that one run writes and the next reads, is keyed on the phrase" becomes "The record is keyed on the phrase. One run writes it and the next reads it."
|
|
39
|
+
3. **"Not X, but Y" when Y alone says it.** "The default is not a report, but an applied repair" becomes "The default applies the repair".
|
|
40
|
+
4. **A nominalized gerund standing in for the actor.** "Five filters separate needing coverage from a particular test being worth writing" becomes "A change can need coverage even when no particular test is worth writing".
|
|
41
|
+
5. **A long subject with an embedded clause before its main verb.** "A change that needs coverage but finds no candidate clearing the bar ships without a test" becomes "A change is merged without a test when it needs coverage and no candidate clears the bar".
|
|
42
|
+
6. **Personification of an inanimate subject.** "The queue now reads as one set behind the blocking ticket" becomes "All four tickets are now marked as blocked by that ticket".
|
|
43
|
+
7. **An abstract noun standing in for a small concrete set.** "The suite covers the boundary cases" becomes "The suite covers an empty list, one entry, and a list past the budget".
|
|
44
|
+
8. **A concrete metaphor standing in for the literal abstraction.** The inverse of shape 7. "attrition rather than advocacy" becomes "tiring the developer rather than persuading them". "priced on your ledger" becomes "measured by you".
|
|
45
|
+
9. **"No" as a determiner.** "publishes no build output" becomes "doesn't publish any build output". "there's no Vercel CLI" becomes "the Vercel CLI isn't installed on this machine". "a skill that no task invokes" becomes "a skill that the plan does not invoke".
|
|
46
|
+
|
|
47
|
+
### The negative-quantifier rule
|
|
48
|
+
|
|
49
|
+
<!-- rule: negative-quantifier 2 -->
|
|
50
|
+
|
|
51
|
+
The helper reports every determiner "no" under this rule, as shape 9, in any position. Report a site of that shape under `negative-quantifier`, and every other site that breaks the plain-speech rule under `plain-speech`.
|
|
52
|
+
|
|
53
|
+
### Words to look for
|
|
54
|
+
|
|
55
|
+
Ten words recur in this corpus in uses for which a word naming the relation exists. Each is a search term rather than a rule, as a shape is: A match is a candidate for the rule's tests. When an entry names a sense that stays, a use in that sense is not a candidate.
|
|
56
|
+
|
|
57
|
+
- **carry**: "the change carries a flag". Instead: has, includes, declares, sets, states.
|
|
58
|
+
- **cost**: "a cost to you", "the token cost". Instead: the unit itself, as in "takes 12 ms", "one round trip", "spends the reader's attention".
|
|
59
|
+
- **hold**: "the caller holds the state". Instead: owns, stores, keeps. Stays when a promise or an invariant holds.
|
|
60
|
+
- **land**: "the fix lands in this PR". Instead: is merged, is committed.
|
|
61
|
+
- **reach**: "the change reaches the machine". Instead: is deployed to, is installed on, is available to, arrives in.
|
|
62
|
+
- **route**: "route the finding to PR-prep". Instead: send to, assign to, report to.
|
|
63
|
+
- **ship**: "ships without a test". Instead: is merged, is released.
|
|
64
|
+
- **sit**: "sits outside the body". Instead: is, is in, is next to.
|
|
65
|
+
- **stand**: "stands up a fixture". Instead: builds, creates. Stays as "stands in for", and when a claim or a passive stands.
|
|
66
|
+
- **surface**: "a review surfaces findings". Instead: reports, raises, reveals. Stays as the noun: a documentation surface.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
Speak plainly in practical documentation, in code comments, and in chat. The one carve-out is presentational text, the kind traditionally reviewed by a copy editor, such as marketing and website copy.
|
|
2
|
+
|
|
3
|
+
Write for a reader who does not share the author's first language, and test each sentence by asking whether that reader parses it on one pass. The test is about structure, not vocabulary: A domain term stays. Use the clearest verb: A file **contains** a section (not "bears" or "carries"), a function **returns** a result (not "the function answers with the result"), a tool **reports** its findings (not "the findings arrive").
|
|
4
|
+
|
|
5
|
+
A sentence can pass that test and still be **mannered prose**: a figure built for the sentence when a direct statement would do. "a dial worth turning" becomes "a parameter worth varying"; "this point earns its keep" becomes "this point still matters". A figure also adds connotations that the writer did not choose and cannot control. When a literal phrase is available, use it.
|
|
6
|
+
|
|
7
|
+
A verb that fits any subject and object does not state any relation between them. "The file carries a section", "the record carries a version", "the change carries a flag": One verb covers three relations and therefore names none of them. Write the verb that names this one: contains, declares, sets. Such a verb passes both tests above, because it is common rather than built for the sentence; therefore, test for it separately.
|
|
8
|
+
|
|
9
|
+
When a sentence makes data, a file, or a part of a document the subject of an action that an agent or a command performs, the reader cannot tell who acts: "the roots join the recorded ones", "the body reaches the approval gate". A passive that omits an actor that the reader needs hides the actor in the same way. Make the actor the subject. In instructions to an agent, the actor is usually the agent, and the sentence is an imperative: "Show the body to the user at the approval gate." In a document that describes code, the actor is the command or function that acts: "`record` adds the roots to the recorded ones"; an imperative there would give the action to the reader. A subject stays when it performs its verb, animate or not, or when its verb states a relation: A function returns a result, and a file contains a section.
|
|
10
|
+
|
|
11
|
+
"No" used as a determiner, in any position, leaves the reader unable to tell whether the thing does not exist or exists and fails the condition, and it hides where the absence was observed: "There's no Vercel CLI" was meant as "the Vercel CLI isn't installed on this machine" and read as "the Vercel CLI doesn't exist". As the subject of a relative clause, it also hides the actor and states a claim about every actor when the sentence is about one. Negate the verb, and name the scope in which the absence was observed: "the Vercel CLI isn't installed on this machine", "doesn't publish any build output", "a field not covered by any of the tests", "a condition that the user could not observe". Swapping in another negative quantifier is not a repair, because "a field that none of the tests names" keeps the construction. When existence is itself in question, state it separately: "the package doesn't have any tests". A site stays when it is a fixed idiom, such as "no longer", "no matter", or "no more than"; the pronoun "no one"; a hyphenated compound, such as "no-op"; a verbless label, heading, or table cell, which does not contain a verb to negate; or code, a quotation, or a marked exhibit.
|
|
12
|
+
|
|
13
|
+
This rule takes precedence over the register of the surrounding documents, this guidance included.
|
|
@@ -0,0 +1,3 @@
|
|
|
1
|
+
**No hard line breaks.** Write each paragraph and each list item as a single line. Do not insert newlines to wrap at a column width. Every surface that renders this text wraps it, and GitHub turns a newline inside a paragraph into a literal line break, so hand-wrapped prose renders ragged.
|
|
2
|
+
|
|
3
|
+
This rule applies to text composed for a rendering surface: a commit body, a PR or issue body, a comment, a saved artifact. Inside the repository, the project's formatter decides instead; if the project has none, follow the convention already in the file.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
<!-- Point-in-time record, read by capture-lede-decision to recover what was published. A revision that you publish gets a new record; leave this one unedited, and say nothing about leaving it. -->
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
## Reduced object relatives
|
|
2
|
+
|
|
3
|
+
<!-- rule: reduced-object-relative 1 -->
|
|
4
|
+
|
|
5
|
+
A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`. This is a house convention, not a claim about ordinary English, which permits the contact clause freely.
|
|
6
|
+
|
|
7
|
+
**Repairs, in preference order.** Choose per site; restored relativizers stacked across a passage read as a tic of their own.
|
|
8
|
+
|
|
9
|
+
1. **Reduce to a passive participle** if the actor is worth naming: "a dependency imported by every exported tier module".
|
|
10
|
+
2. **Restore the relativizer** if the passive reads worse: "the ticket that the branch name encodes".
|
|
11
|
+
3. **Recast** if neither fits: Promote the embedded clause to a main clause, or replace the relative with a prepositional phrase.
|
|
12
|
+
|
|
13
|
+
**A gap in a prepositional phrase takes its own order.** Pied-pipe the preposition first: "the level against which it is probed", preferred over the stranded "the level that it is probed against". If pied-piping reads stiffly, the stranded relativizer is the second choice and a recast the third. The passive participle is last here rather than first, since the actor is already inside the clause.
|
|
14
|
+
|
|
15
|
+
**A predicate-nominal gap takes the restored relativizer.** "the throwing mock that it is", never "the throwing mock it is". Neither of the other repairs applies to it: A copula does not have a preposition to pied-pipe or an actor to promote into a participle. If the restored relativizer reads stiffly, recast.
|
|
16
|
+
|
|
17
|
+
**A coordinated gap takes a doubled relative or one shared stranded relativizer.** When a direct-object gap coordinates with an oblique one, pied-piping cannot reach the first, which does not have a preposition to pipe. The parallel forms are "the error which it threw or with which it rejected" and "the error that it threw or rejected with".
|
|
18
|
+
|
|
19
|
+
**The shapes, ranked by cost.** The rank follows the embedded subject's form, since the reader must keep that form in mind until the verb appears. Each is an exhibit of the construction, not a model to copy.
|
|
20
|
+
|
|
21
|
+
1. **Quantified noun phrase** (worst): "a dependency every exported tier module imports". The reader absorbs a quantifier and a full noun phrase before any verb discharges the head.
|
|
22
|
+
2. **Definite noun phrase**: "the ticket the branch name encodes".
|
|
23
|
+
3. **Bare noun**: "an idiom developers recognize".
|
|
24
|
+
4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
|
|
25
|
+
|
|
26
|
+
**The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same breath; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does. This rule breaks the habit of reaching for a contact clause to dodge a passive that was never the target.
|
|
27
|
+
|
|
28
|
+
**Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). The anaphoric one-series heads a relative clause under the rule too, though it is not a lexical noun, because a relativizer restores to it: "one that the spy carries". Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. The boundary keys on head type and gap role. Neither a short embedded subject nor a tight word budget exempts anything.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
## Target file set
|
|
2
|
+
|
|
3
|
+
Before reading any file, resolve once the set of files that the run may edit, and never widen it afterwards.
|
|
4
|
+
|
|
5
|
+
**Expanding a path argument.** A path naming a file adds that file. A path naming a directory adds what git lists beneath it:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
git ls-files -- <path>
|
|
9
|
+
git ls-files --others --exclude-standard -- <path>
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
The two forms together cover what git tracks plus what it would track, and both honor `.gitignore`, so `node_modules/`, `dist/`, and every other non-authored tree are excluded without any further configuration.
|
|
13
|
+
|
|
14
|
+
**What never enters the set.** Three kinds of file are excluded, each because an edit to it would be discarded or would rewrite a record:
|
|
15
|
+
|
|
16
|
+
- **Deployed output.** A file containing a `GENERATED FILE` or `<!-- codeassembly-` marker, and anything beneath a harness's own `skills/` or `scripts/` directory. Because the next sync overwrites it, the edit belongs to the source from which it was copied.
|
|
17
|
+
- **Saved artifacts.** Anything beneath the artifact base directory, typically `~/ai-artifacts/`.
|
|
18
|
+
- **Text that nobody here authored.** Vendored third-party sources, generated data, and test fixtures, whatever they contain.
|
|
19
|
+
|
|
20
|
+
<HARD-GATE>
|
|
21
|
+
Never edit a file outside the resolved set. Do not follow imports, expand to siblings, or touch a file merely reachable from one already in the set. Report a hit outside the set to the user alongside the summary; never repair it.
|
|
22
|
+
</HARD-GATE>
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
## Technical recommendations
|
|
2
|
+
|
|
3
|
+
- Default to current best practices. Before recommending an approach, verify it reflects the current state of the ecosystem, not a pattern that was standard two years ago.
|
|
4
|
+
- When unsure whether your knowledge is current, say so and look it up rather than presenting a possibly outdated approach as the answer.
|
|
5
|
+
- Prefer CLI tools over web UI instructions. When a task can be done via a CLI command (e.g., `npm trust`, `gh repo edit`, `gh secret set`), recommend the command, not manual steps in a browser. When multiple commands need to be run, offer to write a script in the most suitable language (other things being equal, prefer bash and TypeScript), following the relevant coding conventions.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
Before saving a spec file, scan adjacent tests for shared-setup runs.
|
|
2
|
+
|
|
3
|
+
- **Parameterize** with `it.each` when the variation is small and the test body is structurally identical.
|
|
4
|
+
- **Extract a named helper** when the variation is bigger, when shared setup belongs behind a helper signature, or when assertion shapes differ per case.
|
|
5
|
+
- **Check the assertions, too.** When the rule is a count or predicate, specific-fixture-label assertions should not repeat per row. Assert specific data flow _once_ in a focused test; assert structurally for the rest.
|
|
6
|
+
|
|
7
|
+
Three or more `it` blocks with identical setup and a single varying input is the most common failure mode in interactive sessions. That material belongs behind a helper or a parameterized table, not in N copies of the same shape.
|
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
A verdict is **baseline** when it does not indicate any concern or needed action:
|
|
2
|
+
|
|
3
|
+
| Dimension | Baseline verdict |
|
|
4
|
+
| ------------ | ---------------- |
|
|
5
|
+
| Drift | `none` |
|
|
6
|
+
| Relevance | `relevant` |
|
|
7
|
+
| Progress | `none` |
|
|
8
|
+
| Advisability | `advisable` |
|
|
9
|
+
|
|
10
|
+
An umbrella's `partial` progress is also baseline. An umbrella is a ticket that has open children and whose only unchecked criterion is "Every child is closed", so it is expected to be partly done until its last child closes. Any other unchecked criterion keeps `partial` progress a concern.
|
|
11
|
+
|
|
12
|
+
Complexity verdicts are purely informational and do not have a baseline.
|
|
@@ -0,0 +1,202 @@
|
|
|
1
|
+
The assessment covers five dimensions: drift, relevance, progress, advisability, and complexity. Each produces a constrained verdict and supporting evidence.
|
|
2
|
+
|
|
3
|
+
### Investigation order
|
|
4
|
+
|
|
5
|
+
When assessing every dimension, investigate them in the order below. Advisability is investigated after progress, synthesizing the prior dimensions' context, and complexity is investigated last so that it benefits from context gathered during drift, relevance, progress, and advisability analysis. **Skip both advisability and complexity when progress is `complete`**; neither has value for finished work.
|
|
6
|
+
|
|
7
|
+
### Drift
|
|
8
|
+
|
|
9
|
+
Determine whether the ticket's factual assumptions still match the codebase.
|
|
10
|
+
|
|
11
|
+
1. Extract file paths, module names, API references, and structural assumptions from the ticket body. A measured count in the body is not an assumption: A figure that has changed since the ticket was written is not drift.
|
|
12
|
+
2. Check whether referenced files and paths still exist.
|
|
13
|
+
3. If the ticket has a last-updated date, examine commits since that date in affected areas: `git log --oneline --no-merges --after="{date}" -- {paths}`
|
|
14
|
+
4. If the ticket does not have a last-updated date, compare the ticket's assumptions against the current state of the affected files.
|
|
15
|
+
5. Assess whether the assumptions hold, have partially drifted, or are no longer valid.
|
|
16
|
+
|
|
17
|
+
**Verdicts:**
|
|
18
|
+
|
|
19
|
+
- 🟢 `none`: All factual assumptions hold; referenced files, APIs, and structures match the ticket's description
|
|
20
|
+
- 🟠 `partial`: Some assumptions are wrong but the ticket is salvageable; the core approach still applies with adjustments
|
|
21
|
+
- 🔴 `severe`: The ticket's factual premise no longer applies; referenced modules have been restructured, removed, or fundamentally changed
|
|
22
|
+
|
|
23
|
+
### Relevance
|
|
24
|
+
|
|
25
|
+
Determine whether the motivation for the ticket still applies.
|
|
26
|
+
|
|
27
|
+
1. Identify the problem or need that the ticket was created to address.
|
|
28
|
+
2. Look at broader codebase changes (not limited to paths mentioned in the ticket). Was the problem solved by a different approach? Was the feature or system targeted by the ticket removed or replaced?
|
|
29
|
+
3. Check whether the conditions that motivated the ticket still exist.
|
|
30
|
+
|
|
31
|
+
This dimension requires understanding intent, not just facts. When signals are ambiguous, prefer `uncertain` over a stronger verdict.
|
|
32
|
+
|
|
33
|
+
**Verdicts:**
|
|
34
|
+
|
|
35
|
+
- 🟢 `relevant`: The motivation still applies; the problem or need described in the ticket still exists
|
|
36
|
+
- 🟠 `uncertain`: Signals suggest the need may have changed but human judgment is required to confirm
|
|
37
|
+
- 🔴 `superseded`: The need has been addressed by other means or the target system no longer exists
|
|
38
|
+
|
|
39
|
+
### Progress
|
|
40
|
+
|
|
41
|
+
Determine whether the described work has been implemented. The output format depends on whether the ticket has acceptance criteria.
|
|
42
|
+
|
|
43
|
+
**When the ticket has acceptance criteria:**
|
|
44
|
+
|
|
45
|
+
1. Extract acceptance criteria from the ticket. These may be checkboxes, numbered lists, or prose descriptions of expected behavior.
|
|
46
|
+
2. For each criterion, examine the codebase to determine whether it has been met.
|
|
47
|
+
3. Present the verdict with a count summary (e.g., "4 of 7 criteria met"), followed by each criterion as a checklist item.
|
|
48
|
+
|
|
49
|
+
**When the ticket does not have acceptance criteria:**
|
|
50
|
+
|
|
51
|
+
1. Identify what the ticket's solution describes: new files, modified APIs, added tests, changed behavior.
|
|
52
|
+
2. Search the codebase for evidence of these artifacts.
|
|
53
|
+
3. Present the verdict followed by evidence bullets describing what has and hasn't been done.
|
|
54
|
+
|
|
55
|
+
**Verdicts:**
|
|
56
|
+
|
|
57
|
+
- 🟢 `complete`: All described work (or all acceptance criteria) has been done
|
|
58
|
+
- 🟠 `partial`: Some of the described work has been done but significant portions remain
|
|
59
|
+
- 🔴 `none`: None of the described work is present in the codebase
|
|
60
|
+
|
|
61
|
+
### Advisability
|
|
62
|
+
|
|
63
|
+
Determine whether the ticket should be implemented as written. Synthesize the four facets defined in `{harness_home_dir}/skills/_data/ticket-evaluation.md` (problem reality, scope correctness, solution soundness, title accuracy) against the codebase and ticket text.
|
|
64
|
+
|
|
65
|
+
1. Apply each facet in turn. Does the underlying observation hold? Is scope right at the appropriate class? Does the proposed solution treat the cause? Does the title accurately describe the work?
|
|
66
|
+
2. Synthesize a verdict from the facet results.
|
|
67
|
+
3. Emit one prose evidence bullet per concern raised by the facets. Do not prefix a bullet with its facet name. Omit bullets entirely when the verdict is `advisable`.
|
|
68
|
+
|
|
69
|
+
Bias toward `advisable`: For a recommendation dimension, false-positive concerns are noisier than false-negative passes. Default to `advisable` unless the codebase shows specific evidence of a facet concern.
|
|
70
|
+
|
|
71
|
+
**Verdicts:**
|
|
72
|
+
|
|
73
|
+
- 🟢 `advisable`: Recommend implementing as written; all four facets pass scrutiny
|
|
74
|
+
- 🟠 `questionable`: Recommend with concerns; one or more facets raise issues warranting human review
|
|
75
|
+
- 🔴 `inadvisable`: Recommend against implementing as written; rework needed before proceeding
|
|
76
|
+
|
|
77
|
+
### Complexity
|
|
78
|
+
|
|
79
|
+
Classify how complex the described work is relative to the current codebase. Reference the complexity classification rubric in `{harness_home_dir}/skills/_data/complexity-classification.md` for level definitions.
|
|
80
|
+
|
|
81
|
+
1. Identify the work surface: files, modules, packages, APIs, interfaces, and dependencies that the ticket describes changing or creating. Verify against the codebase.
|
|
82
|
+
2. Assess cross-cutting extent: how many modules or packages are touched, whether changes cross package boundaries, and whether shared interfaces or data structures are affected.
|
|
83
|
+
3. Assess decision density: whether the work follows established patterns or requires new ones, and whether design choices could go multiple ways.
|
|
84
|
+
4. Classify against the rubric. When characteristics span two levels, prefer the higher level.
|
|
85
|
+
|
|
86
|
+
**Verdicts:**
|
|
87
|
+
|
|
88
|
+
- ⚪ `trivial`: Single-line or purely mechanical; does not require judgment
|
|
89
|
+
- 🟢 `mechanical`: Follows an obvious pattern; single module, without API or behavioral changes
|
|
90
|
+
- 🟠 `involved`: Requires understanding context; touches multiple files or modules; may involve design decisions
|
|
91
|
+
- 🔴 `architectural`: Cross-cutting concerns, new patterns, dependency boundary changes, or far-reaching consequences
|
|
92
|
+
|
|
93
|
+
### Output format
|
|
94
|
+
|
|
95
|
+
Format the assessment using the structure below, with the dimensions in order and advisability and complexity omitted when progress is `complete`.
|
|
96
|
+
|
|
97
|
+
**When the ticket has acceptance criteria:**
|
|
98
|
+
|
|
99
|
+
```markdown
|
|
100
|
+
## Assessment: {ticket title} (#{number})
|
|
101
|
+
|
|
102
|
+
Assessed at {YYYYMMDD-HHMMSSZ} against {short SHA}
|
|
103
|
+
|
|
104
|
+
Δ **Drift:** {emoji} `{verdict}`
|
|
105
|
+
|
|
106
|
+
- {Evidence bullet}
|
|
107
|
+
- {Evidence bullet}
|
|
108
|
+
|
|
109
|
+
🎯 **Relevance:** {emoji} `{verdict}`
|
|
110
|
+
|
|
111
|
+
- {Evidence bullet}
|
|
112
|
+
- {Evidence bullet}
|
|
113
|
+
|
|
114
|
+
📶 **Progress:** {emoji} `{verdict}` ({N} of {M} criteria met)
|
|
115
|
+
|
|
116
|
+
- ✅ {Criterion met}
|
|
117
|
+
- ✅ {Criterion met}
|
|
118
|
+
- ❌ {Criterion not met}
|
|
119
|
+
|
|
120
|
+
🧭 **Advisability:** {emoji} `{verdict}`
|
|
121
|
+
|
|
122
|
+
- {Evidence bullet}
|
|
123
|
+
- {Evidence bullet}
|
|
124
|
+
|
|
125
|
+
🧩 **Complexity:** {emoji} `{label}`
|
|
126
|
+
|
|
127
|
+
- {Evidence bullet}
|
|
128
|
+
- {Evidence bullet}
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
**When the ticket does not have acceptance criteria:**
|
|
132
|
+
|
|
133
|
+
```markdown
|
|
134
|
+
## Assessment: {ticket title} (#{number})
|
|
135
|
+
|
|
136
|
+
Assessed at {YYYYMMDD-HHMMSSZ} against {short SHA}
|
|
137
|
+
|
|
138
|
+
Δ **Drift:** {emoji} `{verdict}`
|
|
139
|
+
|
|
140
|
+
- {Evidence bullet}
|
|
141
|
+
- {Evidence bullet}
|
|
142
|
+
|
|
143
|
+
🎯 **Relevance:** {emoji} `{verdict}`
|
|
144
|
+
|
|
145
|
+
- {Evidence bullet}
|
|
146
|
+
- {Evidence bullet}
|
|
147
|
+
|
|
148
|
+
📶 **Progress:** {emoji} `{verdict}`
|
|
149
|
+
|
|
150
|
+
- {Evidence bullet}
|
|
151
|
+
- {Evidence bullet}
|
|
152
|
+
|
|
153
|
+
🧭 **Advisability:** {emoji} `{verdict}`
|
|
154
|
+
|
|
155
|
+
- {Evidence bullet}
|
|
156
|
+
- {Evidence bullet}
|
|
157
|
+
|
|
158
|
+
🧩 **Complexity:** {emoji} `{label}`
|
|
159
|
+
|
|
160
|
+
- {Evidence bullet}
|
|
161
|
+
- {Evidence bullet}
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
### Emoji mapping
|
|
165
|
+
|
|
166
|
+
Drift, relevance, progress, and advisability use a **concern scale**, on which green means no concern and red means high concern:
|
|
167
|
+
|
|
168
|
+
| Verdict position | Emoji |
|
|
169
|
+
| ---------------- | ----- |
|
|
170
|
+
| No concern | 🟢 |
|
|
171
|
+
| Mixed / unclear | 🟠 |
|
|
172
|
+
| High concern | 🔴 |
|
|
173
|
+
|
|
174
|
+
Complexity uses a **size scale**, on which emojis represent effort and scope, not concern:
|
|
175
|
+
|
|
176
|
+
| Level | Emoji |
|
|
177
|
+
| ----- | ----- |
|
|
178
|
+
| 1 | ⚪ |
|
|
179
|
+
| 2 | 🟢 |
|
|
180
|
+
| 3 | 🟠 |
|
|
181
|
+
| 4 | 🔴 |
|
|
182
|
+
|
|
183
|
+
### Verdict reference
|
|
184
|
+
|
|
185
|
+
| Dimension | ⚪ | 🟢 | 🟠 | 🔴 |
|
|
186
|
+
| ---------------- | --------- | ------------ | -------------- | --------------- |
|
|
187
|
+
| **Drift** | n/a | `none` | `partial` | `severe` |
|
|
188
|
+
| **Relevance** | n/a | `relevant` | `uncertain` | `superseded` |
|
|
189
|
+
| **Progress** | n/a | `complete` | `partial` | `none` |
|
|
190
|
+
| **Advisability** | n/a | `advisable` | `questionable` | `inadvisable` |
|
|
191
|
+
| **Complexity** | `trivial` | `mechanical` | `involved` | `architectural` |
|
|
192
|
+
|
|
193
|
+
### Baseline verdicts
|
|
194
|
+
|
|
195
|
+
<!-- include: ticket-assessment-baseline.md / -->
|
|
196
|
+
|
|
197
|
+
### Assessment principles
|
|
198
|
+
|
|
199
|
+
- **Evidence over opinion**: Every verdict must be supported by specific evidence (file paths, commit SHAs, code references)
|
|
200
|
+
- **Prefer caution on relevance**: Use `uncertain` when signals are ambiguous rather than committing to `superseded`
|
|
201
|
+
- **Bias `advisable` absent evidence**: Every non-baseline advisability verdict calls for a follow-up action; default to `advisable` unless the codebase shows specific evidence of a facet concern
|
|
202
|
+
- **Scale to ticket complexity**: A simple ticket gets a brief assessment; a complex ticket with many acceptance criteria gets a thorough one
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
**Choosing a work type.** Whom a change affects decides its type, not the format of its files. Apply the descriptions in `{harness_home_dir}/skills/_data/work-types.json` to the change itself. Never infer a type from how earlier changes were typed, because many were typed wrongly.
|
|
2
|
+
|
|
3
|
+
**`fix` requires a defect that a consumer meets.** Two questions decide it, in order.
|
|
4
|
+
|
|
5
|
+
1. **Does a consumer meet the behavior that changed?** When none does, the type is the one for that audience (`tests`, `tooling`, `ci`, `internal`), whatever the change repaired. A lint rule, a build script, and a test helper are not consumer-facing, so a repair to one is never `fix`. The same question settles a latent condition: When it could not be observed by any consumer, the change does not repair any defect, and evidence that the condition pre-dated the change is not evidence that it was one.
|
|
6
|
+
2. **Did the effect differ from what its author intended?** Compare the intended effect with the actual one. That the code or the text was written deliberately does not settle it, because a deliberate rule can still produce an effect that its author did not intend. When the effect diverged from the intent, the type is `fix`. When it matched, and the change reflects a new decision about what the intent should be, the type is `feat`. When intent and effect are both unchanged and only the construction differs, the type is `refactor`.
|
|
7
|
+
|
|
8
|
+
The test runs in both directions. `fix` is public tier, so typing an improvement `fix` publishes a "Bug fixes" entry telling every reader that something was broken, and typing a genuine defect `refactor` withholds a repair that a reader needs. A defect in consumer-facing behavior is `fix` whatever else the change does, and neither the branch's bulk nor the ticket's subject displaces it.
|
|
9
|
+
|
|
10
|
+
- **Repo-agnostic guidance is source code.** Skills, skill data, partials, subagent definitions, and rulebooks written for use in any repository take the type that the same change to source code would take. A wording correction is `fix` when the text failed to say what its author already intended, and `feat` when it states a new decision; the repair of a writing-rule violation is the former. A restructuring is `refactor` only when it leaves the text read by the agent unchanged, as extracting a partial does. A token cut that does not change any behavior is `perf`.
|
|
11
|
+
- **Guidance on working in one repository is `ai`.** That repository's `AGENTS.md`, its repo-local skills, and its agent configuration take `ai`.
|
|
12
|
+
- **Guidance to agents is never `docs`.** `docs` is documentation for human readers, and a change confined to code comments is `docs`.
|
|
13
|
+
- **Content decides.** What guidance says decides whether it is repo-agnostic, not its file name, location, or format.
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
# The content-format contract against which this root is authored; see "Content-format version" in packages/agents/docs/project-declaration.md.
|
|
2
|
+
format: 2
|
|
3
|
+
|
|
4
|
+
# The TypeScript helpers that `codeassembly bundle-helpers` bundles into this root, both paths relative to this file.
|
|
5
|
+
helpers:
|
|
6
|
+
- entry: ../src/kb-add/cli.ts
|
|
7
|
+
out: skills/kb-add/kb-add.mjs
|
|
8
|
+
- entry: ../src/kb-edit/cli.ts
|
|
9
|
+
out: skills/kb-edit/kb-edit.mjs
|
|
10
|
+
- entry: ../src/kb-curate/cli.ts
|
|
11
|
+
out: skills/kb-curate/kb-curate.mjs
|
|
12
|
+
- entry: ../src/kb-retrieve/cli.ts
|
|
13
|
+
out: skills/kb-retrieve/kb-retrieve.mjs
|
|
14
|
+
- entry: ../src/kb-retrieve-events/cli.ts
|
|
15
|
+
out: skills/kb-retrieve-events/kb-retrieve-events.mjs
|
|
16
|
+
- entry: ../src/update-jira-ticket/cli.ts
|
|
17
|
+
out: skills/update-jira-ticket/update-jira-ticket.mjs
|
|
18
|
+
- entry: ../src/derive-session-context/cli.ts
|
|
19
|
+
out: skills/derive-session-context/derive-session-context.mjs
|
|
20
|
+
- entry: ../src/capture-event/cli.ts
|
|
21
|
+
out: skills/capture-event/capture-event.mjs
|
|
22
|
+
- entry: ../src/capture-lede-decision/cli.ts
|
|
23
|
+
out: skills/capture-lede-decision/capture-lede-decision.mjs
|
|
24
|
+
- entry: ../src/kb-update-events/cli.ts
|
|
25
|
+
out: skills/kb-update-events/kb-update-events.mjs
|
|
26
|
+
- entry: ../src/feedback-memories/cli.ts
|
|
27
|
+
out: skills/migrate-feedback-memories/feedback-memories.mjs
|
|
28
|
+
- entry: ../src/groom-backlog/cli.ts
|
|
29
|
+
out: skills/groom-backlog/groom-backlog.mjs
|
|
30
|
+
- entry: ../src/pull-from-backlog/cli.ts
|
|
31
|
+
out: skills/pull-from-backlog/pull-from-backlog.mjs
|
|
32
|
+
- entry: ../src/revise-prose/cli.ts
|
|
33
|
+
out: skills/revise-prose/revise-prose.mjs
|
|
34
|
+
- entry: ../src/streamline-guidance/cli.ts
|
|
35
|
+
out: skills/streamline-guidance/streamline-guidance.mjs
|
|
36
|
+
- entry: ../src/describe-change/cli.ts
|
|
37
|
+
out: scripts/describe-change.mjs
|
|
38
|
+
- entry: ../src/select-lede-exemplars/cli.ts
|
|
39
|
+
out: scripts/select-lede-exemplars.mjs
|
|
40
|
+
- entry: ../src/resolve-review-run/cli.ts
|
|
41
|
+
out: scripts/resolve-review-run.mjs
|
|
42
|
+
- entry: ../src/manage-jira-ticket/cli.ts
|
|
43
|
+
out: scripts/manage-jira-ticket.mjs
|
|
44
|
+
- entry: ../src/merge-gh-pr/cli.ts
|
|
45
|
+
out: skills/merge-gh-pr/merge-gh-pr.mjs
|
|
46
|
+
- entry: ../src/index-prototypes/cli.ts
|
|
47
|
+
out: skills/index-prototypes/index-prototypes.mjs
|
|
48
|
+
- entry: ../src/select-pr-ticket/cli.ts
|
|
49
|
+
out: skills/review-gh-pr/select-pr-ticket.mjs
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: all
|
|
3
|
+
description: The whole content library (every rulebook, skill, and subagent), computed automatically.
|
|
4
|
+
members: '@library'
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# All
|
|
8
|
+
|
|
9
|
+
The whole-catalog collection. `members: '@library'` resolves to every rulebook, skill, and subagent in the content library, computed at resolution time so that a newly added artifact joins automatically without an edit here. Collections are excluded: The resolver never emits them, and "every collection" would be self-referential.
|
|
10
|
+
|
|
11
|
+
This is the escape hatch, not the expected declaration. It does not make any claim about its members: It deploys the vetted, the unexamined, and the artifacts deliberately left out of every collection alike, and a newly added artifact joins it before anyone has read it. A consumer should declare the collections whose dispositions it wants instead, and reach for this one only to take the catalog whole.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: atlassian
|
|
3
|
+
description: Skills that act on Bitbucket pull requests and Jira work items.
|
|
4
|
+
members:
|
|
5
|
+
skills:
|
|
6
|
+
- create-bitbucket-pr
|
|
7
|
+
- merge-bb-pr
|
|
8
|
+
- review-bb-pr
|
|
9
|
+
- update-jira-ticket
|
|
10
|
+
---
|
|
11
|
+
|
|
12
|
+
# Atlassian
|
|
13
|
+
|
|
14
|
+
Every member acts on one of Atlassian's hosted products: creating, reviewing, and merging Bitbucket pull requests, and creating and updating Jira work items. A consumer should declare this collection only if one of those products is in use.
|
|
15
|
+
|
|
16
|
+
Nothing outside this collection reaches a member. `create-pr`, `merge-pr`, `review-pr`, and `create-ticket` each name one through an optional invocation token, and `collection-dispositions.unit.test.ts` fails when a token naming a member is written in its required form.
|