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,25 @@
|
|
|
1
|
+
# PR resolution
|
|
2
|
+
|
|
3
|
+
Shared contract for the `pr:` frontmatter field. `resolve-frontmatter.sh` does **not** resolve `pr:`; it does not have network, MCP, `gh`, or `curl` access, and most artifacts are written before a PR exists. The field is a best-effort human backlink, populated only when a PR URL is genuinely available.
|
|
4
|
+
|
|
5
|
+
## Who sets `pr:`
|
|
6
|
+
|
|
7
|
+
A skill supplies the URL by passing `--override pr=<url>` to `resolve-frontmatter.sh`; the script writes it verbatim into the frontmatter and omits the field when the skill does not pass an override. Only two writers have a URL at the moment they compose frontmatter:
|
|
8
|
+
|
|
9
|
+
- **`review-branch`** (when invoked via `review-pr`): Sets `pr:` from the PR metadata resolved by `review-pr`. In ticket-only / direct mode it does not have a URL and omits the field.
|
|
10
|
+
- **`respond-to-review`**: Forwards `pr:` from the review artifact to which it responds (that review has `pr:` when it was produced via `review-pr`). Omits it when the review has none.
|
|
11
|
+
|
|
12
|
+
Every other artifact-writing skill omits `pr:`; it does not have a URL at write time. The PR-creation and merge artifacts record the URL as a prose line in their own bodies; they do not use frontmatter.
|
|
13
|
+
|
|
14
|
+
## URL formats
|
|
15
|
+
|
|
16
|
+
| Platform | Format |
|
|
17
|
+
| --------- | ------------------------------------------------------------- |
|
|
18
|
+
| GitHub | `https://github.com/{owner}/{repo}/pull/{n}` (not `/issues/`) |
|
|
19
|
+
| Bitbucket | `https://bitbucket.org/{workspace}/{repo}/pull-requests/{n}` |
|
|
20
|
+
|
|
21
|
+
The PR-aware skills obtain the URL from the SCM directly (created by `gh pr create`, passed as a `pr_id` argument, or fetched from the API), so they do not need any interpolation.
|
|
22
|
+
|
|
23
|
+
## Rule
|
|
24
|
+
|
|
25
|
+
`pr:` is best-effort metadata. A missing URL is never an error and never blocks an artifact write: The field is simply omitted.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# PR source resolution
|
|
2
|
+
|
|
3
|
+
At session start, resolve the pull-request URL on which a skill operates, and reuse it across sessions. Skills that act on "the PR for this branch" should use this shared resolution logic.
|
|
4
|
+
|
|
5
|
+
> **Scope: Runtime discovery and reuse only.** This document covers how a skill _finds_ the PR URL at runtime: prefer a stored URL, otherwise discover one, persist what it resolves, and invalidate a stale stored URL. It does **not** cover the `pr:` frontmatter field. For who sets `pr:`, how it is written via `--override pr=<url>` to `resolve-frontmatter.sh`, and the rule that the field is best-effort and never blocks an artifact write, see [`pr-resolution.md`](pr-resolution.md).
|
|
6
|
+
|
|
7
|
+
## Stored PR URL
|
|
8
|
+
|
|
9
|
+
The branch manifest (`.agents/{branch}.branch-manifest.json`) persists a resolved `pr_url` so that it is reused across sessions instead of being re-discovered each time. The manifest is the single store; a skill reads the stored URL from the manifest JSON emitted by the deriver, without an extra call, and makes every write through the deriver's mutation flags, never by hand-editing the JSON.
|
|
10
|
+
|
|
11
|
+
- **Seed**: On a `PR-<n>` branch identity, the deriver seeds `pr_url` at compose time by building the platform's PR URL shape from the git remote's `owner/repo` and the PR number (host and path from `scm` per [`pr-resolution.md`](pr-resolution.md); `null` when the remote cannot be resolved). This mirrors how the deriver seeds `ticket_url` from a base and id (see [Stored ticket URL](ticket-source-resolution.md#stored-ticket-url)). An explicitly stored URL overrides the seed.
|
|
12
|
+
- **Prefer**: Use a stored `pr_url` as the default before discovering one from the platform.
|
|
13
|
+
- **Persist**: After a PR URL is resolved, store it by running `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --set-pr-url "{url}"`.
|
|
14
|
+
- **Never on the default branch**: That branch does not belong to any pull request, so a URL stored against it is whichever PR the last session happened to resolve. It is the stored default at step 2 of the runtime-resolution path below, which is how `merge-pr` without `--pr` would come to merge an arbitrary PR. Because reviewing someone else's PR from the default branch is ordinary, this is a case that arises rather than a misuse. The deriver enforces it: It refuses the write, reports on stderr, exits 0, and emits a manifest whose `pr_url` is null, and it clears a value already stored there. The same rule applies to `ticket_url`; see [Stored ticket URL](ticket-source-resolution.md#stored-ticket-url).
|
|
15
|
+
- **Invalidate**: When the stored URL does not yield the expected PR (the resource is not found at that URL, whether stale, wrong, moved, or deleted), clear it with `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --clear-pr-url`, then re-resolve. A cleared URL stays null, even across a preference change, until `--set-pr-url` stores a new one. This rule is platform-agnostic: It does not exempt any platform.
|
|
16
|
+
|
|
17
|
+
## Runtime-resolution path (`add-change-record`, `review-pr`, `merge-pr`)
|
|
18
|
+
|
|
19
|
+
These skills discover a PR for the current branch at runtime. Resolve in this order:
|
|
20
|
+
|
|
21
|
+
1. **Explicit argument**: When the command supplies a PR (e.g., `review-pr <pr_id>` or `merge-pr --pr {n}`), use it. An explicit argument always overrides the stored URL.
|
|
22
|
+
2. **Stored URL**: Otherwise, if the manifest has a non-null `pr_url`, use it as the default.
|
|
23
|
+
3. **Discover from the platform**: Otherwise, look up the PR for the current branch, dispatching on `scm`:
|
|
24
|
+
- **`"github"`**: `gh pr view --json number,title,body,labels,headRefName,baseRefName,url`.
|
|
25
|
+
- **`"bitbucket"`**: The branch query in [Bitbucket pull-request access](bitbucket-pr-access.md#finding-the-pull-request-for-a-branch).
|
|
26
|
+
|
|
27
|
+
If the lookup does not find a PR, stop and direct the user to create one.
|
|
28
|
+
|
|
29
|
+
After resolving the URL by any of the three paths above, **persist** it per [Stored PR URL](#stored-pr-url). If a stored URL from step 2 does not yield the expected PR, **invalidate** it and fall through to step 3.
|
|
30
|
+
|
|
31
|
+
## `respond-to-review` path
|
|
32
|
+
|
|
33
|
+
`respond-to-review` does not discover a PR from the platform at runtime. Its PR URL comes from the sibling review artifact's `pr:` frontmatter.
|
|
34
|
+
|
|
35
|
+
- **When the review artifact has a `pr:` value:** Forward it to `resolve-frontmatter.sh` as `--override "pr={pr_url}"` (the frontmatter-field contract; see [`pr-resolution.md`](pr-resolution.md)), and additionally **persist** it via `--set-pr-url` so that future sessions inherit it.
|
|
36
|
+
- **When the review artifact does not have a `pr:` field:** Fall back to the stored manifest `pr_url`, read from the manifest JSON that the deriver already emitted during session-context setup.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# Recommendation gradient
|
|
2
|
+
|
|
3
|
+
For numbered option-style questions with 2 or more choices, mark each option with a strength gradient and a brief rationale. The gradient applies to every list with substantive tradeoffs, including templated next-steps menus and substantive binary choices.
|
|
4
|
+
|
|
5
|
+
The render contract comes first; the doctrine behind it follows. Skills that ask option-style questions include the render contract inlined, so they consult this file only for the doctrine.
|
|
6
|
+
|
|
7
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
8
|
+
|
|
9
|
+
## Why the gate comes first
|
|
10
|
+
|
|
11
|
+
Asking is not a neutral act. It is cheap for the agent (it discharges responsibility for the call, rules out being wrong, and costs one paragraph) and expensive twice over: The developer pays a context switch to load the context, weigh the options, and answer, and the session that asked idles until the answer arrives. Across a dozen concurrent sessions those costs compound into decision fatigue and a stalled pipeline. A menu that the agent could have resolved itself transfers cost from the cheap side to the expensive one, and it looks like diligence while it happens, which is why it goes unnoticed and recurs.
|
|
12
|
+
|
|
13
|
+
The gate reads the markers rather than asking for judgment, because a judgment gate loses to a step that says to ask: An agent following a step list executes the step, and a rendered ■■■ makes the ask feel legitimate. The gate is only as reliable as the markers that it reads, and the observed bias is a marker set too weak: An option whose alternatives have disqualifying flaws gets ■■□, and the menu renders. The contract's leader check corrects that before the gate reads the markers. Two ■■□ at the top is a real fork, an unmarked list is a preference, and every other field is decided. The gated class is a closed list for the same reason: "consequential" is read generously, and a list is not.
|
|
14
|
+
|
|
15
|
+
A real fork is a choice between acceptable options, not doubt about a fact. On one change, the agent applied the work-type test and resolved the change to `feat`, then rendered one entry's typing, `feat` against `fix`, as a menu marked ■■□ on both options. The agent held the diff, the commits, the taxonomy, and the test that decides the type; the developer held the summary bullets, and answering meant reloading all of it to give a worse-informed answer than the agent's. The type has one right answer under the test, and the closeness of the two candidates was doubt about which one the test yields. The correct handling is a decision: Apply the test, pick, state the reason in one line, and let the pull-request body show the type before anything publishes.
|
|
16
|
+
|
|
17
|
+
A wrong-but-stated recommendation is cheaper to correct than a decision handed back: Correcting one costs a word, answering one costs an evaluation and a wait. The record keeps the developer's veto at the cheaper price. They read the ledger and overrule the entries with which they disagree, and the session has kept working in the meantime. "When in doubt, ask" is therefore the expensive default, not the safe one, and "when in doubt, record" is the rule that replaces it.
|
|
18
|
+
|
|
19
|
+
The gate and the marker are one rule seen twice. A menu that passes the gate is one that the markers could not settle or one that the developer authorizes, and the agent may still hold a strong evidence-based ranking inside an authorization menu, which is exactly when ■■■ is honest. A marker set below the strength actually available tells the developer nothing, and leaves them investigating every menu to find the few that are real forks.
|
|
20
|
+
|
|
21
|
+
## Why a manufactured bullet costs more than none
|
|
22
|
+
|
|
23
|
+
Bullets in an option list are weighted equally by construction; the format does not provide a minor bullet. Placing a line under `➖` asserts that the reader should weigh it, so they spend attention deciding how much it matters. For a manufactured con the answer is none, and the cost is paid before the worthlessness is discovered. That makes it waste rather than merely noise.
|
|
24
|
+
|
|
25
|
+
The con is also load-bearing for the menu's existence: Because an option recommended without a drawback reads as a decision rather than an option, presenting a settled call as a fork requires inventing a drawback. A fabricated con is the sign that the gate above was skipped, not an independent formatting slip.
|
|
26
|
+
|
|
27
|
+
When the honest cost is hard to find, that difficulty is itself evidence the option is strong. Spend the effort on finding the real cost or on omitting the bullet, never on manufacturing a plausible-sounding one.
|
|
28
|
+
|
|
29
|
+
A menu that looks balanced when the options are not misreports the analysis: It tells the developer that the agent found a close call. The developer relies on the menu for objective advice, and an even-handed look is the opposite of that when one option is sound and the others are flawed. A con whose size the reader cannot see does the same damage in a smaller form, since the reader has to investigate to learn that it is trivial. Both failures recur after being named, because a menu with a con on every option looks diligent while it misleads.
|
|
30
|
+
|
|
31
|
+
## Confirmation prompts vs. substantive binaries
|
|
32
|
+
|
|
33
|
+
Reserve `👍🏼👎🏼` for confirmation prompts, in which the agent has proposed a single action and the user's response is approve-or-redirect. "No" means "let's adjust or discuss," not a concrete alternative agent action.
|
|
34
|
+
|
|
35
|
+
A yes/no choice in which both paths have substantive tradeoffs takes the gradient with two numbered options instead. "No" then designates a concrete alternative agent action with its own consequences worth weighing.
|
|
36
|
+
|
|
37
|
+
Same surface phrasing, two correct renderings:
|
|
38
|
+
|
|
39
|
+
**Procedural (confirmation prompt):**
|
|
40
|
+
|
|
41
|
+
> Apply these revisions? 👍🏼👎🏼
|
|
42
|
+
|
|
43
|
+
"No" leads to discussion or revision; the prompt does not enumerate an alternative action.
|
|
44
|
+
|
|
45
|
+
**Substantive (gradient list):**
|
|
46
|
+
|
|
47
|
+
> #412 asks for the flag that this change adds, and also for a short alias that the change does not add. Want me to:
|
|
48
|
+
>
|
|
49
|
+
> 1. ■■□ Close #412 as superseded by this change:
|
|
50
|
+
> - ➖ the alias request closes with it, and it is not tracked by any other ticket
|
|
51
|
+
> 2. ■■□ Leave #412 open, retitled to the alias:
|
|
52
|
+
> - ➖ its 30 comments about the shipped flag bury the one about the alias
|
|
53
|
+
|
|
54
|
+
Both "yes" (close) and "no" (retitle) are concrete agent actions with their own tradeoffs. The decision edits a remote ticket, so it is in the gated class and is asked whatever the markers say.
|
|
55
|
+
|
|
56
|
+
## Ranking criteria
|
|
57
|
+
|
|
58
|
+
Rank options on correctness (behavior, API quality, architectural soundness, testability, maintainability) and treat convenience considerations (effort, blast radius, consistency with existing code) as secondary. See [design priorities](./design-priorities.md) for the full rule and a before/after example.
|
|
59
|
+
|
|
60
|
+
## Where these lists appear
|
|
61
|
+
|
|
62
|
+
An option-style question is rendered inside an [action-items block](./action-items.md), the terminal block that ends every response with an ask.
|
|
63
|
+
|
|
64
|
+
## Further examples
|
|
65
|
+
|
|
66
|
+
Single question without markers (pure taste call):
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
Want me to:
|
|
70
|
+
1. Use camelCase:
|
|
71
|
+
- ➕ matches the host file's local style
|
|
72
|
+
2. Use kebab-case:
|
|
73
|
+
- ➕ matches the package's public API style
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
Multiple questions in one response (Q1/Q2 identifiers):
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
**Q1: Naming convention?**
|
|
80
|
+
1. Use camelCase:
|
|
81
|
+
- ➕ matches the host file's local style
|
|
82
|
+
2. Use kebab-case:
|
|
83
|
+
- ➕ matches the package's public API style
|
|
84
|
+
|
|
85
|
+
**Q2: File location?**
|
|
86
|
+
1. ■■□ Co-locate with its only consumer:
|
|
87
|
+
- ➕ the check changes together with the form that it validates
|
|
88
|
+
2. ■■□ Place in the shared utility package:
|
|
89
|
+
- ➕ the billing package needs the same check once #588 lands
|
|
90
|
+
```
|
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
# Scope and deferral decisions
|
|
2
|
+
|
|
3
|
+
## The default: Fold in
|
|
4
|
+
|
|
5
|
+
By default, fold into the current change the work that the ticket didn't name (a discovered defect, an adjacent cleanup, a companion change) when the problem requires it, or when it is cheap and serves the ticket's goal. A ticket is a signal of intent, not a boundary; it belongs to us and can be refined. Spinning off a separate ticket needs an affirmative, stated reason:
|
|
6
|
+
|
|
7
|
+
- a genuinely separable concern,
|
|
8
|
+
- a materially different risk surface,
|
|
9
|
+
- size that would overwhelm the current change, or
|
|
10
|
+
- independent prioritization (the work can wait and competes with other backlog priorities on its own merits).
|
|
11
|
+
|
|
12
|
+
"The ticket didn't mention it" is never such a reason. When the discovered work addresses the same underlying problem, closing only the ticket-named part leaves the problem partially solved, so the discovered work is required, not optional.
|
|
13
|
+
|
|
14
|
+
**Authority.** The agent recommends the disposition of discovered work and builds on the recommendation; the developer vetoes. A fold-in is provisional and surfaces at the ticket checkpoint with its reason. A spin-off creates remote state, so it is asked before the ticket is created. Never declare work "out of scope" as settled fact, and never drop discovered work without reporting it.
|
|
15
|
+
|
|
16
|
+
**Feature responsibility.** When the current change introduces a feature, an avoidable user-visible defect caused by that feature is in-scope-by-default, a likely bug to fix here, not an automatic follow-up. Meeting the ticket's written acceptance criteria does not license merging a defect that the change itself introduced.
|
|
17
|
+
|
|
18
|
+
## Why a separate ticket is expensive
|
|
19
|
+
|
|
20
|
+
A new ticket is not free. Beyond the work itself, it requires the whole pipeline (creation, reading, evaluation, design, planning, implementation, review, checks, push, PR, approval, merge, and cleanup) and has an opportunity cost against everything else in the backlog. Small, clean tickets yield small, clean PRs that are easy to approve; that value is real, but it must outweigh the pipeline and opportunity costs, judged against the whole flow rather than any single step. For a one-line vocabulary fix or a two-line cleanup, the overhead can exceed the underlying work by an order of magnitude; putting it in a separate ticket is not risk-management but unnecessary cost.
|
|
21
|
+
|
|
22
|
+
Once work is judged genuinely separable, ticket it immediately rather than leaving it in the conversation; a tracker records that state so that the user does not have to remember it.
|
|
23
|
+
|
|
24
|
+
## Three-lane disposition model
|
|
25
|
+
|
|
26
|
+
The agent assigns every finding that it reports to one of three lanes. The agent never silently drops or withholds findings on threshold grounds: It recommends a lane for each finding and the developer can veto any of them, so the agent does not pre-filter on cost.
|
|
27
|
+
|
|
28
|
+
### Do now
|
|
29
|
+
|
|
30
|
+
Apply the change on the current branch in the current session.
|
|
31
|
+
|
|
32
|
+
- **Preferred default for trivial items** ([complexity levels 1–2](complexity-classification.md)) when branch state and code overlap permit (see [drive-by suitability](#drive-by-suitability) below).
|
|
33
|
+
- The agent commits the change as a drive-by: a small adjacent commit that is merged with the branch's main work.
|
|
34
|
+
- Zero ticket overhead.
|
|
35
|
+
|
|
36
|
+
### Batch later
|
|
37
|
+
|
|
38
|
+
Bundle related small items into a single follow-up ticket.
|
|
39
|
+
|
|
40
|
+
- Preferred when several drive-by-ineligible items have accumulated and their cumulative weight justifies one ticket.
|
|
41
|
+
- **Recommended over per-item ticketing when ≥2 trivial items remain** or when items share a `scope:` label or source artifact.
|
|
42
|
+
- Ticket body is a checklist with one entry per finding (description plus source attribution) and without a per-item complexity level.
|
|
43
|
+
- Cost: One ticket's overhead amortized across N items.
|
|
44
|
+
|
|
45
|
+
### Separate ticket
|
|
46
|
+
|
|
47
|
+
A standalone ticket for a single finding.
|
|
48
|
+
|
|
49
|
+
- Reserved for **substantive items** ([complexity levels 3+](complexity-classification.md)) and small items that don't fit any batch.
|
|
50
|
+
- Use when the work needs its own design, its own discussion, or its own scope label.
|
|
51
|
+
- Cost: Full per-ticket overhead.
|
|
52
|
+
|
|
53
|
+
## Drive-by suitability
|
|
54
|
+
|
|
55
|
+
A trivial item is a good drive-by candidate when all of these hold:
|
|
56
|
+
|
|
57
|
+
- **Branch is not already large or complicated.** Asking a reviewer to review one extra small change is fine; asking a reviewer to review one more change on top of a sprawling diff is not.
|
|
58
|
+
- **The drive-by doesn't mix concerns within a single file.** The standard "drive-by changes are bad" heuristic triggers too often: The reviewer's real difficulty arises when concerns mix in one file. **Changes in completely unrelated files are good drive-by candidates**: The reviewer can skim past them.
|
|
59
|
+
- **The drive-bys remain few.** Two or three drive-bys on a focused branch is fine; ten of them turns the branch into a collection of unrelated changes. Once a drive-by candidate would push the branch past the agent's judgment of "still readable as one change", assign subsequent items to **batch later**.
|
|
60
|
+
|
|
61
|
+
### Agent-consultable signals
|
|
62
|
+
|
|
63
|
+
- **Branch size**: `git diff --stat {default_branch}..HEAD`. Above ~10 files or ~500 lines of diff, treat the branch as already large; hold new drive-bys to a stricter standard.
|
|
64
|
+
- **Code overlap**: Is the target file present in `git diff --name-only {default_branch}..HEAD`?
|
|
65
|
+
- **Same-file overlap.** Caution: The reviewer must disentangle concerns within one diff. Prefer batch or separate ticket unless the change is genuinely related to the branch's main work.
|
|
66
|
+
- **Different-file.** Fine: The reviewer can skim past unrelated additions.
|
|
67
|
+
|
|
68
|
+
When a heuristic flags caution but the agent's judgment disagrees (e.g., the "large" branch is just a generated-file refresh), the agent should make the call and note the reasoning briefly.
|
|
69
|
+
|
|
70
|
+
## Worked example: Ticket #466 wrap-up
|
|
71
|
+
|
|
72
|
+
The wrap-up of ticket #466 raised six items. Under a reflexive "one ticket per finding" model, this would have produced six tickets. Under the cost-aware model, the same items produce zero or one ticket:
|
|
73
|
+
|
|
74
|
+
| Item | Nature | Lines | Lane under cost-aware model |
|
|
75
|
+
| ---- | ---------------------------------- | ----- | ----------------------------------------------------------------------- |
|
|
76
|
+
| T1 | vocabulary fix in SKILL.md pointer | 1 | **Do now** (drive-by, unrelated file) |
|
|
77
|
+
| T2 | `echo ""` cleanup | 2 | **Do now** (drive-by, unrelated file) |
|
|
78
|
+
| T3 | YAML quoting note | ~5 | **Do now** (drive-by, unrelated file) |
|
|
79
|
+
| R1 | minor recommendation | <10 | **Batch later** with R2 and S1 if the branch is too large for drive-bys |
|
|
80
|
+
| R2 | minor recommendation | <10 | **Batch later** with R1 and S1 if the branch is too large for drive-bys |
|
|
81
|
+
| S1 | minor suggestion | <10 | **Batch later** with R1 and R2 if the branch is too large for drive-bys |
|
|
82
|
+
|
|
83
|
+
Walk back through the list and apply the rule: Move any item that fails drive-by suitability to batch later; make any item that doesn't fit a batch a separate ticket.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Spike conventions
|
|
2
|
+
|
|
3
|
+
Spike work is an investigation, not a build: Its artifacts answer questions and enable a decision rather than deliver observable software behavior. This file defines the spike-shaped ticket and plan templates that the ticket- and plan-authoring skills use in place of their feature templates when the work is a spike.
|
|
4
|
+
|
|
5
|
+
Spike mode is entered explicitly (the invocation signals it) and is not auto-detected from ticket type, label, or title. Everything outside the two templates below (source resolution, staleness, Q&A, saving) is unchanged from the feature flow.
|
|
6
|
+
|
|
7
|
+
The concision and content-placement doctrines for feature tickets and plans apply unchanged; only what differs for a spike is stated here.
|
|
8
|
+
|
|
9
|
+
## Spike ticket template
|
|
10
|
+
|
|
11
|
+
```markdown
|
|
12
|
+
# Spike: {question}
|
|
13
|
+
|
|
14
|
+
## Question
|
|
15
|
+
|
|
16
|
+
{What is unknown, and why the answer matters: the uncertainty driving the spike.}
|
|
17
|
+
|
|
18
|
+
## Context
|
|
19
|
+
|
|
20
|
+
{Background, prior art, what prompted the question.}
|
|
21
|
+
|
|
22
|
+
## Scope
|
|
23
|
+
|
|
24
|
+
{What will and won't be investigated: "explore X, not Y".}
|
|
25
|
+
|
|
26
|
+
## Timebox
|
|
27
|
+
|
|
28
|
+
{Effort ceiling, e.g. "1 day".}
|
|
29
|
+
|
|
30
|
+
## Acceptance criteria
|
|
31
|
+
|
|
32
|
+
### Questions to answer
|
|
33
|
+
|
|
34
|
+
- [ ] {A question that the investigation must resolve.}
|
|
35
|
+
|
|
36
|
+
### Decisions to enable
|
|
37
|
+
|
|
38
|
+
- [ ] {A decision that the findings must make possible.}
|
|
39
|
+
|
|
40
|
+
Deliverable: a findings & recommendation artifact.
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
|
|
44
|
+
|
|
45
|
+
Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is a first-class section; acceptance criteria are questions-to-answer and decisions-to-enable rather than observable-behavior checkboxes; the spike ticket does not have a test or documentation criterion; the deliverable is a findings artifact, saved via the standard `save-artifact` conventions (without a dedicated artifact type).
|
|
46
|
+
|
|
47
|
+
## Spike plan template
|
|
48
|
+
|
|
49
|
+
```markdown
|
|
50
|
+
# Spike plan: {Title}
|
|
51
|
+
|
|
52
|
+
## Context
|
|
53
|
+
|
|
54
|
+
{What the spike investigates and how this plan connects to the ticket.}
|
|
55
|
+
|
|
56
|
+
## Approach
|
|
57
|
+
|
|
58
|
+
{The investigation strategy in 2-3 sentences.}
|
|
59
|
+
|
|
60
|
+
## Decisions taken
|
|
61
|
+
|
|
62
|
+
- {A decision that the agent took without asking, with its one-line reason; append `(provisional)` when it awaits the checkpoint.}
|
|
63
|
+
|
|
64
|
+
## Timebox
|
|
65
|
+
|
|
66
|
+
{Effort ceiling, mirroring the ticket.}
|
|
67
|
+
|
|
68
|
+
## Investigation steps
|
|
69
|
+
|
|
70
|
+
### Step 1: {Line of inquiry}
|
|
71
|
+
|
|
72
|
+
**Probes:** {Which question this step answers.}
|
|
73
|
+
**How:** {Approach: code read, throwaway prototype, benchmark, experiment.}
|
|
74
|
+
**Answered when:** {What resolving this step looks like.}
|
|
75
|
+
|
|
76
|
+
## Open questions & risks
|
|
77
|
+
|
|
78
|
+
{Unknowns that may redirect the investigation.}
|
|
79
|
+
|
|
80
|
+
## Deliverable
|
|
81
|
+
|
|
82
|
+
{The findings & recommendation artifact: the answers reached, a recommendation, and residual unknowns.}
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
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; a step does not have a test or documentation criterion.
|
|
86
|
+
|
|
87
|
+
## Aligning a spike
|
|
88
|
+
|
|
89
|
+
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.
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
# Ticket evaluation
|
|
2
|
+
|
|
3
|
+
A ticket (regardless of who created it) is a request, report, or suggestion, not a contract. We own the code; the ticket is input. Any behavioral or API change proposed by the ticket is a recommendation to evaluate, not an instruction to implement.
|
|
4
|
+
|
|
5
|
+
The author may have framed it poorly, missed the actual problem, scoped it too narrowly, proposed an unsound fix, or filed work that turns out to be inadvisable. Before designing to a ticket, evaluate it on its merits:
|
|
6
|
+
|
|
7
|
+
- **Is the problem real?** Reproduce or verify the underlying observation, not just the framing.
|
|
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: Work required by the problem folds into the current change by default rather than being deferred; see [scope-and-deferral](./scope-and-deferral.md). Scope can also be too large: When the ticket holds two or more pieces that each ship and can be verified on their own, raise the split before design begins, while the cut still costs an edit rather than a rewrite of the ticket, new children, a re-cut plan, and work already committed against it.
|
|
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
|
+
- **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
|
+
- **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
|
+
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,43 @@
|
|
|
1
|
+
# Ticket ID extraction (Jira-style)
|
|
2
|
+
|
|
3
|
+
This is the canonical contract for extracting a Jira-style ticket ID from a branch name or commit message subject. Both the `get-ticket-id` skill (Bash) and the `derive-session-context` bundled TypeScript helper implement this contract; downstream callers rely on the two implementations producing identical results for the same input.
|
|
4
|
+
|
|
5
|
+
## Contract
|
|
6
|
+
|
|
7
|
+
- **Pattern (case-insensitive):** `[A-Za-z]{2,}-[0-9]+`. Two or more letters, a hyphen, one or more digits. Single-letter prefixes (`a-1`, `x-99`) are not valid ticket IDs.
|
|
8
|
+
- **Position:** Matched anywhere in the input. The first match wins.
|
|
9
|
+
- **Output normalization:** The captured ID is uppercased before being returned (`mac-130` → `MAC-130`).
|
|
10
|
+
- **Suffix tolerance:** Trailing `.N` (sub-ticket) and `-description` segments are accepted in input but are not part of the canonical ID. The greedy `[0-9]+` boundary stops at any non-digit (`.`, `-letter`, `/`, `_`, end-of-string), so these suffixes are naturally truncated; post-match stripping is not required.
|
|
11
|
+
|
|
12
|
+
## Behavior table
|
|
13
|
+
|
|
14
|
+
The following inputs are the test oracle for both implementations.
|
|
15
|
+
|
|
16
|
+
| Input | Output |
|
|
17
|
+
| --------------------------- | -------------- |
|
|
18
|
+
| `MAC-130` | `MAC-130` |
|
|
19
|
+
| `mac-130` | `MAC-130` |
|
|
20
|
+
| `wt/compPlaN-795` | `COMPPLAN-795` |
|
|
21
|
+
| `wthorsen/MAC-130` | `MAC-130` |
|
|
22
|
+
| `wt/jira-123.1-some-suffix` | `JIRA-123` |
|
|
23
|
+
| `jira-123-1` | `JIRA-123` |
|
|
24
|
+
| `MAC-147-some-description` | `MAC-147` |
|
|
25
|
+
| `feat-2` | `FEAT-2` |
|
|
26
|
+
| `feat/foo-2` | `FOO-2` |
|
|
27
|
+
| `PR-123` | `PR-123` |
|
|
28
|
+
| `main` | _(empty)_ |
|
|
29
|
+
|
|
30
|
+
Two of these cases are surprising in isolation but follow directly from the contract:
|
|
31
|
+
|
|
32
|
+
- `feat-2 → FEAT-2`: `feat` is a valid two-or-more-letter prefix, so `feat-2` matches the Jira-style shape. Branch slugs that happen to start with a kebab-case word followed by a digit will be picked up as ticket IDs.
|
|
33
|
+
- `feat/foo-2 → FOO-2`: Because the match is unanchored, `foo-2` later in the string matches even though `feat/` does not.
|
|
34
|
+
|
|
35
|
+
This is intentional: Case-insensitive unanchored matching is the price of supporting `wt/mac-130` and `wthorsen/MAC-130` uniformly. Callers that want stricter shapes should not rely on this contract; use the bare-numeric fallback (described below) instead.
|
|
36
|
+
|
|
37
|
+
## Pull-request identifier
|
|
38
|
+
|
|
39
|
+
`PR-<n>` (e.g. `PR-123`) matches the pattern like any other two-letter prefix, so it extracts to `PR-123`. This is a sanctioned identity for a pull request that does not have a backing ticket, giving it a branch name and an artifact directory. Downstream URL derivation treats a `PR-<n>` id as a non-ticket: `derive-session-context` does not build a ticket URL for it, even when a ticket base URL is configured (see `resolveTicketUrls` in `compose-manifest.ts`).
|
|
40
|
+
|
|
41
|
+
## Bare-numeric fallback (out of scope)
|
|
42
|
+
|
|
43
|
+
When the input does not contain a Jira-style ID, the `get-ticket-id` script falls back to a **bare numeric prefix** anchored at the start of the input, formatted via `project.ticket_ref_prefix` from `.agents/preferences.yaml`. That fallback is a separate, orthogonal feature for `#`-style projects and is not covered by this contract. See `extract_bare_number` in `packages/guidance/content/scripts/get-ticket-id.sh` for the bash implementation and `extract-ticket-id.ts` in `packages/guidance/src/derive-session-context/` for the equivalent TypeScript implementation.
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# Ticket source resolution
|
|
2
|
+
|
|
3
|
+
Resolve a ticket source argument into ticket content and metadata. Skills that accept a ticket reference should use this shared resolution logic.
|
|
4
|
+
|
|
5
|
+
## Resolution table
|
|
6
|
+
|
|
7
|
+
| Input form | Resolution |
|
|
8
|
+
| ----------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
9
|
+
| URL to a known platform (GitHub, Jira, etc.) | Use the platform CLI or a connected read tool if available; otherwise, fetch the URL content |
|
|
10
|
+
| Other URL | Fetch the URL content |
|
|
11
|
+
| Shorthand reference (`#99`, `issue 99`, `GitHub issue #99`) | Resolve platform (see below), then fetch per [platform-specific fetch](#platform-specific-fetch) |
|
|
12
|
+
| File path | Read the file |
|
|
13
|
+
| Plain text | Use as-is |
|
|
14
|
+
| _(no source provided)_ | Auto-resolve from environment (see [auto-resolve](#auto-resolve)) |
|
|
15
|
+
|
|
16
|
+
**Persist the resolved URL.** After resolving by any form above (an explicitly supplied URL included, not only the auto-resolve path), store the resolved `ticket_url` in the branch manifest so that later sessions reuse it without re-resolving or re-pasting. On the default branch nothing is stored, and the deriver enforces that. See [Stored ticket URL](#stored-ticket-url).
|
|
17
|
+
|
|
18
|
+
## Auto-resolve
|
|
19
|
+
|
|
20
|
+
When the invocation does not provide a ticket source, attempt to derive the ticket from the current environment. This covers the common case in which the branch name encodes the ticket identity (e.g., branch `357` for GitHub issue #357, or branch `MAC-42/feat/foo` for Jira ticket MAC-42).
|
|
21
|
+
|
|
22
|
+
### Steps
|
|
23
|
+
|
|
24
|
+
1. **Get session context** by invoking the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) and reading the manifest JSON emitted on stdout. This JSON contains `ticket_id`, the persisted `ticket_url`, and `ticket_base_url` (the org-stable base mirrored from the `ticket.base_url` preference; see [Stored ticket URL](#stored-ticket-url)).
|
|
25
|
+
|
|
26
|
+
2. **Prefer the stored URL.** If `ticket_url` is a non-null string, fetch the ticket directly from that URL; skip the platform/identifier reconstruction below. If the stored URL does not yield the expected ticket, invalidate it per [Stored ticket URL](#stored-ticket-url) and continue with reconstruction.
|
|
27
|
+
|
|
28
|
+
3. **Otherwise reconstruct from `ticket_id`.** If `ticket_id` is `null`, auto-resolve fails; ask the user for a ticket source.
|
|
29
|
+
|
|
30
|
+
4. **Determine the platform and construct the fetch identifier:**
|
|
31
|
+
|
|
32
|
+
a. **If `ticket_id` is purely numeric** (e.g., `357`): The ID is a platform issue number. Determine the platform using the [platform resolution cascade](#platform-resolution-cascade). For GitHub, fetch issue `357`.
|
|
33
|
+
|
|
34
|
+
b. **If `ticket_id` contains a prefix** (e.g., `MAC-42`): The ID is a Jira-style key. The platform is Jira (or whichever platform hosts that project). The deriver includes a configured `ticket_ref_prefix` other than `#` in `ticket_id`, so a bare-number branch under `MAC-` arrives here as `MAC-357`.
|
|
35
|
+
|
|
36
|
+
c. If the platform still cannot be determined, ask the user.
|
|
37
|
+
|
|
38
|
+
d. **Construct the URL from a base when one is available.** If a base URL is known (`ticket_base_url` from the manifest, or `ticket.base_url` from `.agents/preferences.yaml`), the ticket URL is the base joined to `ticket_id` with a single `/` (e.g. `https://org.atlassian.net/browse/` + `MAC-42` → `https://org.atlassian.net/browse/MAC-42`). This is the reconstruction path for a Jira-style key: It yields the URL consumed by a URL-taking Jira read tool, and the URL to present and persist when the content cannot be fetched.
|
|
39
|
+
|
|
40
|
+
5. **Fetch the ticket** per [platform-specific fetch](#platform-specific-fetch).
|
|
41
|
+
|
|
42
|
+
6. **Persist the resolved URL.** Once a ticket URL is in hand (whether reconstructed here, supplied by the user, or fetched), store it for future sessions per [Stored ticket URL](#stored-ticket-url).
|
|
43
|
+
|
|
44
|
+
### When auto-resolve fails
|
|
45
|
+
|
|
46
|
+
If the ticket ID is `null` or the platform cannot be determined, do not guess. Ask the user for an explicit ticket source. The cost of asking is low; the cost of fetching the wrong ticket is high.
|
|
47
|
+
|
|
48
|
+
A caller may substitute its own fallback for this "ask the user" terminal step when it has a sound default source. For example, `review-branch` falls back to the most recent local `*_ticket.md` snapshot instead of prompting, so an unattended review can still proceed against a reasonable contract.
|
|
49
|
+
|
|
50
|
+
## Platform resolution cascade
|
|
51
|
+
|
|
52
|
+
Determine which platform a ticket belongs to:
|
|
53
|
+
|
|
54
|
+
1. Check `.agents/preferences.yaml` → `integrations` (if exactly one enabled, use it; if multiple, ask)
|
|
55
|
+
2. Check `git remote get-url origin` (e.g., `github.com` → GitHub)
|
|
56
|
+
3. Ask the user
|
|
57
|
+
|
|
58
|
+
This cascade is used by both [shorthand reference resolution](#shorthand-reference-resolution) and [auto-resolve](#auto-resolve).
|
|
59
|
+
|
|
60
|
+
## Shorthand reference resolution
|
|
61
|
+
|
|
62
|
+
Determine which platform `#99` refers to using the [platform resolution cascade](#platform-resolution-cascade).
|
|
63
|
+
|
|
64
|
+
## Platform-specific fetch
|
|
65
|
+
|
|
66
|
+
### GitHub
|
|
67
|
+
|
|
68
|
+
```
|
|
69
|
+
gh issue view --json number,title,body,labels,updatedAt {number}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
Skills may request a subset of these fields. The `updatedAt` field is needed by skills that perform temporal analysis (e.g., staleness checks) and may be omitted by skills that only need the ticket content.
|
|
73
|
+
|
|
74
|
+
### Jira
|
|
75
|
+
|
|
76
|
+
Access Jira Cloud through Atlassian's `acli`, falling back to a connected Jira read tool. Detect the CLI with `command -v acli`, and treat a non-zero exit from the fetch itself as unavailable: An `acli` that is installed but unauthenticated exits non-zero with an error on stderr and nothing on stdout, and that error does not distinguish an authentication failure from a missing issue, so fall through on the exit status rather than on the message.
|
|
77
|
+
|
|
78
|
+
**Preferred: `acli`.** Read the ticket body with the default view, which renders the description as text.
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
acli jira workitem view {key}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
When the source is a Jira URL rather than a key, the key is its `PROJECT-NUMBER` segment, which is the final segment of a `/browse/` URL.
|
|
85
|
+
|
|
86
|
+
When a skill needs structured metadata, such as the `updated` timestamp for a staleness check, add `--json --fields '*navigable,-description'`. The `--json` flag returns the raw REST v3 response, in which the description is Atlassian Document Format rather than Markdown, so exclude it there and take the body from the default view. First-time setup is `acli jira auth login --web`, a browser flow that does not mint an API token.
|
|
87
|
+
|
|
88
|
+
**Fallback: A connected Jira read tool.** Because tool names vary by server and by machine alias, identify the tool by its parameters:
|
|
89
|
+
|
|
90
|
+
- **Takes an issue URL**: Pass the ticket URL. Prefer this shape when both are connected, since it does not need site resolution.
|
|
91
|
+
- **Takes an issue key and a cloud ID**: Resolve the cloud ID first, from the same server's tool listing accessible Atlassian sites. It is the `id` of the site whose URL matches the ticket URL's host, or of the sole site listed when the ticket URL is not known. If neither settles it, ask the user which site hosts the ticket. Resolve it once and reuse it for the rest of the session.
|
|
92
|
+
|
|
93
|
+
**Last resort.** When neither is available, present the Jira key and ask the user for the ticket content. When `ticket.base_url` is configured, the ticket URL is reconstructed from the base and `ticket_id` (per [auto-resolve](#auto-resolve) step 4d), so it does not have to be supplied or re-pasted. A caller with a sound default source may substitute it for that prompt, as [When auto-resolve fails](#when-auto-resolve-fails) allows.
|
|
94
|
+
|
|
95
|
+
The stored URL applies throughout: A Jira ticket URL resolved once is reused on later sessions, and it is invalidated like any other stored URL when it does not yield the expected ticket (see [Stored ticket URL](#stored-ticket-url)).
|
|
96
|
+
|
|
97
|
+
## Platform-specific write
|
|
98
|
+
|
|
99
|
+
Write a revision back to the ticket of record, which the caller names; when the caller does not name a ticket, it is the ticket from which the revision's source came. The platform is `scm` from the session-context manifest, falling back to the [platform resolution cascade](#platform-resolution-cascade) when the manifest does not set `scm`. Under that default, a ticket that resolved from a file is written back to that file, and one that resolved from plain text does not have a write target.
|
|
100
|
+
|
|
101
|
+
**A partial revision is composed from the platform's current body.** When a skill revises one section of a ticket, it fetches the current body per [platform-specific fetch](#platform-specific-fetch) and applies the revision to that, so every section that it does not revise is carried over from the platform rather than from a local copy. A whole-ticket body approved by the user replaces the body outright.
|
|
102
|
+
|
|
103
|
+
**Nothing is reported as updated until the write succeeds.** A write that fails is reported as a failure, naming the manual step that remains.
|
|
104
|
+
|
|
105
|
+
### GitHub
|
|
106
|
+
|
|
107
|
+
Write the body to a scratch file per [gh body file](#gh-body-file), naming it `gh-body-issue{number}-{timestamp}.md`, then:
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
body_path="{absolute path from the write step}"
|
|
111
|
+
[ -s "$body_path" ] || { echo "Body file missing or empty: $body_path" >&2; exit 1; }
|
|
112
|
+
gh issue edit {number} --body-file "$body_path"
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
### Jira
|
|
116
|
+
|
|
117
|
+
Update through {skill?:update-jira-ticket}, which states the tool-shape branch and bundles the pre-flight checker that its HTML surface needs.
|
|
118
|
+
|
|
119
|
+
`acli`'s default view is text rather than Markdown and the write converts the whole description, so a partial revision re-renders the sections that it leaves alone; report it as a re-rendering of the whole description rather than an edit confined to the revised section.
|
|
120
|
+
|
|
121
|
+
### Other platforms
|
|
122
|
+
|
|
123
|
+
An automated write is not available for these platforms. Report that the ticket was not updated and present the composed body for the user to apply, rather than passing over the write in silence.
|
|
124
|
+
|
|
125
|
+
## Stored ticket URL
|
|
126
|
+
|
|
127
|
+
The branch manifest (`.agents/{branch}.branch-manifest.json`) persists a resolved `ticket_url` so that it is reused across sessions instead of being reconstructed or re-pasted each time. The manifest is the single store; a skill reads the stored URL from the manifest JSON emitted by the deriver, without an extra call, and makes every write through the deriver's mutation flags, never by hand-editing the JSON.
|
|
128
|
+
|
|
129
|
+
The manifest also includes `ticket_base_url`, mirroring the `ticket.base_url` preference. When a base and a `ticket_id` are both known, the deriver seeds `ticket_url` by joining them, so a bare Jira-style reference resolves to a URL without a supplied one. An explicitly stored URL always overrides that constructed default.
|
|
130
|
+
|
|
131
|
+
- **Prefer**: Auto-resolve uses a stored `ticket_url` before reconstructing one from `ticket_id`.
|
|
132
|
+
- **Persist**: After a ticket URL is resolved (reconstructed, supplied by the user, or fetched), store it by running `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --set-ticket-url "{url}"`.
|
|
133
|
+
- **Never on the default branch**: That branch is not derived from any ticket, so a URL stored against it is not its association but whichever ticket the last session happened to resolve, and a later session auto-resolving from it proceeds against an arbitrary one. The deriver enforces this: It refuses the write, reports on stderr, exits 0, and emits a manifest whose `ticket_url` is null. It clears a value already stored there for the same reason. A skill that decides the skip itself can report it in its own completion output instead of leaving it to a stderr line; `create-ticket` does. The same rule applies to `pr_url`; see [PR source resolution](pr-source-resolution.md#stored-pr-url).
|
|
134
|
+
- **Invalidate**: When the stored URL does not yield the expected ticket (the resource is not found at that URL, whether stale, wrong, moved, or deleted), clear it with `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs --clear-ticket-url`, then re-resolve. A cleared URL stays null, even across a preference change, until `--set-ticket-url` stores a new one. This rule is platform-agnostic: It does not exempt any platform. For GitHub, re-resolution re-derives or re-fetches; for Jira, re-resolution re-fetches through `acli` or a connected read tool, and re-prompts the user only when neither is available.
|
|
135
|
+
|
|
136
|
+
## Resolved metadata
|
|
137
|
+
|
|
138
|
+
After resolution, store the following metadata for use by the calling skill:
|
|
139
|
+
|
|
140
|
+
- **Platform**: Which platform the ticket was resolved from (e.g., GitHub, Jira, file, plain text)
|
|
141
|
+
- **Repository**: The repository identifier (e.g., `owner/repo`), if applicable
|
|
142
|
+
- **Issue number**: The numeric identifier, if applicable
|
|
143
|
+
- **Last-updated date**: The ticket's last-modified timestamp, if available from the platform
|
|
144
|
+
- **Ticket content**: The title, body, labels, and any other retrieved fields
|
|
145
|
+
- **Ticket URL**: Persisted across sessions in the branch manifest's `ticket_url` field, written through the deriver's mutation flags; see [Stored ticket URL](#stored-ticket-url)
|
|
146
|
+
|
|
147
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|