codeassembly-guidance 0.6.0 → 0.8.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 +446 -0
- package/CHANGELOG.md +107 -0
- package/README.md +47 -51
- package/bin/codeassembly-validate-preferences.js +2 -8
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-unsearched-private-stores.md +6 -0
- package/content/_partials/plain-speech.md +2 -2
- package/content/_partials/ticket-assessment.md +3 -3
- package/content/codeassembly-content.yaml +8 -0
- package/content/collections/recommended.md +6 -0
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
- package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +2 -2
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +7 -1
- package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
- package/content/guidance/shared/AGENTS.md +3 -4
- package/content/scripts/README.md +1 -1
- package/content/scripts/check-branch-currency.mjs +7 -7
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +89 -89
- package/content/scripts/manage-jira-ticket.mjs +162 -160
- package/content/scripts/select-lede-exemplars.mjs +85 -85
- package/content/scripts/validate-preferences.mjs +41 -41
- package/content/skills/_data/artifact-conventions.md +3 -3
- package/content/skills/_data/entry-points.md +1 -1
- package/content/skills/_data/project-stage.md +9 -5
- package/content/skills/_data/reduced-object-relatives.md +15 -0
- package/content/skills/_data/spike-conventions.md +16 -6
- package/content/skills/_data/ticket-evaluation.md +3 -0
- package/content/skills/_partials/implementation-order-list.md +27 -0
- package/content/skills/_partials/merge-settled-criterion.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +2 -2
- package/content/skills/_partials/plan-template.md +3 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
- package/content/skills/_partials/split-launch-prompts.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -3
- package/content/skills/analyze-performance/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +4 -4
- package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
- package/content/skills/assess-ticket/SKILL.md +3 -1
- package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
- package/content/skills/assess-usability/SKILL.md +4 -4
- package/content/skills/capture-event/SKILL.md +20 -11
- package/content/skills/capture-event/capture-event.mjs +123 -123
- package/content/skills/capture-feedback/SKILL.md +2 -1
- package/content/skills/capture-lede-decision/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +97 -97
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/condense-branch/SKILL.md +18 -36
- package/content/skills/condense-branch/condense-branch.mjs +17 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-devlog/SKILL.md +4 -4
- package/content/skills/create-gh-pr/SKILL.md +9 -11
- package/content/skills/create-pr/SKILL.md +10 -12
- package/content/skills/create-ticket/SKILL.md +22 -15
- package/content/skills/create-ticket/resolve-ticket-target.mjs +92 -92
- package/content/skills/curate-feedback/SKILL.md +2 -2
- package/content/skills/curate-feedback/curate-feedback.mjs +82 -82
- package/content/skills/derive-session-context/derive-session-context.mjs +120 -120
- package/content/skills/design-and-plan/SKILL.md +10 -8
- package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
- package/content/skills/implement-plan/SKILL.md +4 -2
- package/content/skills/implementation-order/implementation-order.mjs +67 -0
- package/content/skills/index-prototypes/SKILL.md +2 -2
- package/content/skills/investigate-spike/SKILL.md +3 -3
- package/content/skills/kb-add/SKILL.md +12 -3
- package/content/skills/kb-add/kb-add.mjs +88 -88
- package/content/skills/kb-curate/kb-curate.mjs +88 -88
- package/content/skills/kb-edit/kb-edit.mjs +90 -90
- package/content/skills/kb-retrieve/SKILL.md +8 -3
- package/content/skills/kb-retrieve/kb-retrieve.mjs +104 -104
- package/content/skills/kb-retrieve-events/SKILL.md +8 -3
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +113 -113
- package/content/skills/kb-update-events/kb-update-events.mjs +92 -92
- package/content/skills/lesson-clusters/lesson-clusters.mjs +102 -102
- package/content/skills/list-gh-progress-items/SKILL.md +36 -0
- package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
- package/content/skills/list-implementation-order/SKILL.md +23 -0
- package/content/skills/merge-bb-pr/SKILL.md +40 -19
- package/content/skills/merge-gh-pr/SKILL.md +34 -23
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +13 -8
- package/content/skills/merge-pr/SKILL.md +64 -31
- package/content/skills/migrate-feedback-memories/SKILL.md +1 -0
- package/content/skills/plan/SKILL.md +5 -3
- package/content/skills/prepare-prototype-brief/SKILL.md +5 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
- package/content/skills/refine-plan/SKILL.md +5 -3
- package/content/skills/refine-prototype/SKILL.md +2 -1
- package/content/skills/respond-to-review/SKILL.md +4 -4
- package/content/skills/review-bb-pr/SKILL.md +1 -2
- package/content/skills/review-branch/SKILL.md +19 -14
- package/content/skills/review-criteria/SKILL.md +2 -2
- package/content/skills/review-gh-pr/SKILL.md +1 -2
- package/content/skills/review-pr/SKILL.md +2 -3
- package/content/skills/revise-prose/revise-prose.mjs +109 -109
- package/content/skills/save-artifact/SKILL.md +4 -6
- package/content/skills/save-plan/SKILL.md +4 -2
- package/content/skills/start-ticket/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +80 -80
- package/content/skills/summarize-change/SKILL.md +20 -9
- package/content/skills/summarize-chat/SKILL.md +2 -2
- package/content/skills/testing-conventions/SKILL.md +2 -2
- package/content/skills/triage-feedback/SKILL.md +6 -2
- package/content/skills/triage-spike-findings/SKILL.md +33 -24
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
- package/content/skills/update-project-guidance/SKILL.md +1 -1
- package/content/skills/wrap-up/SKILL.md +8 -4
- package/content/skills/write-progress-report/SKILL.md +111 -0
- package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
- package/content/subagents/disposition-challenger.md +7 -6
- package/content/subagents/entry-drafter.md +2 -0
- package/content/subagents/usability-assessor.md +3 -2
- package/package.json +13 -12
- package/schemas/preferences.v1.json +82 -8
- package/schemas/work-types.v1.json +1 -1
|
@@ -13,7 +13,7 @@ The artifact directory is the developer's audit trail of development. Its plans,
|
|
|
13
13
|
|
|
14
14
|
## Directory structure
|
|
15
15
|
|
|
16
|
-
All artifacts are stored under a configurable base directory (`base_dir`, default `~/ai-artifacts`). Invoke the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) to resolve `artifact_base_dir
|
|
16
|
+
All artifacts are stored under a configurable base directory (`base_dir`, default `~/ai-artifacts`). Invoke the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) to resolve the directories. Its manifest is the source of each: `artifact_base_dir` for `{base_dir}/`, `project_artifact_dir` for `{base_dir}/projects/{project-slug}/`, and `ticket_dir` for `{base_dir}/projects/{project-slug}/tickets/{ticket-id}/`, which is `null` when the branch does not encode a ticket. The tree illustrates the layout; read the paths from the manifest rather than composing them:
|
|
17
17
|
|
|
18
18
|
```
|
|
19
19
|
{base_dir}/
|
|
@@ -141,7 +141,7 @@ The reader does still hard-fail on malformed YAML, missing git state, and shape
|
|
|
141
141
|
{base_dir}/projects/{project-slug}/tickets/{ticket-id}/
|
|
142
142
|
```
|
|
143
143
|
|
|
144
|
-
Ticket-level artifacts and run directories are both stored here
|
|
144
|
+
Ticket-level artifacts and run directories are both stored here, in the manifest's `ticket_dir`. Its last segment is `ticket_id`, which includes any prefix other than `#` (see [Ticket ID](#ticket-id)). When `ticket_dir` is `null`, `save-artifact` states the directory to use.
|
|
145
145
|
|
|
146
146
|
### Run paths
|
|
147
147
|
|
|
@@ -160,7 +160,7 @@ Ticket-level artifacts and run directories are both stored here. Invoke the bund
|
|
|
160
160
|
| feedback-triage | `feedback-triage` | `{base_dir}/projects/{project-slug}/feedback-triage/` |
|
|
161
161
|
| plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
|
|
162
162
|
|
|
163
|
-
Non-ticket paths are relative to the project directory
|
|
163
|
+
Non-ticket paths are relative to the project directory, the manifest's `project_artifact_dir`. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with three exceptions: `deferred-findings`, `feedback-curation`, and `feedback-triage` are hardcoded and cannot be overridden.
|
|
164
164
|
|
|
165
165
|
Devlogs, deferred-findings, feedback-curation, and feedback-triage artifacts are dual-homed: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket-id}/`; otherwise they fall back to the project-scoped paths above (`devlogs/`, `deferred-findings/`, `feedback-curation/`, and `feedback-triage/`). All filenames in these types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
|
|
166
166
|
|
|
@@ -6,7 +6,7 @@ The skill that opens the work in a ticket's worktree follows from the ticket's s
|
|
|
6
6
|
|
|
7
7
|
- **The ticket's state**: open or closed, from the platform fetch in [ticket source resolution](ticket-source-resolution.md#platform-specific-fetch).
|
|
8
8
|
- **The branch's pull request**: `pr_url` from the session-context manifest, or else the pull request whose head is `branch_name` in any state (on GitHub, `gh pr list --head {branch_name} --state all --json url,state`). `pr_url` is usually null on a ticket branch, so the lookup is the common case.
|
|
9
|
-
- **The ticket directory**: `
|
|
9
|
+
- **The ticket directory**: The manifest's `ticket_dir`, and the artifact types that [artifact conventions](artifact-conventions.md) defines. The newest plan is the one that the plan resolution of {skill?:implement-plan} selects (its [process](../implement-plan/SKILL.md#process), step 2): the greatest filename prefix across `*_plan.md` and `*_plan-v*.md`, never `*_plan-review.md`. The newest artifact of any other type is the one with the greatest filename prefix.
|
|
10
10
|
|
|
11
11
|
## Routes
|
|
12
12
|
|
|
@@ -1,12 +1,15 @@
|
|
|
1
1
|
# Project stage
|
|
2
2
|
|
|
3
|
-
A project declares its stage in its own `.agents/preferences.yaml`, under `project`, and the session-context manifest reports each value as `project_maturity`, `project_sensitivity`, and `project_audience`, `null` when the project does not declare it. The global preferences file never supplies a stage, because a stage describes one
|
|
3
|
+
A project declares its stage in its own `.agents/preferences.yaml`, under `project`, and the session-context manifest reports each value as `project_maturity`, `project_sensitivity`, and `project_audience`, `null` when the project does not declare it. A subdirectory, such as one experiment in a repository of experiments, declares its own stage as an entry of `project.stages`: a `path` relative to the repository root and the keys that it overrides. The manifest reports the entries as `project_stages`, each with the values that it inherits from the project filled in. The global preferences file never supplies a stage, because a stage describes one repository or a part of one.
|
|
4
|
+
|
|
5
|
+
The stage that governs a piece of work is the entry whose `path` contains the work's paths, matched at a directory boundary, with the longest containing path winning; a path under no entry takes the project's stage. When the work touches paths under more than one stage, each key takes its most demanding value among them. The table below lists each key's values from the least demanding to the most.
|
|
4
6
|
|
|
5
7
|
## Values
|
|
6
8
|
|
|
7
9
|
| Key | Value | Meaning |
|
|
8
10
|
| ------------- | -------------- | -------------------------------------------------------------------------------- |
|
|
9
|
-
| `maturity` | `
|
|
11
|
+
| `maturity` | `exploration` | The output's shape is still being found, and nothing depends on it yet. |
|
|
12
|
+
| | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
|
|
10
13
|
| | `early` | In use by others, but the shape is still changing; downtime is tolerated. |
|
|
11
14
|
| | `production` | Others depend on it; downtime and data loss have real costs. |
|
|
12
15
|
| `sensitivity` | `low` | Nothing that would harm anyone if published. |
|
|
@@ -19,8 +22,9 @@ A project declares its stage in its own `.agents/preferences.yaml`, under `proje
|
|
|
19
22
|
## What each value implies
|
|
20
23
|
|
|
21
24
|
- **Security.** `owner` with `low` sensitivity needs only what keeps the owner's own credentials out of the repository; access control beyond the host's own login is machinery without an asset to protect. `personal` data warrants access limited to the people that it concerns. Authentication with several factors, rate limits, and origin checks are needed for `public` users or `confidential` data.
|
|
22
|
-
- **Availability.** `hobby`
|
|
25
|
+
- **Availability.** `exploration` and `hobby` tolerate a service that runs only while the owner works, such as a local process or a database on the owner's machine. `early` tolerates downtime and manual recovery. Hosted, always-available infrastructure and backups are needed for `production`.
|
|
23
26
|
- **Infrastructure.** Choose the least infrastructure on which the project runs at its declared stage: a file before a database, a local process before a hosted service, one environment before several.
|
|
27
|
+
- **Verification.** An output is unsettled while the governing maturity is `exploration`, or while the work is a spike, a proof of concept, a prototype, or an agent whose output the developer has not approved. While an output is unsettled, the developer judges it by reading it on real inputs, starting from the user's own example of the output when one exists. Golden references, answer keys, gated evals, and exhaustive fixtures wait until the developer approves an output as the target, and are frozen from it; any built earlier are provisional, not a contract. Unit tests of the deterministic code around the output are outside this rule.
|
|
24
28
|
|
|
25
29
|
## Rules
|
|
26
30
|
|
|
@@ -28,5 +32,5 @@ A project declares its stage in its own `.agents/preferences.yaml`, under `proje
|
|
|
28
32
|
- **Default to the least machinery that works for the declared stage.** Read [design priorities](design-priorities.md) against the stage: Behavioral correctness covers the cases that matter at that stage.
|
|
29
33
|
- **Escalate only for a named asset or need.** Add security, availability, or infrastructure beyond what the stage implies only when the design names what it protects or serves, such as "the tokens table holds the owner's API keys". State the asset or need in the ticket.
|
|
30
34
|
- **Make added hardening switchable.** A safeguard added beyond the stage, such as an origin check or a rate limit, is switched by configuration, so that a preview deployment or a local run can work without it.
|
|
31
|
-
- **Ask for an undeclared value; never infer it.** An undeclared value is a preference for which the agent holds no evidence, so it is in the gated class: Ask the developer rather than infer enterprise requirements from silence. Once the developer answers, declare the value in the project's `.agents/preferences.yaml` and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
|
|
32
|
-
- **Record the premises.** State each value that decided a security, availability, or
|
|
35
|
+
- **Ask for an undeclared value; never infer it.** An undeclared value is a preference for which the agent holds no evidence, so it is in the gated class: Ask the developer rather than infer enterprise requirements from silence. Ask about verification only when the answer decides it: Work that is unsettled by its kind, such as a spike, does not need the maturity. Once the developer answers, declare the value in the project's `.agents/preferences.yaml`, under `project.stages` when it describes a subdirectory, and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
|
|
36
|
+
- **Record the premises.** State each value that decided a security, availability, infrastructure, or verification question where the work records its decisions: in a ticket's `## Context`, one sentence per premise naming the value and the decision that it settled, and in a product's design doc.
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# Reduced object relatives: rare cases
|
|
2
|
+
|
|
3
|
+
The "Reduced object relatives" rule of the writing preferences governs these cases, which its repairs do not settle on their own.
|
|
4
|
+
|
|
5
|
+
## A gap after a copula
|
|
6
|
+
|
|
7
|
+
**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.
|
|
8
|
+
|
|
9
|
+
## A coordinated gap
|
|
10
|
+
|
|
11
|
+
**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 apply to 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".
|
|
12
|
+
|
|
13
|
+
## The anaphoric one-series as head
|
|
14
|
+
|
|
15
|
+
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".
|
|
@@ -39,7 +39,7 @@ The concision and content-placement doctrines for feature tickets and plans appl
|
|
|
39
39
|
|
|
40
40
|
- [ ] {A decision that the findings must make possible.}
|
|
41
41
|
|
|
42
|
-
Deliverable: a findings & recommendation artifact, and the closing post on this ticket.
|
|
42
|
+
Deliverable: a findings & recommendation artifact, and the closing post on this ticket, followed by the ticket's close.
|
|
43
43
|
```
|
|
44
44
|
|
|
45
45
|
`Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
|
|
@@ -81,7 +81,7 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
|
|
|
81
81
|
|
|
82
82
|
## Deliverable
|
|
83
83
|
|
|
84
|
-
{The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
|
|
84
|
+
{The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, followed by the ticket's close, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
|
|
85
85
|
```
|
|
86
86
|
|
|
87
87
|
Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior, and it names the [closing post](#closing-post); a step does not have a test or documentation criterion.
|
|
@@ -90,18 +90,22 @@ The `investigate-spike` skill carries out a spike plan.
|
|
|
90
90
|
|
|
91
91
|
## Closing post
|
|
92
92
|
|
|
93
|
-
The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
|
|
93
|
+
The agent that ends a spike posts its conclusion on the ticket as a comment, then closes the ticket as completed. The post contains:
|
|
94
94
|
|
|
95
95
|
- The answer to each of the ticket's questions to answer.
|
|
96
96
|
- The recommendation on each of the ticket's decisions to enable.
|
|
97
97
|
- The counts and the proposed groupings, when the spike produced them.
|
|
98
98
|
- Links to the published page, when the spike published one, and to the findings artifact, with the artifact's path written `~/`-relative, so that the post does not publish a home-directory path.
|
|
99
99
|
|
|
100
|
-
The skill that ends the spike offers the post. When the findings leave an item without a disposition, the triage round that disposes of them on the same ticket ends the spike: `triage-spike-findings` offers the post, and the skill that produced the findings names the triage as its next step without offering the post, which could not yet answer the decisions to enable. When the findings leave nothing to triage, the skill that produced them offers it. A follow-up triage ticket for a later batch does not take a closing post, because its dispositions comment is its record
|
|
100
|
+
The skill that ends the spike offers the post. When the findings leave an item without a disposition and the ticket is on a [triage platform](#triage-platforms), the triage round that disposes of them on the same ticket ends the spike: `triage-spike-findings` offers the post, and the skill that produced the findings names the triage as its next step without offering the post, which could not yet answer the decisions to enable. When the findings leave nothing to triage, the skill that produced them offers it. A follow-up triage ticket for a later batch does not take a closing post, because its dispositions comment is its record: `triage-spike-findings` closes it as completed, without a post, once that comment is posted, under the confirmation that covers the round's writes. The post on the original ticket names the follow-ups.
|
|
101
101
|
|
|
102
|
-
Offer the post as
|
|
102
|
+
Offer the post and the close as one item in the closing action-items block of that skill, show the post's body, and name both actions in the ask: "Post this conclusion on #420 and close it as completed?". Make both writes only on consent: They are remote writes, and the developer is the one who can tell whether a finding is fit for the ticket's tracker and whether the spike is done. Consent to the offer is the developer's call on closing the ticket. When the developer declines, post nothing and leave the ticket open. When the session does not have a ticket, do not offer it.
|
|
103
103
|
|
|
104
|
-
|
|
104
|
+
Before writing, read the ticket's comments and its state, and decide each write on its own, so that a rerun neither posts the conclusion twice nor fails on a closed ticket:
|
|
105
|
+
|
|
106
|
+
- Post the conclusion unless a comment already opens with the post's first line. Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file).
|
|
107
|
+
- Close a GitHub ticket with `gh issue close {number} --reason completed` only while its state is `OPEN`.
|
|
108
|
+
- Make both writes on a Jira ticket with `node {harness_home_dir}/scripts/manage-jira-ticket.mjs close --key {key} --post {body file}`, which makes both checks and transitions the ticket only while its status category is not `done`. The repository's `integrations.jira.done_status` preference names the status to which it transitions. When `acli` is unavailable or signed in to another site, make the same two checks through the Jira client that {skill?:update-jira-ticket} names.
|
|
105
109
|
|
|
106
110
|
## Findings batches
|
|
107
111
|
|
|
@@ -109,6 +113,12 @@ A batch is the set of items that one triage round inventories: the proposals, fi
|
|
|
109
113
|
|
|
110
114
|
Each batch has a ticket of its own, which covers the assessment that produced the batch and the triage round that disposes of it, so the ticket's [closing post](#closing-post) follows the triage round. An assessment that spans more than one unit is an umbrella with one child per unit, each child covering that unit's assessment and triage round and blocked by the child before it, so that each round runs after the earlier rounds have posted their dispositions and can read them. A findings artifact that holds more than 10 items is triaged in several batches, each on its own ticket, as `triage-spike-findings` states.
|
|
111
115
|
|
|
116
|
+
## Triage platforms
|
|
117
|
+
|
|
118
|
+
`triage-spike-findings` supports GitHub and Jira. The platform is where the tickets live, resolved as {skill?:create-ticket} step 3 resolves it, not the code host that the session-context manifest's `scm` names: A Bitbucket repository can keep its tickets in Jira.
|
|
119
|
+
|
|
120
|
+
On a ticket on any other platform, the skill that produced the findings does not name the triage as its next step: It names the items that the findings leave for disposal by hand, and offers the [closing post](#closing-post) as it does when the findings leave nothing to triage. `triage-spike-findings` stops at its preflight on such a ticket.
|
|
121
|
+
|
|
112
122
|
## Aligning a spike
|
|
113
123
|
|
|
114
124
|
When `align-ticket-with-implementation` reconciles a spike, the branch's "implementation" is the findings: Reconcile whether the investigation answered its questions and reached a recommendation, not whether the branch met acceptance criteria. Align the ticket's questions and decisions to what the investigation actually concluded.
|
|
@@ -7,7 +7,10 @@ The author may have framed it poorly, missed the actual problem, scoped it too n
|
|
|
7
7
|
- **Is the problem real?** Reproduce or verify the underlying observation, not just the framing.
|
|
8
8
|
- **Is the scope right?** Look for related instances of the same defect class, neighboring code paths, or assumptions that don't hold beyond the ticket's frame. Scope can grow, not only shrink: By default, the agent folds work required by the problem into the current change rather than deferring it; see [scope-and-deferral](./scope-and-deferral.md). Scope can also be too large: When the ticket contains two or more pieces that can each be merged and verified on their own, raise the split before design begins, while the cut still requires an edit rather than a rewrite of the ticket, new children, a re-cut plan, and work already committed against it.
|
|
9
9
|
- **Is the proposed solution sound?** A ticket may include a recommended fix that solves the symptom but not the cause, or that fixes the cause less well than an alternative. Apply the [design priorities](./design-priorities.md) criteria: A convenient-but-wrong fix is unsound, even if it matches surrounding code.
|
|
10
|
+
- **Can its pull request settle each criterion?** When the ticket's work is a code change, apply the test of the merge-settled criterion convention below to each acceptance criterion. Report each criterion that fails it, and recommend the ticket to which it moves: the ticket that consumes the change, or a new ticket when the tracker does not contain one.
|
|
10
11
|
- **Is the title accurate?** "Flaky test in X" may be a hygiene anti-pattern that exists in three places. Reframe titles when the underlying truth is broader or different.
|
|
11
12
|
- **Is the change worth making?** Synthesize the above: Doing nothing, or doing something narrower, may be the right call. Don't treat acceptance as the default.
|
|
12
13
|
|
|
14
|
+
<!-- include: ../_partials/merge-settled-criterion.md / -->
|
|
15
|
+
|
|
13
16
|
When evaluation reveals a divergence from the ticket as written, raise the observation to the user before designing, but lead with the substantive finding, not the ticket. The ticket's job was to start the conversation; once it has started, the codebase reality and the user's judgment decide, not the original wording.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
## Implementation-order list
|
|
2
|
+
|
|
3
|
+
Print open tickets that have work of their own in the order in which to implement them, as a tree for a narrow column. An umbrella, a ticket that has sub-issues, is left out, because its children do its work; the step names the children for them to be listed. The step that links here names the tickets, in the order in which it reached them, an `--external` entry for each ticket outside GitHub, and an `--edge` for each dependency that the tracker does not record. A bundled helper reads the tickets, orders them, and writes the fixed part of every line. You shorten the titles and mark the publish gates.
|
|
4
|
+
|
|
5
|
+
1. **Run the helper.**
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
node {harness_home_dir}/skills/implementation-order/implementation-order.mjs \
|
|
9
|
+
--ticket {OWNER/REPO#N} --external "{REPOSITORY}:{KEY}={Title}" --edge "{BLOCKER}>{BLOCKED}"
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
Write a GitHub ticket as `OWNER/REPO#N`, taking the repository from the ticket's URL. For a ticket outside GitHub, `{REPOSITORY}` is the repository in which the ticket is implemented, as `OWNER/NAME` when the owner is known and `NAME` otherwise; it gives the ticket that repository's prefix. Omit `{REPOSITORY}:` only when the repository is not known. Repeat each flag once per ticket or edge. Each side of an edge is `OWNER/REPO#N` or the key, without its repository, that an `--external` declares, and the blocked side is a listed ticket. On a non-zero exit, report the helper's stderr and do not print the list: A list that lacks a ticket misstates the order.
|
|
13
|
+
|
|
14
|
+
The helper prints `{"tickets": [...], "omitted": [...], "cycle": [...]}`. `tickets` is in list order. `omitted` names each ticket that the list leaves out, with its `reason`: `closed`, or `umbrella` for an open ticket that has sub-issues.
|
|
15
|
+
|
|
16
|
+
2. **Shorten each title** to at most the ticket's `titleBudget` characters. Cut words rather than end with an ellipsis, and keep the leading verb. Leave a title that already fits as it is.
|
|
17
|
+
|
|
18
|
+
3. **Find the publish gates.** A gate follows a ticket when its change must be published, and the dependency upgraded in a consuming repository, before a ticket that it blocks can start. Look for one wherever a ticket blocks a ticket in another repository; `crossRepository` marks those among `otherBlockers`, and a child in the tree whose `repository` differs from its parent's is another. The tracker does not record whether the blocked repository consumes the blocking one as a published package, so judge that from the tickets and the conversation.
|
|
19
|
+
|
|
20
|
+
4. **Print the list** as one fenced block. For each ticket, in order:
|
|
21
|
+
- Its line: `lead`, then the shortened title.
|
|
22
|
+
- Its `blockerLine`, when that is not null.
|
|
23
|
+
- Its gate, when step 3 found one: `gateLead`, then the package's name, then `, upgrade in `, then the prefix of each consuming repository in the list, separated by commas. Name the package rather than the repository when the two differ.
|
|
24
|
+
|
|
25
|
+
A ticket's place states its blocker: It is indented under the ticket that blocks it. `blockerLine` names the blockers that the indent does not state.
|
|
26
|
+
|
|
27
|
+
When `cycle` is not empty, add a last line inside the block: `⚠️`, then the labels of the tickets in `cycle`, then `block each other`.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
**Merge-settled criterion convention:** When writing a ticket whose work is a code change, state only the criteria that its pull request can satisfy or falsify. The test is whether the pull request's tests, checks, or review can show the criterion to hold or to fail at merge. A criterion that fails the test is an operational step, which depends on elapsed time, on deployed state, or on a run against shared data, such as "a deployed agent, run a day after seeding, places every fixture in its expected section". Move such a step to the ticket that consumes the change, or propose a ticket of its own for it when the tracker does not contain one that consumes the change, so that the code ticket can close when its pull request merges.
|
|
@@ -65,9 +65,9 @@ Select the recommended option by checking these rules in order and stopping at t
|
|
|
65
65
|
|
|
66
66
|
When rule 1 matches, the rendered option must name that decision on a `➕` line. Being unable to write the line means rule 1 did not match.
|
|
67
67
|
|
|
68
|
-
2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either.
|
|
68
|
+
2. **Split the ticket**: Recommend only when the plan is too large for one implement-and-review pass, and it contains two or more pieces that can each be merged and verified on their own. Both halves are required: Too large without a seam is not a match, and a seam in a plan that one pass would cover is not one either. A plan that touches two or more repositories matches whatever its size: Each repository is a piece, per the ticketing preferences.
|
|
69
69
|
|
|
70
|
-
A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`.
|
|
70
|
+
A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. The `➕` line names the size and the pieces, each with the tasks that it takes: `➕ eleven tasks across three packages, and two pieces ship on their own: the schema change (tasks 1–4), then the reader that consumes it (tasks 5–11)`. For a plan that spans repositories, the pieces are the repositories: `➕ three tasks across two repositories: the helper in williamthorsen/codeassembly (task 1), then the skill that calls it here (tasks 2–3)`.
|
|
71
71
|
|
|
72
72
|
Structural properties (new module boundaries, changed interfaces, several packages) make a plan _more likely_ to be too large. They are evidence to weigh, and none of them matches rule 2 on its own.
|
|
73
73
|
|
|
@@ -52,13 +52,15 @@
|
|
|
52
52
|
|
|
53
53
|
**Per-task test criterion:** When a task creates or modifies testable behavior, its acceptance criteria must include a test criterion that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
|
|
54
54
|
|
|
55
|
+
**Per-task verification guidance:** When the work's output is unsettled per [project stage](../_data/project-stage.md), each task that produces the output verifies it through a reading round rather than a golden reference, an answer key, or an eval gate: The agent runs the output on real inputs, starting from the user's own example of the output when one exists, and presents it, and the developer's judgment of it is the task's `**Residue:**`, because only the developer can approve a target. Plan a golden reference or an eval only as a task that follows the developer's approval of an output, and freeze it from that output.
|
|
56
|
+
|
|
55
57
|
**Per-task documentation criterion:** When a task adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), its acceptance criteria must include updating documentation, help text, and usage examples, including removal of references to anything that no longer exists.
|
|
56
58
|
|
|
57
59
|
**Per-task README guidance:** When a task writes or revises a README, consult {rulebook:readme-conventions} while planning the task. Its key decisions name the rulebook, the table row that fits the README, and what that row says the README leads with, keeps, and omits, so that the constraints are available to an implementer that cannot load the rulebook.
|
|
58
60
|
|
|
59
61
|
**Per-task documentation placement:** When a task writes or revises guidance or documentation, its key decisions name the source that defines each fact that the task documents, and the task writes a pointer to that source rather than a copy, per the "Documentation placement" section of the shared agent instructions.
|
|
60
62
|
|
|
61
|
-
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions} and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, the model, the placement, and the state attribute of each control that reveals a region or toggles a setting, the cue that marks each state for which a reader scans a list, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the rulebook
|
|
63
|
+
**Per-task interface guidance:** When a task defines colour tokens, styles or writes interface text, or builds a page, a prototype, or a UI component, consult {rulebook:accessibility-conventions}, {rulebook:visual-design-conventions}, and {rulebook:ui-copy-conventions} while planning the task. Its key decisions state the contrast and size floors and the contrast check, the interaction states that each interactive element shows, the model, the placement, and the state attribute of each control that reveals a region or toggles a setting, the explanation of each action whose consequence is not evident from its label and the form that it takes, the cue that marks each state for which a reader scans a list, the spacing, alignment, mark, role, and identity rules, and the copy rules and the copy budget, so that the constraints are available to an implementer that cannot load the rulebooks. When the plan changes a visible component, its `## Verification` includes the browser check of each new or changed interactive element that the accessibility rulebook states and the browser check of each new or changed view that the visual-design rulebook states.
|
|
62
64
|
|
|
63
65
|
**Data-change guidance:** When the work changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions} while planning. Scope the plan to one step of the expand, migrate, contract sequence, and name that step in the key decisions of each task that touches the data. A task or verification check does not run a migration or another write against shared state before merge. When a verdict from an agent decides such a write, the acceptance criteria of the task that implements the verdict name the evidence and the script that checks it before the write. When the work adds or changes a skill that writes to shared state, `## Verification` runs the skill against the real data up to its approval checkpoint or as a dry run, and reviews each verdict that the run would act on.
|
|
64
66
|
|
|
@@ -1,9 +1,9 @@
|
|
|
1
|
-
1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `branch_name`, `default_branch`, `ticket_id`, `ticket_ref`, `ticket_url`, `scm`,
|
|
1
|
+
1. **Get context**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; extract `branch_name`, `default_branch`, `ticket_id`, `ticket_ref`, `ticket_url`, `scm`, and `ticket_dir` from it.
|
|
2
2
|
|
|
3
3
|
2. **Resolve the plan**: Stop at the first source that yields one:
|
|
4
4
|
- **Explicit `--plan=<path>`**: Read it.
|
|
5
5
|
- **Already in context**: This session produced or read the plan. Use it as-is; do not re-read the file.
|
|
6
|
-
- **Newest plan for the ticket**: The newest of `*_plan.md` and `*_plan-v*.md` under `{
|
|
6
|
+
- **Newest plan for the ticket**: The newest of `*_plan.md` and `*_plan-v*.md` under `{ticket_dir}/` (run subdirectories included), by the greatest `YYYYMMDD-HHMMSSZ` filename prefix. Both forms have that prefix, so they sort chronologically together and the lexicographically greatest is the newest across the two. Because `refine-plan` writes its revision as `_plan-v2.md` under a later prefix than the plan that it revises, matching both forms lets a refined plan take precedence over the original that it supersedes. Do not widen to `*_plan*.md`, which also matches the `_plan-review.md` artifact written beside the revision.
|
|
7
7
|
- **Ask**: The sources above do not resolve a plan. Ask the user for a path rather than working from the ticket alone: A caller who invoked this skill has a plan in mind.
|
|
8
8
|
|
|
9
9
|
Announce the resolved path and its timestamp before executing anything. Several plans can exist for one ticket, and the newest is not always the intended one: This announcement is how the user catches a superseded plan while the choice can still change without cost. It is not ceremony, and it is not skippable when the resolution was unambiguous.
|
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
**Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}
|
|
1
|
+
**Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. When two or more tickets keep work, print the list for them above the prompts, per [implementation-order list](#implementation-order-list), passing an `--edge` for each `--blocked-by` between pieces outside GitHub: The helper reads GitHub's native blockers, which `{skill:create-ticket}` recorded for the GitHub pieces, and not a Jira link. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}**`, followed by a fenced block that contains only the text to paste. The list states each ticket's readiness, so the heading does not repeat it:
|
|
2
2
|
|
|
3
3
|
- The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, omitting any argument that the rule omits, and omitting the plan when the ticket does not have one.
|
|
4
4
|
- The scope notes that the session needs and that the artifacts do not state, such as "only tasks 2 and 3" or "merge only after `live` contains #N".
|
|
@@ -1,3 +1,3 @@
|
|
|
1
|
-
**Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. For a piece that depends on an earlier piece being merged first, pass `--blocked-by` naming that piece's reference, which exists by then.
|
|
1
|
+
**Create the tickets.** Create the pieces in order with `{skill:create-ticket}`. With three or more pieces, pass `--parent` naming the originating ticket. On Jira, the children of an originating ticket at level 0, such as a `Task`, are created as its subtasks, as `{skill:create-ticket}` states for `--parent`: Each child then stays in the umbrella's project and sprint and cannot have children of its own. The originating ticket's type is not changed to an epic instead, because Jira handles a change across hierarchy levels as a move, which `acli` does not expose, and an epic cannot keep the originating ticket's existing epic as its parent. For a piece that depends on an earlier piece being merged first, pass `--blocked-by` naming that piece's reference, which exists by then.
|
|
2
2
|
|
|
3
3
|
**Rewrite the originating ticket.** Write the originating ticket's new body per the platform-specific write in [ticket source resolution](../_data/ticket-source-resolution.md#platform-specific-write).
|
|
@@ -1,3 +1,5 @@
|
|
|
1
|
+
<!-- include: merge-settled-criterion.md / -->
|
|
2
|
+
|
|
1
3
|
**Test criterion convention:** When writing a ticket that changes testable behavior, include a test criterion in its acceptance criteria that asks for coverage at the cheapest tier that observes the behavior, per the placement rules in the `testing-conventions` skill (e.g., "New/modified behavior in this change is covered by tests at the cheapest tier that observes it"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests that it would require are ones that fail that skill's bar for earning a place.
|
|
2
4
|
|
|
3
5
|
**Documentation criterion convention:** When writing a ticket that adds, removes, or renames user-facing surface (CLI flags, commands, API endpoints, configuration keys, environment variables), include in its acceptance criteria the corresponding updates to documentation, help text, and usage examples, including removal of references to anything that no longer exists.
|
|
@@ -51,7 +51,7 @@ What the skill does depends on whether a prior ticket exists, not on how the cal
|
|
|
51
51
|
|
|
52
52
|
**Alignment, when a prior ticket exists.** `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the ticket was written. Reproduce all three verbatim from the source ticket and revise `## Acceptance criteria` alone, because the criteria alone are the contract that an implementation can falsify. A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. A section missing from the source ticket stays omitted: Alignment revises the record and adds nothing to it. The saved artifact is still a complete ticket; only its revision is partial.
|
|
53
53
|
|
|
54
|
-
When the implementation diverges from what was proposed, report
|
|
54
|
+
When the implementation diverges from what was proposed, report the divergence in the pull-request description's `## Notes for reviewers` only when it changes what a reviewer checks, under the reader test that `summarize-change` states, and state it as the current fact rather than as a departure from the ticket; otherwise leave it out. Do not raise it as a ticket edit, and do not offer it as an option. A reviewer reads the diff to learn what the code does, so an implementation outgrowing its proposal is an ordinary finding rather than a defect in the ticket.
|
|
55
55
|
|
|
56
56
|
The source ticket is the one that the caller names. A review names it in its `## Specification compliance` section, which records the source against which the review measured, the remote issue or the local snapshot.
|
|
57
57
|
|
|
@@ -96,11 +96,11 @@ The skill writes two artifacts: the ticket of record on its platform, and a loca
|
|
|
96
96
|
|
|
97
97
|
### Path resolution
|
|
98
98
|
|
|
99
|
-
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; read `
|
|
99
|
+
Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash. The bundle emits the session-context manifest JSON to stdout; read `ticket_dir` from it (the same invocation in step 1 already populated the manifest file, so this is a fast-path read).
|
|
100
100
|
|
|
101
101
|
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
102
102
|
|
|
103
|
-
Ticket directory: `{
|
|
103
|
+
Ticket directory: `{ticket_dir}/`, or the directory that {skill:save-artifact} states when `ticket_dir` is null
|
|
104
104
|
|
|
105
105
|
Artifact type: `ticket`. Filename format:
|
|
106
106
|
|
|
@@ -99,4 +99,4 @@ Save the document with {skill:save-artifact} as a ticket-level `performance-find
|
|
|
99
99
|
|
|
100
100
|
### 7. Report
|
|
101
101
|
|
|
102
|
-
Once the developer approves the findings, give the artifact's path and one line of counts: pages measured, metrics failing by class, and improvements by effort.
|
|
102
|
+
Once the developer approves the findings, give the artifact's path and one line of counts: pages measured, metrics failing by class, and improvements by effort. When the ticket is on a [triage platform](../_data/spike-conventions.md#triage-platforms), name {skill:triage-spike-findings} as the next step, with the artifact's path as its input; otherwise, name the improvements left for disposal by hand. Improvements above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.
|
|
@@ -9,7 +9,7 @@ supported-harnesses: [claude]
|
|
|
9
9
|
|
|
10
10
|
Find the code and tests in one unit of a codebase that would be written differently if they were written afresh today, and propose one change for each. Each lens is a {subagent:code-health-assessor} that reads the unit without seeing any other lens's report. You run the sensors, write the brief that every lens reads, dispatch the lenses, check every proposal's evidence against the tree, and merge the proposals into one findings artifact.
|
|
11
11
|
|
|
12
|
-
The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. When the findings leave nothing to triage, its
|
|
12
|
+
The skill does not grade anything: The findings artifact is the input of `triage-spike-findings`, which grades each proposal, has a challenger argue against every grade, and decides what becomes a ticket. When the findings leave nothing to triage, or the ticket is not on a [triage platform](../_data/spike-conventions.md#triage-platforms), its remote writes are the [closing post](../_data/spike-conventions.md#closing-post) on the ticket and the ticket's close, both made on one consent from the developer; otherwise the triage round makes both.
|
|
13
13
|
|
|
14
14
|
## Inputs
|
|
15
15
|
|
|
@@ -100,7 +100,7 @@ As each lens returns:
|
|
|
100
100
|
Merge the passed proposals of every lens into one list, and write it to `{ticket_dir}/code-health/proposals.json`:
|
|
101
101
|
|
|
102
102
|
- **Merge** proposals that share a key: Keep the first source ID as the merged entry's `id`, which the schema limits to one, and list every source ID with the proposal in the findings document. Keep the union of paths and evidence, the strongest strength (`sensor`, then `rule`, then `reading`), the largest size, and the largest reach.
|
|
103
|
-
- **Tracked.** Run `check-tracked --proposals {ticket_dir}/code-health/proposals.json` with one `--prior` for each `*_dispositions.md` under `{
|
|
103
|
+
- **Tracked.** Run `check-tracked --proposals {ticket_dir}/code-health/proposals.json` with one `--prior` for each `*_dispositions.md` under `{project_artifact_dir}/tickets/`. Move every proposal that it lists under `tracked` out of the ranking, into a **Tracked** section with its source and reason. When `tracker.checked` is false, record its reason under residual unknowns.
|
|
104
104
|
- **Rank** the rest by reach, then by the best hotspot rank among the proposal's paths (a proposal without a ranked path sorts last), then by ID.
|
|
105
105
|
|
|
106
106
|
Write the findings document:
|
|
@@ -122,8 +122,8 @@ Save the document with {skill:save-artifact} as a ticket-level `code-health-find
|
|
|
122
122
|
|
|
123
123
|
Give the developer the findings artifact's path and one line of counts: proposals ranked, tracked, and dropped.
|
|
124
124
|
|
|
125
|
-
When the findings rank any proposal, name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states.
|
|
125
|
+
When the findings rank any proposal and the ticket is on a [triage platform](../_data/spike-conventions.md#triage-platforms), name `triage-spike-findings` as the next step, with the findings artifact's path as its input, and do not offer the closing post: The triage round ends the spike and offers it, as [Closing post](../_data/spike-conventions.md#closing-post) states.
|
|
126
126
|
|
|
127
|
-
Otherwise,
|
|
127
|
+
Otherwise, name the proposals left for disposal by hand when there are any, and offer to close the ticket with the closing post in the same response's action-items block. The post's contents, the consent, and the checks that a rerun relies on are stated in [Closing post](../_data/spike-conventions.md#closing-post). For an assessment, the answers that the post gives are the counts, and the post names the proposals that a prior disposition or an issue already tracks.
|
|
128
128
|
|
|
129
129
|
<!-- guidance-hook: implementation-preferences -->
|