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,18 @@
|
|
|
1
|
+
**Write the tightened ticket, not a draft to be tightened later.** A ticket is the minimal contract that a reader needs, not a transcript of the design session. Compose the maximally tight version that still keeps the full meaning; length comes from content, not from a completeness instinct. (Producing the tight version up front spares the reader, and spares everyone the tighten-on-request round trip.)
|
|
2
|
+
|
|
3
|
+
State conclusions, not the journey to them. Naming a chosen approach (including "X, not Y") is a durable decision and belongs in the ticket. The _story_ of how the decision was reached does not: Drop the design back-and-forth, the false starts, restated context, and motivating episodes.
|
|
4
|
+
|
|
5
|
+
**Self-check before presenting.** For each sentence, ask: Would removing it change what the reader does or how the work gets executed? If not, cut it. State each acceptance criterion once, and do not restate it in surrounding prose.
|
|
6
|
+
|
|
7
|
+
Add a design-narrative section (rationale, alternatives explored) only when the user explicitly asks for it.
|
|
8
|
+
|
|
9
|
+
**Before** (the design journey is left in):
|
|
10
|
+
|
|
11
|
+
> We first considered extending the existing `FooAdapter`, but a spike showed it couples the cache to the transport, so after some back-and-forth we landed on a separate `CacheLayer`. The team has struggled with cache invalidation before, and this should finally fix that. Acceptance: A new `CacheLayer` module exists. It must be covered by tests so we know it works.
|
|
12
|
+
|
|
13
|
+
**After** (conclusion only, full meaning intact):
|
|
14
|
+
|
|
15
|
+
> Add a `CacheLayer` separate from the transport (not an extension of `FooAdapter`, which would couple cache to transport).
|
|
16
|
+
>
|
|
17
|
+
> - [ ] `CacheLayer` is independent of the transport.
|
|
18
|
+
> - [ ] New behavior is covered by tests.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
**Test criterion convention:** When writing a ticket that changes testable behavior, include a test criterion in its acceptance criteria (e.g., "New/modified behavior in this change is covered by tests"). Omit it when the change falls entirely within the carve-outs defined in the `testing-conventions` skill, or when the only tests it would compel are ones that fail that skill's bar for earning a place.
|
|
2
|
+
|
|
3
|
+
**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.
|
|
4
|
+
|
|
5
|
+
**Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must land before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
|
|
6
|
+
|
|
7
|
+
**Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever lands first, the deploy or the migration.
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
**Place ticket content by kind, not by volume.** A ticket states the change's _subject_ and the _outcomes_ that it must produce; the _mechanism_ that achieves them belongs with the implementation, not the ticket. This is a separate axis from concision: A perfectly short ticket can still contain the wrong _kind_ of content.
|
|
2
|
+
|
|
3
|
+
- **Ticket**: The change's **subject** (the defect being fixed, the current structure being changed, the target contract or behavior that it exposes) and **key** non-obvious details that save the implementer real derivation (e.g. "reuse the sibling table's `getSortValue`").
|
|
4
|
+
- **Implementation**: The **mechanism**, meaning internal wiring, files as a diff-list, step sequences, deletion lists, and the internal props/config of a dependency consumed by the change.
|
|
5
|
+
|
|
6
|
+
The line is subject vs. mechanism, not code vs. prose: A code name is fine when it _is_ the subject. **Bug and refactoring tickets** name existing code because that code is the subject. Keep it; the fix procedure still belongs with the implementation.
|
|
7
|
+
|
|
8
|
+
**Before** (a feature ticket transcribing a reference implementation's API surface):
|
|
9
|
+
|
|
10
|
+
> Set `columnDefs`, pass `getSortedRowModel`, and wire `state.sorting`; pin the first column via `columnPinning.left: ['name']`; mock `@acme/table` in `__mocks__/@acme/table/compiled.tsx`.
|
|
11
|
+
|
|
12
|
+
**After** (the same change stated as the contract that it must honor):
|
|
13
|
+
|
|
14
|
+
> Every column sorts client-side, and the first column stays pinned during horizontal scroll. (Which props wire this up is implementation.)
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
Start from this skeleton. Add a section only when it adds signal on which the reader must act.
|
|
2
|
+
|
|
3
|
+
- **Problem** and **Acceptance criteria (Must have)**: Always present.
|
|
4
|
+
- **Context**, **Proposed solution** (including "X, not Y"), and **Should have / Nice to have**: Opt-in, added only when the reader needs them. Omit empty tiers.
|
|
5
|
+
|
|
6
|
+
This applies the [concision principle](../_data/concision.md) to tickets.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
## Problem
|
|
2
|
+
|
|
3
|
+
{Clear statement of what needs to be solved and why}
|
|
4
|
+
|
|
5
|
+
## Context
|
|
6
|
+
|
|
7
|
+
{Relevant background, constraints, prior art, related systems}
|
|
8
|
+
|
|
9
|
+
## Proposed solution
|
|
10
|
+
|
|
11
|
+
{The shape of the proposed approach: components or boundaries involved, how it fits into the existing system, and the chosen approach, including "X, not Y" when a rejected option is worth recording. Keep this section outcome-shaped per the placement doctrine below.}
|
|
12
|
+
|
|
13
|
+
<!-- include: acceptance-criteria-scaffold.md / -->
|
|
@@ -0,0 +1,136 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: add-change-record
|
|
3
|
+
description: Add a change-record block to a pull request whose body contains none
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Add change record
|
|
8
|
+
|
|
9
|
+
Append a `change-record` block to a pull request whose body has none, so that the merge publishes the change entries.
|
|
10
|
+
|
|
11
|
+
The block is drafted by `{skill:summarize-change}`, which consolidates the branch, draws the entries, audits them, and renders the block. This skill lifts the rendered block from the summary that the run saved and appends it to the pull-request body; it drafts nothing of its own.
|
|
12
|
+
|
|
13
|
+
**A block that is already written is never replaced.** A readable block, a malformed one, and one that does not record an entry are all left for the author to repair by hand, as [the change record](../_data/change-record.md#where-the-record-is-read) states. This skill adds a block only where there is none.
|
|
14
|
+
|
|
15
|
+
## Arguments
|
|
16
|
+
|
|
17
|
+
| Flag | Effect | Default |
|
|
18
|
+
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------- |
|
|
19
|
+
| `--pr {n}` | Add the block to PR `{n}` instead of the PR for the current branch. | PR for the current branch |
|
|
20
|
+
| `--scope {scope}` | Passed to `{skill:summarize-change}`, which records it as an override on the consolidated record. | none |
|
|
21
|
+
| `--type {type}` | Passed to `{skill:summarize-change}`. A `!` on it (`feat!`) adds the breaking mark, as that skill's own argument does. | none |
|
|
22
|
+
|
|
23
|
+
## Process
|
|
24
|
+
|
|
25
|
+
### 1. Get session context
|
|
26
|
+
|
|
27
|
+
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`, `scm`, and `pr_url` from it.
|
|
28
|
+
|
|
29
|
+
### 2. Resolve the pull request
|
|
30
|
+
|
|
31
|
+
Resolve it per [PR source resolution](../_data/pr-source-resolution.md#runtime-resolution-path-add-change-record-review-pr-merge-pr): An explicit `--pr {n}` overrides; otherwise a stored `pr_url` from session context is the default; otherwise discover the pull request for the current branch. Persist the resolved URL via `--set-pr-url`, and invalidate (`--clear-pr-url`) and re-resolve a stored URL that does not yield the expected pull request.
|
|
32
|
+
|
|
33
|
+
Read the pull request's metadata, dispatching on `scm`:
|
|
34
|
+
|
|
35
|
+
- **`"github"`**:
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
gh pr view {pr} --json number,title,body,headRefName,headRefOid,url
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
- **`"bitbucket"`**: Issue an `action: "get"` call per [Bitbucket pull-request access](../_data/bitbucket-pr-access.md), then map its fields onto the same names: `description` to `body`, `source.branch.name` to `headRefName`, `source.commit.hash` to `headRefOid`, and `links.html.href` to `url`.
|
|
42
|
+
- **Unknown or missing**: Ask the user which platform to use.
|
|
43
|
+
|
|
44
|
+
If the pull request cannot be resolved, stop with: "No open pull request found for branch `{branch_name}`. Create one with `{skill?:create-pr}` first."
|
|
45
|
+
|
|
46
|
+
### 3. Confirm that HEAD is the pull request's head commit
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
git rev-parse HEAD
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
The next step runs `{skill:summarize-change}`, which reads `{default_branch}...HEAD` and records HEAD as the block's `entries_commit`. A block drafted anywhere else describes commits that the pull request does not contain, and `resolve-merge` would read it as stale at merge.
|
|
53
|
+
|
|
54
|
+
Compare the local SHA with `headRefOid`. On GitHub the two are full SHAs and must be equal; on Bitbucket, compare on a prefix per [Bitbucket pull-request access](../_data/bitbucket-pr-access.md#reading-a-pull-request), since the platform may abbreviate its hash.
|
|
55
|
+
|
|
56
|
+
When they differ, stop, naming both commits and the branch to check out.
|
|
57
|
+
|
|
58
|
+
### 4. Confirm that the body does not contain a block
|
|
59
|
+
|
|
60
|
+
Write the pull-request body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-pr{number}-{timestamp}.md`. On GitHub, write it from the platform, so that the file contains the body byte for byte:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
gh pr view {pr} --json body --jq '.body' > "{body_file}"
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
On Bitbucket, write the `description` from step 2 to the file verbatim.
|
|
67
|
+
|
|
68
|
+
Then resolve the merge over it, opening with the assignment and the guard:
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
body_path="{absolute path from the write step}"
|
|
72
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
73
|
+
node {harness_home_dir}/scripts/describe-change.mjs resolve-merge \
|
|
74
|
+
--base "{default_branch}" \
|
|
75
|
+
--head "{headRefOid}" \
|
|
76
|
+
--pr-number "{number}" \
|
|
77
|
+
--pr-title "{title}" \
|
|
78
|
+
--pr-body-file "$body_path"
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The guard keeps a failed read out of the decision: An empty file does not contain a block, and this skill would append one to a body that it never read.
|
|
82
|
+
|
|
83
|
+
Read `notices` from the output. The block reading is settled by the helper rather than by a fence scan here, so that this skill and the merge agree on what counts as a block, malformed included.
|
|
84
|
+
|
|
85
|
+
Continue only when `notices` contains `absent-block`. Otherwise stop with the reason that the notices give:
|
|
86
|
+
|
|
87
|
+
- **`malformed-block`**: The body's block cannot be read (its `defect`). Say that a written block is never replaced, and that the author repairs this one by hand.
|
|
88
|
+
- **Neither notice**: The body already contains a readable block. Say so, and that a block without entries is left as it is.
|
|
89
|
+
|
|
90
|
+
A guard refusal or a non-zero exit stops the skill the same way, with the helper's own message and the outcome `stopped: block not resolved`.
|
|
91
|
+
|
|
92
|
+
### 5. Draft the block
|
|
93
|
+
|
|
94
|
+
Invoke `{skill:summarize-change}`, passing through `--scope` and `--type` as given. That skill saves a change summary whose body ends with the rendered `change-record` block.
|
|
95
|
+
|
|
96
|
+
Take the last `change-record` fence from the summary that this session just saved, copied character for character, the fence lines included. Read it from the saved file rather than from the transcript.
|
|
97
|
+
|
|
98
|
+
When the saved summary does not contain a fence, stop, relaying what `{skill:summarize-change}` reported about `render-block`. Nothing is written to the pull request.
|
|
99
|
+
|
|
100
|
+
### 6. Show the block and ask
|
|
101
|
+
|
|
102
|
+
Show the block as it will be appended, then ask:
|
|
103
|
+
|
|
104
|
+
```
|
|
105
|
+
Append this change record to PR #{number}? 👍🏼👎🏼
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
The ask comes after the block is shown, because the write changes state that others read. If the user declines, stop with nothing written.
|
|
109
|
+
|
|
110
|
+
### 7. Write the body back
|
|
111
|
+
|
|
112
|
+
Append the block after the body read in step 4, separated by one blank line, and write the whole body to a scratch file per [gh body file](#gh-body-file). The block is appended rather than inserted above a `Closes` line: A hand-written body places that line anywhere, and the block's being the body's last element is the only rule that a reader enforces.
|
|
113
|
+
|
|
114
|
+
- **`"github"`**:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
body_path="{absolute path from the write step}"
|
|
118
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
119
|
+
gh pr edit {number} --body-file "$body_path"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
- **`"bitbucket"`**: Write through the description-update action that [Bitbucket pull-request access](../_data/bitbucket-pr-access.md) documents, if it documents one. That doc is the single statement of the tool's actions, and today it documents reading, finding, and merging alone. When it does not document that action, stop, showing the block again and saying that the author pastes it as the description's last element in the Bitbucket UI.
|
|
123
|
+
|
|
124
|
+
### 8. Confirm the block is the body's last element
|
|
125
|
+
|
|
126
|
+
Re-read the body from the platform as step 4 does, write it to a fresh scratch file, and run `resolve-merge` over it again with the same flags. The block is in place when `notices` no longer contains `absent-block` and `malformed-block` does not appear.
|
|
127
|
+
|
|
128
|
+
When either check fails, say what the helper reported and that the pull request's body is the one to inspect. Do not write again.
|
|
129
|
+
|
|
130
|
+
### 9. Report
|
|
131
|
+
|
|
132
|
+
Report the pull-request URL and the path of the change summary that step 5 saved, which is a byproduct of the run rather than a second artifact to compose.
|
|
133
|
+
|
|
134
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|
|
135
|
+
|
|
136
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: add-test-ids
|
|
3
|
+
description: Add data-test-id attributes to new and modified React components
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Add test IDs
|
|
8
|
+
|
|
9
|
+
Add `data-test-id` attributes to components in files that you're working on.
|
|
10
|
+
|
|
11
|
+
## Rules
|
|
12
|
+
|
|
13
|
+
- Add to all components declared in current task scope
|
|
14
|
+
- Do not change existing `data-test-id` values
|
|
15
|
+
- Do not add to components that don't support the attribute
|
|
16
|
+
|
|
17
|
+
## Format
|
|
18
|
+
|
|
19
|
+
Convert component name to kebab-case:
|
|
20
|
+
|
|
21
|
+
- `HelpPanel` → `data-test-id="help-panel"`
|
|
22
|
+
- `UserProfileCard` → `data-test-id="user-profile-card"`
|
|
23
|
+
- `NavigationMenu` → `data-test-id="navigation-menu"`
|
|
24
|
+
|
|
25
|
+
## Example
|
|
26
|
+
|
|
27
|
+
```tsx
|
|
28
|
+
// Before
|
|
29
|
+
export const HelpPanel: FC<Props> = ({ title, children }) => {
|
|
30
|
+
return (
|
|
31
|
+
<div className="help-panel">
|
|
32
|
+
<h2>{title}</h2>
|
|
33
|
+
{children}
|
|
34
|
+
</div>
|
|
35
|
+
);
|
|
36
|
+
};
|
|
37
|
+
|
|
38
|
+
// After
|
|
39
|
+
export const HelpPanel: FC<Props> = ({ title, children }) => {
|
|
40
|
+
return (
|
|
41
|
+
<div className="help-panel" data-test-id="help-panel">
|
|
42
|
+
<h2>{title}</h2>
|
|
43
|
+
{children}
|
|
44
|
+
</div>
|
|
45
|
+
);
|
|
46
|
+
};
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
## Placement
|
|
50
|
+
|
|
51
|
+
Add `data-test-id` to the root element of the component.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: align-ticket-with-implementation
|
|
3
|
+
description: Align an issue ticket with the current branch's implementation
|
|
4
|
+
user-invocable: true
|
|
5
|
+
dependencies:
|
|
6
|
+
skills:
|
|
7
|
+
- testing-conventions
|
|
8
|
+
---
|
|
9
|
+
|
|
10
|
+
# Align ticket with implementation
|
|
11
|
+
|
|
12
|
+
Produce or revise an issue ticket (e.g., GitHub issue, Jira issue) to describe what the current branch's implementation accomplishes.
|
|
13
|
+
|
|
14
|
+
## Arguments
|
|
15
|
+
|
|
16
|
+
| Flag | Effect | Default |
|
|
17
|
+
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
|
|
18
|
+
| `--write-target=remote\|local` | Which artifact alignment writes, per [Write targets](#write-targets). `local` saves the local ticket artifact alone and leaves the ticket of record as it stands, for a ticket that the user cannot or must not edit; `remote` requires a ticket of record to resolve and stops when none does. | The ticket of record when one resolves, else the local artifact alone |
|
|
19
|
+
|
|
20
|
+
## Process
|
|
21
|
+
|
|
22
|
+
1. **Resolve the source ticket**: Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `default_branch`, `ticket_url`, and `ticket_id` from the manifest JSON that it emits on stdout. Resolve the ticket named by the caller, or failing that the manifest's, per [ticket source resolution](../_data/ticket-source-resolution.md). Whether a source ticket resolves selects the branch in [Two branches](#two-branches). If resolution is ambiguous or fails, take the alignment branch and ask: A lookup that fell through must not be read as licence to author a proposal over one that already exists.
|
|
23
|
+
|
|
24
|
+
2. **Analyze branch changes**:
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
git diff {default_branch}...HEAD
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
3. **Write the ticket** on the branch selected by step 1, describing issues that were addressed, then write it to the targets named in [Saving](#saving)
|
|
31
|
+
|
|
32
|
+
## Output structure
|
|
33
|
+
|
|
34
|
+
The artifact begins with YAML frontmatter conforming to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema. See [Frontmatter resolution](#frontmatter-resolution) below for field resolution. The frontmatter conforms to the canonical schema; see the canonical example in [artifact-conventions.md](../_data/artifact-conventions.md#universal-artifact-frontmatter).
|
|
35
|
+
|
|
36
|
+
```markdown
|
|
37
|
+
<!-- include: ../_partials/ticket-skeleton.md / -->
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
<!-- include: ../_partials/ticket-skeleton-tiers.md / -->
|
|
41
|
+
|
|
42
|
+
## Guidance
|
|
43
|
+
|
|
44
|
+
<!-- include: ../_partials/ticket-concision.md / -->
|
|
45
|
+
|
|
46
|
+
<!-- include: ../_partials/ticket-placement.md / -->
|
|
47
|
+
|
|
48
|
+
When aligning to an existing implementation, _the implementation_ is the code on the branch; describe what the code now does, and resist transcribing its mechanism back into the ticket.
|
|
49
|
+
|
|
50
|
+
### Two branches
|
|
51
|
+
|
|
52
|
+
What the skill does turns on whether a prior ticket exists, not on how the caller scoped the call.
|
|
53
|
+
|
|
54
|
+
**Generation, when a prior ticket does not exist.** The work was done on the branch without a ticket, so every section is authored now from the implementation and nothing is overwritten. The skeleton's `## Proposed solution` section is forward-looking by default; here it records the approach that the branch actually took, not a proposal still under consideration.
|
|
55
|
+
|
|
56
|
+
**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.
|
|
57
|
+
|
|
58
|
+
When the implementation diverges from what was proposed, report that divergence in the pull-request description, whose job is to describe the change under review. 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.
|
|
59
|
+
|
|
60
|
+
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.
|
|
61
|
+
|
|
62
|
+
<!-- include: ../_partials/ticket-criteria-conventions.md / -->
|
|
63
|
+
|
|
64
|
+
**Ratified-delta mode.** When the caller supplies a delta that it has already put to the user, such as a review's proposed-edit preview, the previewed delta is the whole of the revision. Apply exactly its lines and reproduce every other criterion and section verbatim. Do not seek further divergence between the ticket and the implementation: The caller's user consented to those lines, not to alignment as such. When applying a line reveals a change that the delta does not contain, stop and report it rather than widening the edit.
|
|
65
|
+
|
|
66
|
+
Invoked without a delta, alignment revises whichever criteria the implementation falsifies. The mode bounds how much of `## Acceptance criteria` changes; it never widens what alignment may touch.
|
|
67
|
+
|
|
68
|
+
**Spike mode.** If the branch implements a spike, use the spike ticket template in [spike conventions](../_data/spike-conventions.md), reconciling whether the investigation answered its questions rather than whether the branch met acceptance criteria.
|
|
69
|
+
|
|
70
|
+
- Keep tone professional and objective
|
|
71
|
+
- Focus on what was broken and what needed fixing
|
|
72
|
+
- Prioritize functional issues in "Must have"
|
|
73
|
+
- Place code quality/maintenance items in "Should have"
|
|
74
|
+
|
|
75
|
+
## Frontmatter resolution
|
|
76
|
+
|
|
77
|
+
The artifact's frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema.
|
|
78
|
+
|
|
79
|
+
Source `{model_id}` from your system-prompt environment block: the line `model named ... model ID is ...`.
|
|
80
|
+
|
|
81
|
+
Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill align-ticket-with-implementation --interactive true --model "{model_id}"` via Bash. Prepend the output verbatim to the artifact body.
|
|
82
|
+
|
|
83
|
+
Append `--extra copies_remote=true` when the remote write in [Write targets](#write-targets) succeeded, which records that the saved body is a copy of the ticket of record; see [ticket frontmatter](../_data/artifact-conventions.md#ticket-frontmatter). Omit it on the generation branch, which does not have a ticket of record to copy; under `--write-target=local`, whose snapshot is the newer contract by design; and when the remote write failed, leaving the remote without the body that the artifact contains. Writing the remote before saving the local artifact makes the outcome known in time to record it.
|
|
84
|
+
|
|
85
|
+
## Saving
|
|
86
|
+
|
|
87
|
+
### Write targets
|
|
88
|
+
|
|
89
|
+
The skill writes two artifacts: the ticket of record on its platform, and a local ticket artifact at the path derived in [Path resolution](#path-resolution). The frontmatter belongs to the local artifact alone; the body written to the platform does not include frontmatter.
|
|
90
|
+
|
|
91
|
+
**The ticket of record** resolves from the session-context manifest, from `ticket_url` or from `ticket_id` with `scm`, whichever artifact supplied the source content in step 1: A caller can name a local snapshot while a remote issue exists.
|
|
92
|
+
|
|
93
|
+
**Alignment writes it; generation does not.** On the alignment branch, apply the criteria revision to the remote's current body and write it per [platform-specific write](../_data/ticket-source-resolution.md#platform-specific-write). Generation does not have a ticket of record to write.
|
|
94
|
+
|
|
95
|
+
**Consent comes from the caller.** In ratified-delta mode, the user has already consented to the remote write, so do not ask again before it. Invoked without a delta, render the criteria revision as a delta and confirm before writing.
|
|
96
|
+
|
|
97
|
+
**`--write-target=local` writes the local artifact alone.** The ticket of record is left as it stands, however it resolved. The override selects the target and nothing else: The mode still bounds the revision, and the no-delta confirmation still precedes the write. `--write-target=remote` states the default explicitly and, when a ticket of record does not resolve, stops and reports the missing target rather than falling back to the local artifact.
|
|
98
|
+
|
|
99
|
+
**Order and reporting.** Write the remote, then save the local artifact, then report. A remote write that fails leaves the artifact saved and is reported as a failure, naming the manual step that remains; when the remote did not resolve, or `--write-target=local` held it back, report that the remote was not updated and which of the two is the reason.
|
|
100
|
+
|
|
101
|
+
### Path resolution
|
|
102
|
+
|
|
103
|
+
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 `artifact_base_dir`, `project_slug`, and `ticket_id` from it (the same invocation in step 1 already populated the manifest file, so this is a fast-path read).
|
|
104
|
+
|
|
105
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
106
|
+
|
|
107
|
+
Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
|
|
108
|
+
|
|
109
|
+
Artifact type: `ticket`. Filename format:
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
{timestamp}_{slug}_ticket.md
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Example: `20250809-1430Z_fix-memory-leak_ticket.md`
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: anti-patterns
|
|
3
|
+
description: Common anti-patterns to avoid including dependency overrides and quick-fix shortcuts
|
|
4
|
+
user-invocable: false
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Anti-patterns to avoid
|
|
8
|
+
|
|
9
|
+
Common but problematic approaches that should be avoided in favor of proper solutions.
|
|
10
|
+
|
|
11
|
+
## Package management
|
|
12
|
+
|
|
13
|
+
### Dependency overrides
|
|
14
|
+
|
|
15
|
+
- **Never use package overrides as first solutions** - Avoid `pnpm.overrides`, `yarn resolutions`, or `npm overrides` to force dependency versions. These create technical debt and version conflicts
|
|
16
|
+
- **Don't bypass dependency resolution** - Let package managers handle transitive dependencies through proper update commands
|
|
17
|
+
- **Avoid version pinning shortcuts** - Use semantic version ranges and proper dependency management
|
|
18
|
+
|
|
19
|
+
## Development approach
|
|
20
|
+
|
|
21
|
+
### Quick fixes over proper solutions
|
|
22
|
+
|
|
23
|
+
- **Don't suggest hacks before exploring proper solutions** - Exhaust maintainable, ecosystem-respecting approaches first
|
|
24
|
+
- **Avoid configuration shortcuts** - Don't bypass intended workflows through configuration tricks
|
|
25
|
+
- **Never prioritize immediate convenience over maintainability** - Proper solutions prevent technical debt
|
|
26
|
+
|
|
27
|
+
## Code quality
|
|
28
|
+
|
|
29
|
+
### Shortcuts that create debt
|
|
30
|
+
|
|
31
|
+
- **Don't accept "good enough" solutions** - If it creates maintenance burden, it's not good enough
|
|
32
|
+
- **Avoid band-aid fixes** - Address root causes rather than symptoms
|
|
33
|
+
|
|
34
|
+
### Suppression directives
|
|
35
|
+
|
|
36
|
+
- **A suppression directive (a comment that tells a linter or type checker to ignore a specific warning) is a design signal, not a workaround.** The rule flagged the code because it matched a pattern that is usually wrong.
|
|
37
|
+
- **Try these in order before suppressing inline:** (1) change the code so that the rule no longer triggers, usually the right answer; (2) reconfigure the rule if its default is wrong for the project; (3) define a scoped exception for a whole category that is legitimately exempt. Suppress inline only as a last resort, when the case is genuinely local and none of the above fits, such as an external boundary where the real type can't be known.
|
|
38
|
+
- **An `any` or a type assertion suppresses in the language what a directive suppresses in a comment.** Both silence the checker without changing what the code does, so the same ladder applies to both: Model the type that the value actually has, or return `unknown` and let the caller narrow it.
|
|
39
|
+
- **Write a rationale for every suppression that you introduce**, naming the rule, why it doesn't apply here, and what alternatives you rejected. Restating the rule is not a rationale.
|
|
40
|
+
|
|
41
|
+
```ts
|
|
42
|
+
// ❌ Suppress the warning
|
|
43
|
+
// eslint-disable-next-line complexity -- does a lot
|
|
44
|
+
function classify(order) {
|
|
45
|
+
/* long, deeply nested */
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
// ✅ Change the code so that the rule no longer triggers
|
|
49
|
+
function classify(order) {
|
|
50
|
+
return isExpedited(order) ? classifyExpedited(order) : classifyStandard(order);
|
|
51
|
+
}
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
### Error handling
|
|
55
|
+
|
|
56
|
+
- **Don't place non-failing code inside try/catch blocks** - Only wrap operations that can actually throw errors
|
|
57
|
+
- String concatenation, variable assignments, and other safe operations should be outside try/catch to clearly indicate what needs error handling
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: assess-ticket
|
|
3
|
+
description: Assess a ticket against the current codebase for drift, relevance, progress, advisability, and complexity, and prompt for follow-up actions
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Assess ticket
|
|
8
|
+
|
|
9
|
+
Assess a ticket against the current codebase across five dimensions: drift, relevance, progress, advisability, and complexity. Produces a structured assessment with constrained verdicts and supporting evidence.
|
|
10
|
+
|
|
11
|
+
**Announce at start:** "Using assess-ticket to assess {ticket reference} (mode: {mode})."
|
|
12
|
+
|
|
13
|
+
## Arguments
|
|
14
|
+
|
|
15
|
+
- **Ticket source** (optional): Issue URL, shorthand reference (`#99`, `issue 99`), file path, or plain text. When omitted, auto-resolved from the environment (see [ticket source resolution](../_data/ticket-source-resolution.md#auto-resolve)).
|
|
16
|
+
- **Mode** (optional): `drift`, `relevance`, `progress`, `advisability`, `complexity`, or `all` (default: `all`)
|
|
17
|
+
|
|
18
|
+
## Process
|
|
19
|
+
|
|
20
|
+
### 1. Resolve ticket source
|
|
21
|
+
|
|
22
|
+
Resolve the ticket source using the [ticket source resolution](../_data/ticket-source-resolution.md) table. Request the `updatedAt` field for temporal analysis, and the ticket's child counts (on GitHub, `subIssuesSummary`) for the umbrella case in [Baseline verdicts](#baseline-verdicts). Store the resolved metadata (platform, repo, issue number, last-updated date, child counts, ticket content). Never treat a ticket source without child counts, such as plain text or a file, as an umbrella. 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.
|
|
23
|
+
|
|
24
|
+
### 2. Investigate
|
|
25
|
+
|
|
26
|
+
Run the investigation for the requested mode, or for every dimension when mode is `all`, per [Assessment procedure](#assessment-procedure).
|
|
27
|
+
|
|
28
|
+
### 3. Output
|
|
29
|
+
|
|
30
|
+
Format the assessment per [Output format](#output-format). When a single mode is requested, output only that dimension's section (with the header and provenance line). When mode is `all`, output all dimensions in order, omitting both advisability and complexity when progress is `complete`.
|
|
31
|
+
|
|
32
|
+
Obtain the base SHA via `git rev-parse --short HEAD`.
|
|
33
|
+
|
|
34
|
+
### 4. Next steps
|
|
35
|
+
|
|
36
|
+
After presenting the assessment output, evaluate whether any verdicts are non-baseline and, if so, present follow-up actions. Follow [next steps after assessment](next-steps-after-assessment.md) for the verdict-to-actions mapping, combination rules, and interaction protocol, and [Baseline verdicts](#baseline-verdicts) for the baseline definition.
|
|
37
|
+
|
|
38
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
39
|
+
|
|
40
|
+
## Assessment procedure
|
|
41
|
+
|
|
42
|
+
<!-- include: ../../_partials/ticket-assessment.md / -->
|
|
43
|
+
|
|
44
|
+
## Key principles
|
|
45
|
+
|
|
46
|
+
- **Assessment first, action on request**: Lead with the assessment; offer follow-up actions but do not execute without user selection
|
|
@@ -0,0 +1,98 @@
|
|
|
1
|
+
# Next steps after assessment
|
|
2
|
+
|
|
3
|
+
Prompt for follow-up actions when any assessment verdict is non-baseline. The prompt applies in both `all` mode and single-mode assessments.
|
|
4
|
+
|
|
5
|
+
## Baseline definition
|
|
6
|
+
|
|
7
|
+
<!-- include: ../../_partials/ticket-assessment-baseline.md / -->
|
|
8
|
+
|
|
9
|
+
Complexity verdicts never trigger a prompt.
|
|
10
|
+
|
|
11
|
+
When all assessed verdicts are baseline, do not show a next-steps prompt.
|
|
12
|
+
|
|
13
|
+
## Verdict-to-actions mapping
|
|
14
|
+
|
|
15
|
+
Each non-baseline verdict maps to one or more follow-up actions. Offer no action for a verdict that the baseline definition counts as baseline, even when another dimension is off baseline: For an umbrella's `partial` progress, offer neither the update nor the close below. Actions describe intent; decide how to execute them based on the ticket platform and available tools.
|
|
16
|
+
|
|
17
|
+
### ♻️ Update actions
|
|
18
|
+
|
|
19
|
+
| Verdict | Action |
|
|
20
|
+
| ------------------- | --------------------------------------------- |
|
|
21
|
+
| Drift: `partial` | Update ticket to match current codebase state |
|
|
22
|
+
| Drift: `severe` | Update ticket to match current codebase state |
|
|
23
|
+
| Progress: `partial` | Update ticket to match current codebase state |
|
|
24
|
+
|
|
25
|
+
These collapse into a single "Update ticket" action regardless of how many dimensions trigger it.
|
|
26
|
+
|
|
27
|
+
### ♻️ Revise actions
|
|
28
|
+
|
|
29
|
+
| Verdict | Action |
|
|
30
|
+
| ---------------------------- | ---------------------------------------------- |
|
|
31
|
+
| Advisability: `questionable` | Revise ticket to address advisability concerns |
|
|
32
|
+
|
|
33
|
+
This action shares the ♻️ icon with "Update ticket to match current codebase state" but is a distinct action: It covers content or scope rework prompted by an advisability concern, not factual sync with the codebase. When both apply, both appear as separate options.
|
|
34
|
+
|
|
35
|
+
### 🏁 Close actions
|
|
36
|
+
|
|
37
|
+
| Verdict | Action |
|
|
38
|
+
| --------------------------- | ------------------------------------------------------ |
|
|
39
|
+
| Drift: `severe` | Close as outdated |
|
|
40
|
+
| Relevance: `superseded` | Close with comment explaining what superseded it |
|
|
41
|
+
| Progress: `partial` | Close and create a new ticket scoped to remaining work |
|
|
42
|
+
| Progress: `complete` | Close with comment summarizing completed work |
|
|
43
|
+
| Advisability: `inadvisable` | Close as inadvisable |
|
|
44
|
+
|
|
45
|
+
When multiple close actions apply, present each as a separate option; they differ in intent and outcome.
|
|
46
|
+
|
|
47
|
+
### 💬 Comment actions
|
|
48
|
+
|
|
49
|
+
| Verdict | Action |
|
|
50
|
+
| ---------------------- | ------------------------------------------------------- |
|
|
51
|
+
| Relevance: `uncertain` | Add comment noting ambiguous relevance for human triage |
|
|
52
|
+
|
|
53
|
+
## Combination protocol
|
|
54
|
+
|
|
55
|
+
When multiple dimensions produce non-baseline verdicts, their actions are combined into a single numbered list:
|
|
56
|
+
|
|
57
|
+
1. **Collect** actions grouped by type: ♻️ update → ♻️ revise → 🏁 close → 💬 comment.
|
|
58
|
+
2. **Deduplicate**: Each distinct action appears at most once. ♻️ "Update ticket to match current codebase state" and ♻️ "Revise ticket to address advisability concerns" are distinct actions and remain as separate options when both apply.
|
|
59
|
+
3. Number sequentially.
|
|
60
|
+
|
|
61
|
+
## Interaction protocol
|
|
62
|
+
|
|
63
|
+
1. Present the numbered action list immediately after the assessment output.
|
|
64
|
+
2. Wait for the user to select an option by number.
|
|
65
|
+
3. Execute the selected action.
|
|
66
|
+
|
|
67
|
+
## Output format
|
|
68
|
+
|
|
69
|
+
```
|
|
70
|
+
Next steps:
|
|
71
|
+
1. ♻️ {Update action}
|
|
72
|
+
2. 🏁 {Close action}
|
|
73
|
+
3. 💬 {Comment action}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Example: Combined output
|
|
77
|
+
|
|
78
|
+
Assessment produces drift: `partial`, relevance: `relevant` (baseline), progress: `partial`:
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
Next steps:
|
|
82
|
+
1. ♻️ Update ticket to match current codebase state
|
|
83
|
+
2. 🏁 Close and create a new ticket scoped to remaining work
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Action 1 combines drift and progress update triggers into a single option. Action 2 comes from progress. Relevance is baseline and contributes nothing.
|
|
87
|
+
|
|
88
|
+
## Example: Distinct ♻️ flavors
|
|
89
|
+
|
|
90
|
+
Assessment produces drift: `partial` and advisability: `questionable` (other dimensions baseline):
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
Next steps:
|
|
94
|
+
1. ♻️ Update ticket to match current codebase state
|
|
95
|
+
2. ♻️ Revise ticket to address advisability concerns
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
Both actions share the ♻️ icon but represent distinct intents (factual sync with the codebase versus content/scope rework), so they appear as separate numbered options rather than collapsing under the dedupe rule.
|