codeassembly-guidance 0.1.0 → 0.3.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 +984 -0
- package/CHANGELOG.md +240 -0
- package/README.md +45 -99
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +21 -5
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +17 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +206 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
- package/content/guidance/rulebooks/commit-conventions.md +5 -4
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +39 -4
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +98 -98
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +64 -16
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +15 -4
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +22 -12
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +11 -11
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +7 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +98 -0
- package/content/skills/capture-event/SKILL.md +4 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +3 -3
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +28 -10
- package/content/skills/create-pr/SKILL.md +7 -6
- package/content/skills/create-ticket/SKILL.md +64 -23
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
- package/content/skills/design-and-plan/SKILL.md +17 -18
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +27 -23
- package/content/skills/index-prototypes/SKILL.md +86 -31
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +4 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +5 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
- package/content/skills/kb-retrieve-events/SKILL.md +20 -11
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
- package/content/skills/kb-update-events/SKILL.md +10 -7
- package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +2 -2
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +354 -3
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +3 -1
- package/content/skills/streamline-guidance/SKILL.md +11 -16
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +23 -14
- package/content/skills/testing-conventions/SKILL.md +81 -8
- package/content/skills/triage-feedback/SKILL.md +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +12 -12
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/feedback-triage-challenger.md +81 -0
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/lesson-clusterer.md +68 -0
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +21 -17
- package/schemas/preferences.v1.json +50 -7
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -34,7 +34,7 @@ Do NOT generate the implementation plan until the ticket has been approved. This
|
|
|
34
34
|
|
|
35
35
|
### Phase 1: Resolve task source and assess relevancy
|
|
36
36
|
|
|
37
|
-
1. **Resolve the task source** using the [ticket source resolution](../_data/ticket-source-resolution.md) table. Request the `updatedAt` field for use in the relevancy check. Store the resolved metadata for use in the relevancy check and Phase 5's optional remote update. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument.
|
|
37
|
+
1. **Resolve the task source** using the [ticket source resolution](../_data/ticket-source-resolution.md) table. Request the `updatedAt` field for use in the relevancy check. Store the resolved metadata for use in the relevancy check and Phase 5's optional remote update. When the source resolves to a URL, persist it to the branch manifest per [Stored ticket URL](../_data/ticket-source-resolution.md#stored-ticket-url) so that a later session does not need a ticket argument. Then report the ticket's open blockers per [Open blockers](../_data/ticket-source-resolution.md#open-blockers), whether or not the relevancy check runs, and continue: A blocker does not stop design. Then check the branch per [branch currency](../_data/branch-currency.md) before exploring the codebase, reading `branch_name` and `default_branch` from the manifest that `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits, and passing the paths that the ticket names.
|
|
38
38
|
|
|
39
39
|
2. **Assess relevancy**: Determine whether the ticket may be stale and, if so, verify it is still relevant.
|
|
40
40
|
|
|
@@ -64,11 +64,11 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
64
64
|
|
|
65
65
|
### Phase 2: Understand the task
|
|
66
66
|
|
|
67
|
-
1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase.
|
|
67
|
+
1. **Explore project context:** Check relevant files, docs, recent commits to understand the affected area of the codebase. Read the project's declared stage from the manifest's `project_maturity`, `project_sensitivity`, and `project_audience` fields, which `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` emits.
|
|
68
68
|
|
|
69
69
|
2. **Evaluate the ticket on its merits**: Apply the criteria in [ticket evaluation](../_data/ticket-evaluation.md). When evaluation reveals a divergence from the ticket as written, recommend a disposition, build the design on it, and present the divergence at the ticket checkpoint; raise it earlier only when the design cannot proceed without the answer. Divergence includes scope that should grow: By default, fold work that the problem requires into this change rather than into a follow-up (see [scope-and-deferral](../_data/scope-and-deferral.md)).
|
|
70
70
|
|
|
71
|
-
3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate
|
|
71
|
+
3. **Form the questions that the design turns on, and decide what the gate lets you decide.** The questions cover purpose and motivation, constraints and scope boundaries, and success criteria and edge cases. Answer each from the codebase, the ticket, and the [option format](#option-format) gate when you can, and record the answer as a decision taken, with its reason. Defer the asks that survive the gate to the ticket checkpoint in Phase 3; ask earlier only when the design cannot proceed without the answer, and prefer multiple choice when you do. Treat the declared stage as the premise of every security, availability, and infrastructure question, per [project stage](../_data/project-stage.md). Treat a step that a person must run on each machine as a defect of the design, per [who applies the change](../_data/design-priorities.md#who-applies-the-change): Prefer a design that the agent applies and verifies itself, and when the step stays, the ticket's `## Proposed solution` names the rung of that ladder that shapes it. Ask for each undeclared stage value: in this step when the design has such a question, since the answer decides it, and otherwise at the ticket checkpoint. The ticket's `## Context` states each premise that decided such a question, and the plan includes a task that declares each answered value.
|
|
72
72
|
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
73
73
|
|
|
74
74
|
**Important:** Do not use `{tool:AskUserQuestion}` or any interactive selector (pop-up, arrow-key, structured-choice) for multiple-choice questions. Ask the question as plain text in the message body, with options as a numbered list.
|
|
@@ -77,14 +77,14 @@ Invoke the `{skill:assess-ticket}` skill with the resolved ticket source and mod
|
|
|
77
77
|
|
|
78
78
|
### Phase 3: Converge on a design and refine the ticket
|
|
79
79
|
|
|
80
|
-
1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
|
|
80
|
+
1. **Choose the approach.** When the solution is obvious, build on it; don't manufacture alternatives for the sake of it. When it is not obvious, weigh 2-3 approaches, ranked per [design priorities](../_data/design-priorities.md), in which a design that needs a person to act on each machine ranks below one that the agent applies itself, and apply the gate: A fork whose two strongest options are both ■■□ is presented at the checkpoint below with its trade-offs; otherwise the draft records the choice as "X, not Y" with its reason.
|
|
81
81
|
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
82
82
|
|
|
83
83
|
2. **Draft the ticket on the recommended approach, provisionally.** The design is the draft ticket: Its `## Proposed solution` states the design, scaled to complexity, and a fork that survived the gate is written on its recommended branch until the checkpoint settles it.
|
|
84
84
|
|
|
85
85
|
**Spike mode.** If this is a spike, use the spike ticket template in [spike conventions](../_data/spike-conventions.md) in place of the skeleton below; everything else in this phase is unchanged.
|
|
86
86
|
|
|
87
|
-
If the source ticket already covers problem, context, proposed solution, and acceptance criteria adequately and the design did not
|
|
87
|
+
If the source ticket already covers problem, context, proposed solution, and acceptance criteria adequately and the design did not reveal any changes, propose adopting it as-is at the checkpoint. Skip the rewrite. Only add or revise sections for which the design revealed gaps or shifts in understanding.
|
|
88
88
|
|
|
89
89
|
When the ticket needs work, produce or update it to state the proposed approach:
|
|
90
90
|
|
|
@@ -94,20 +94,18 @@ When the ticket needs work, produce or update it to state the proposed approach:
|
|
|
94
94
|
<!-- include: ../_partials/ticket-skeleton.md / -->
|
|
95
95
|
```
|
|
96
96
|
|
|
97
|
-
<!-- include: ../_partials/ticket-
|
|
98
|
-
|
|
99
|
-
<!-- include: ../_partials/ticket-concision.md / -->
|
|
100
|
-
|
|
101
|
-
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
102
|
-
|
|
103
|
-
<!-- include: ../_partials/ticket-placement.md / -->
|
|
97
|
+
<!-- include: ../_partials/ticket-composition.md / -->
|
|
104
98
|
|
|
105
99
|
Here, _the implementation_ is the plan artifact (Phase 4): Mechanism that the ticket omits is recorded there, not dropped.
|
|
106
100
|
|
|
107
101
|
<!-- include: ../_partials/ticket-criteria-conventions.md / -->
|
|
108
102
|
|
|
103
|
+
<!-- include: ../../_partials/prose-line-breaks.md / -->
|
|
104
|
+
|
|
109
105
|
**Present the ticket as the first checkpoint**, in one turn: the draft ticket, the decisions taken so far with their reasons, and the forks that survived the gate as option-style questions. Revise until approved. Approval of the ticket is approval of the design.
|
|
110
106
|
|
|
107
|
+
**When the checkpoint splits the ticket**, the session continues with one piece: With two pieces, it plans the originating ticket, which keeps the first piece; with an umbrella, it plans the first child, whose work belongs in that child's own worktree. Phase 5 then ends with the launch prompts that [Splitting the ticket](#splitting-the-ticket) defines, with each ticket's entry point chosen by that section's **Report.** rule, and the planned piece's prompt names its saved plan. With two pieces, the next-steps menu stays for the originating ticket, and that ticket's prompt heading adds that this session continues with it at the menu. With an umbrella, the launch prompts replace the `Next action` menu, so that nothing offers to implement a child in the current worktree.
|
|
108
|
+
|
|
111
109
|
### Phase 4: Generate implementation plan
|
|
112
110
|
|
|
113
111
|
<HARD-GATE>
|
|
@@ -134,12 +132,13 @@ Then save both artifacts:
|
|
|
134
132
|
- Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout (auto-generate ticket ID as `{YYYYMMDD}-{4 random hex}` if none found)
|
|
135
133
|
- Target: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
136
134
|
- `mkdir -p` the target directory
|
|
135
|
+
- After an umbrella split, save the plan in the planned child's directory instead, `tickets/{child_id}/`, beside the ticket artifact that `{skill:create-ticket}` saved there
|
|
137
136
|
|
|
138
137
|
2. Resolve frontmatter fields for both artifacts. The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
|
|
139
138
|
|
|
140
|
-
Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill design-and-plan --interactive true` via Bash. Prepend the output verbatim to each artifact body.
|
|
139
|
+
Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill design-and-plan --interactive true` via Bash. Prepend the output verbatim to each artifact body. For a plan saved in a child's directory, append `--override ticket_id="{child_id}" --override ticket_ref="{child_ref}"` to the plan's invocation, so that its frontmatter names the child rather than the current branch's ticket.
|
|
141
140
|
|
|
142
|
-
Append `--extra copies_remote=true` to the ticket artifact's invocation, and to that one alone, when the source was a remote ticket and the refined ticket does not differ from its body: the same condition under which the remote-issue offer below is not made. This records that the saved body is a copy of the ticket of record; see [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). When the offer is made, omit it on both outcomes: On consent, the remote is written after the artifact is saved, so
|
|
141
|
+
Append `--extra copies_remote=true` to the ticket artifact's invocation, and to that one alone, when the source was a remote ticket and the refined ticket does not differ from its body: the same condition under which the remote-issue offer below is not made. This records that the saved body is a copy of the ticket of record; see [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). When the offer is made, omit it on both outcomes: On consent, the remote is written after the artifact is saved, so the remote is already the more recent copy, and a refusal leaves the snapshot genuinely newer.
|
|
143
142
|
|
|
144
143
|
3. Save both artifacts following `save-artifact` naming conventions:
|
|
145
144
|
- Ticket: `{YYYYMMDD-HHMMSSZ}_{slug}_ticket.md`
|
|
@@ -147,7 +146,7 @@ Then save both artifacts:
|
|
|
147
146
|
|
|
148
147
|
Prepend the resolved frontmatter to each artifact content before writing.
|
|
149
148
|
|
|
150
|
-
4. Report paths and present next steps.
|
|
149
|
+
4. Report paths and present next steps. After a split at the ticket checkpoint, end with the launch prompts, per the checkpoint-split rule in Phase 3.
|
|
151
150
|
|
|
152
151
|
```
|
|
153
152
|
Design and plan complete:
|
|
@@ -168,14 +167,14 @@ Next steps:
|
|
|
168
167
|
|
|
169
168
|
**A2: Next action**
|
|
170
169
|
1. 🧠 ■□□ Refine plan:
|
|
171
|
-
- Clear context
|
|
170
|
+
- Clear context, then {skill?:refine-plan} with plan: {plan_path}, ticket: {ticket_path}
|
|
172
171
|
...
|
|
173
172
|
```
|
|
174
173
|
|
|
175
174
|
On consent, write the refined ticket per [platform-specific write](../_data/ticket-source-resolution.md#platform-specific-write). The refined ticket is the whole body approved by the user, so it replaces the remote body outright.
|
|
176
175
|
|
|
177
176
|
<HARD-GATE>
|
|
178
|
-
Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The `**A1: Remote issue**` and `**A2: Next action**` sub-block labels above are the sanctioned wrapper when the remote offer is shown; they do not add or reorder any option. The plan was developed interactively, with the ticket and the plan each approved at a checkpoint; use this as recommendation context. Include both `{ticket_path}` and `{plan_path}` in each skill-invoking option line.
|
|
177
|
+
Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The `**A1: Remote issue**` and `**A2: Next action**` sub-block labels above are the sanctioned wrapper when the remote offer is shown; they do not add or reorder any option. After an umbrella split at the ticket checkpoint, the launch prompts take the place of the `Next action` menu, per the checkpoint-split rule in Phase 3. The plan was developed interactively, with the ticket and the plan each approved at a checkpoint; use this as recommendation context. Include both `{ticket_path}` and `{plan_path}` in each skill-invoking option line.
|
|
179
178
|
</HARD-GATE>
|
|
180
179
|
|
|
181
180
|
**STOP.** Beyond the remote-issue update above, do not invoke any skill. Do not begin implementation.
|
|
@@ -187,7 +186,7 @@ Follow the options, output format, and recommendation rules in [next-steps optio
|
|
|
187
186
|
- **YAGNI ruthlessly**: Cut unnecessary scope from designs
|
|
188
187
|
- **Scale to complexity**: A simple task gets a short design and a short plan
|
|
189
188
|
- **Plan for engineers, not transcribers**: Communicate decisions, not ceremony
|
|
190
|
-
- **The ticket is the contract**: If facts
|
|
189
|
+
- **The ticket is the contract**: If the facts found during implementation differ from the plan, the ticket's acceptance criteria are the source of truth
|
|
191
190
|
|
|
192
191
|
<!-- include: ../_partials/next-steps-after-plan.md / -->
|
|
193
192
|
|
|
@@ -6,7 +6,7 @@ user-invocable: true
|
|
|
6
6
|
|
|
7
7
|
# Groom backlog
|
|
8
8
|
|
|
9
|
-
Sweep a repository's open GitHub issues for tickets whose motivation other work has met, whose premise the codebase has outgrown, or whose
|
|
9
|
+
Sweep a repository's open GitHub issues for tickets whose motivation other work has met, whose premise the codebase has outgrown, or whose outcome depends on another ticket. A bundled helper does the mechanical half: It fetches and selects the tickets, detects which are in progress, finds candidate cross-references, keeps the ledger, classifies each assessment under the policy, proposes an action for each escalation, and renders the digests, the drafted edits, and the comments. You do the rest: one `{subagent:ticket-assessor}` subagent per ticket, one confirmation per digest page, and every write to GitHub.
|
|
10
10
|
|
|
11
11
|
The sweep decides by default. Every selected ticket is assessed, and each digest page asks one question: whether to apply the actions that it proposes.
|
|
12
12
|
|
|
@@ -64,7 +64,7 @@ The helper applies the umbrella case in `ingest` and in `comment`.
|
|
|
64
64
|
| A `keep` | `keep` |
|
|
65
65
|
| Anything else, including a close below high confidence | `leave` |
|
|
66
66
|
|
|
67
|
-
`leave` writes nothing; the entry still shows the recommendation, so that the user can name it. The assessor drafts the edit behind every `update`, `revise`, and `split`: the replacement sections of the body and, for a split, the child tickets. The digest shows each draft under its entry.
|
|
67
|
+
`leave` writes nothing; the entry still shows the recommendation, so that the user can name it. The assessor drafts the edit behind every `update`, `revise`, and `split`: the replacement sections of the body, a replacement title when the current one no longer describes the ticket, and, for a split, the child tickets. The digest shows each draft under its entry.
|
|
68
68
|
|
|
69
69
|
**What the digest groups.** A hub is an open ticket on whose outcome two or more escalations of one digest page depend; the page shows it once, above its dependents, so that the user decides it first. Overlapping open tickets are merged into one group with the assessors' recommended survivor. Merging tickets stays the user's action, through the ticket skills.
|
|
70
70
|
|
|
@@ -74,7 +74,7 @@ The helper applies the umbrella case in `ingest` and in `comment`.
|
|
|
74
74
|
|
|
75
75
|
## Process
|
|
76
76
|
|
|
77
|
-
Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`, except
|
|
77
|
+
Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`, except when a step below says otherwise. Invoke the helper as:
|
|
78
78
|
|
|
79
79
|
```bash
|
|
80
80
|
node {harness_home_dir}/skills/groom-backlog/groom-backlog.mjs {command} --run {run} {flags}
|
|
@@ -159,7 +159,7 @@ Run `digest` once, and walk the pages of that one result: A `leave` stays undeci
|
|
|
159
159
|
|
|
160
160
|
The result contains the run's open escalations, `total`, and `pages`: each escalation whose latest assessment escalated and that does not have a decision recorded after it. Each page's `entries` give each entry's `proposed` action, a `decision` with an optional `supersededBy`. Present one page at a time, verbatim from its `markdown`, and close the turn with an action-items block that asks one question: whether to apply the page's proposed actions. The user answers `yes` to apply them all, or names the entries to change, in the decision vocabulary (`keep`, `update`, `revise`, `split`, `close-complete`, `close-superseded` optionally by `#N`, `close-not-planned`, or `leave`), with an optional reason: `yes, except 3 keep, 5 close-superseded by #40`. Naming a `leave` entry applies what it names. A `no` without changes applies nothing on the page.
|
|
161
161
|
|
|
162
|
-
Under `--dry-run`, present every page, take
|
|
162
|
+
Under `--dry-run`, present every page, do not take any decisions, and go to the summary.
|
|
163
163
|
|
|
164
164
|
### 7. Apply the confirmed actions and summarize
|
|
165
165
|
|
|
@@ -196,7 +196,7 @@ Every action on a ticket follows one order: apply the drafted edit when the deci
|
|
|
196
196
|
gh issue edit {child number} --parent {number}
|
|
197
197
|
```
|
|
198
198
|
|
|
199
|
-
Then replace the ticket's body
|
|
199
|
+
Then replace the ticket's body, adding `--title "{title}"` when the result's `title` is not `null`:
|
|
200
200
|
|
|
201
201
|
```bash
|
|
202
202
|
body_path="{body path}"
|
|
@@ -204,6 +204,8 @@ Every action on a ticket follows one order: apply the drafted edit when the deci
|
|
|
204
204
|
gh issue edit {number} --body-file "$body_path"
|
|
205
205
|
```
|
|
206
206
|
|
|
207
|
+
Edit a ticket only through this step: A title or label edited after the decision is recorded makes the ticket look changed, and the next `collect` selects it again.
|
|
208
|
+
|
|
207
209
|
2. **Render the comment** to a file:
|
|
208
210
|
|
|
209
211
|
```bash
|
|
@@ -214,7 +216,7 @@ Every action on a ticket follows one order: apply the drafted edit when the deci
|
|
|
214
216
|
|
|
215
217
|
Pass `--reason` when the user stated one, `--superseded-by` when the decision names the superseding ticket, and `--children` with the created children's numbers for a split. `--decision` is one of `keep`, `close-complete`, `close-superseded`, `close-not-planned`, `update`, `revise`, and `split`.
|
|
216
218
|
|
|
217
|
-
The result's `post` states whether the comment is posted. When it is `false`, the helper
|
|
219
|
+
The result's `post` states whether the comment is posted. When it is `false`, the helper does not write a body: Skip to step 5.
|
|
218
220
|
|
|
219
221
|
3. **Post it**, per [gh body file](#gh-body-file):
|
|
220
222
|
|