codeassembly-guidance 0.1.0 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +984 -0
- package/CHANGELOG.md +240 -0
- package/README.md +45 -99
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +21 -5
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/kb-standard-tags.md +7 -0
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +17 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +206 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
- package/content/guidance/rulebooks/commit-conventions.md +5 -4
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
- package/content/guidance/shared/AGENTS.md +39 -4
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +98 -98
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +2 -0
- package/content/skills/_data/artifact-conventions.md +64 -16
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/complexity-classification.md +1 -1
- package/content/skills/_data/design-priorities.md +15 -4
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +21 -6
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +22 -12
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/apply-guidance-edits.md +5 -0
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +11 -11
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +7 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-composition.md +40 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/_partials/ticket-skeleton.md +15 -1
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +127 -0
- package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
- package/content/skills/assess-usability/SKILL.md +98 -0
- package/content/skills/capture-event/SKILL.md +4 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-feedback/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +3 -3
- package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +28 -10
- package/content/skills/create-pr/SKILL.md +7 -6
- package/content/skills/create-ticket/SKILL.md +64 -23
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
- package/content/skills/design-and-plan/SKILL.md +17 -18
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +27 -23
- package/content/skills/index-prototypes/SKILL.md +86 -31
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +4 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +5 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
- package/content/skills/kb-retrieve-events/SKILL.md +20 -11
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
- package/content/skills/kb-update-events/SKILL.md +10 -7
- package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
- package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +2 -2
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-guidance/SKILL.md +97 -0
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +354 -3
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +3 -1
- package/content/skills/streamline-guidance/SKILL.md +11 -16
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +23 -14
- package/content/skills/testing-conventions/SKILL.md +81 -8
- package/content/skills/triage-feedback/SKILL.md +150 -0
- package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +12 -12
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/code-health-assessor.md +98 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/feedback-triage-challenger.md +81 -0
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/lesson-clusterer.md +68 -0
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +21 -17
- package/schemas/preferences.v1.json +50 -7
- package/schemas/work-types.v1.json +1 -1
- package/content/_partials/code-descriptions.md +0 -4
- package/content/_partials/code-style.md +0 -7
- package/content/_partials/live-repo-writes.md +0 -13
- package/content/_partials/reduced-object-relative.md +0 -28
- package/content/_partials/test-structure-audit-checklist.md +0 -7
- package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
- package/content/skills/_partials/next-steps-after-review.md +0 -350
- package/content/skills/_partials/ticket-concision.md +0 -18
- package/content/skills/_partials/ticket-placement.md +0 -14
- package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
- package/content/skills/testing-conventions/mistakes.md +0 -1
|
@@ -2,6 +2,15 @@
|
|
|
2
2
|
|
|
3
3
|
Standards for AI-generated artifact storage, naming, and lifecycle.
|
|
4
4
|
|
|
5
|
+
## Purpose
|
|
6
|
+
|
|
7
|
+
The artifact directory is the developer's audit trail of development. Its plans, reviews, change summaries, pull-request and merge records, devlogs, and chat summaries record what an agent produced and when, each as it stood at the moment of writing (see [Mutability](#mutability)). The directory is not a source of truth, and it is not a home for durable content:
|
|
8
|
+
|
|
9
|
+
- **Durable content.** Put instructions, a procedure, or a reference that a later session must find in the repository (its docs, `AGENTS.md`, or a README), or in a skill or rulebook when they apply across repositories. A later session looks there, not in the artifact directory.
|
|
10
|
+
- **Authority.** An artifact is not authority on the current state of code, design, or decisions. Treat what a search of artifacts turns up as history, and verify it against the repository, the tickets, and the pull requests.
|
|
11
|
+
- **Conclusions.** A conclusion that a reader of the ticket needs is posted on the ticket, and the artifact keeps the evidence. For a spike, see [Closing post](spike-conventions.md#closing-post).
|
|
12
|
+
- **Inputs to the same work.** A skill that reads an artifact as an input to the same piece of work, such as the plan that `implement-plan` executes or the change summary that `create-pr` publishes, uses the artifact as the workflow intends.
|
|
13
|
+
|
|
5
14
|
## Directory structure
|
|
6
15
|
|
|
7
16
|
All artifacts are stored under a configurable base directory (`base_dir`, default `~/ai-artifacts`). Invoke the bundled session-context deriver (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) to resolve `artifact_base_dir`:
|
|
@@ -17,6 +26,25 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
|
|
|
17
26
|
│ │ ├── manifest.json
|
|
18
27
|
│ │ ├── shots/{slug}-v{n}.png
|
|
19
28
|
│ │ └── {slug}-v{n}.html
|
|
29
|
+
│ ├── usability/ ← a usability assessment's lens reports and evidence, kept by `assess-usability`
|
|
30
|
+
│ │ ├── {lens}-report.md
|
|
31
|
+
│ │ └── {lens}/{finding-id}-{slug}.png
|
|
32
|
+
│ ├── code-health/ ← a code-health assessment's sense document, reports, and proposals, kept by `assess-code-health`
|
|
33
|
+
│ │ ├── sense.json
|
|
34
|
+
│ │ ├── {lens}/report.md
|
|
35
|
+
│ │ └── {lens}/proposals.json
|
|
36
|
+
│ ├── triage/ ← a findings triage's working files, kept by `triage-spike-findings`
|
|
37
|
+
│ │ ├── findings.md
|
|
38
|
+
│ │ ├── inventory.md
|
|
39
|
+
│ │ ├── recommendations.md
|
|
40
|
+
│ │ ├── challenge.md
|
|
41
|
+
│ │ ├── dispositions.json
|
|
42
|
+
│ │ ├── preview/ ← the rendered comments shown at the confirmation
|
|
43
|
+
│ │ │ ├── dispositions-comment.md
|
|
44
|
+
│ │ │ └── comment-{issue}.md
|
|
45
|
+
│ │ └── rendered/ ← the rendered comments that are posted
|
|
46
|
+
│ │ ├── dispositions-comment.md
|
|
47
|
+
│ │ └── comment-{issue}.md
|
|
20
48
|
│ └── {run-id}/ ← review run directory
|
|
21
49
|
│ ├── {NN}_{role}_{artifact}.md
|
|
22
50
|
│ └── ...
|
|
@@ -26,13 +54,16 @@ All artifacts are stored under a configurable base directory (`base_dir`, defaul
|
|
|
26
54
|
│ └── {timestamp}_{slug}_deferred-findings.md ← project-scoped fallback when a ticket is not in session
|
|
27
55
|
├── devlogs/
|
|
28
56
|
│ └── {timestamp}_{concise-title}.md ← project-scoped fallback when a ticket is not in session
|
|
57
|
+
├── feedback-triage/
|
|
58
|
+
│ ├── {timestamp}_{slug}_feedback-triage.md ← project-scoped fallback when a ticket is not in session
|
|
59
|
+
│ └── {timestamp}_work/ ← the run's working files
|
|
29
60
|
└── plans/
|
|
30
61
|
└── {design-documents}.md
|
|
31
62
|
```
|
|
32
63
|
|
|
33
64
|
### Project slug
|
|
34
65
|
|
|
35
|
-
Always present under `projects/`, even when `{base_dir}/` is inside the project
|
|
66
|
+
Always present under `projects/`, even when `{base_dir}/` is inside the project, so that an artifact's path has the same shape wherever `base_dir` lies. Invoke the bundled session-context deriver to obtain `project_slug`.
|
|
36
67
|
|
|
37
68
|
### Ticket ID
|
|
38
69
|
|
|
@@ -42,7 +73,19 @@ A `project.ticket_ref_prefix` other than `#` is part of the ticket ID, so it nam
|
|
|
42
73
|
|
|
43
74
|
### Prototype sets
|
|
44
75
|
|
|
45
|
-
`prototypes/`
|
|
76
|
+
`prototypes/` contains the ticket's one prototype set: the sources, the stored screenshots, and the manifest from which `index-prototypes` renders the set's index page. The page itself is rendered into the session's scratch directory for publishing and is not kept here.
|
|
77
|
+
|
|
78
|
+
### Usability evidence
|
|
79
|
+
|
|
80
|
+
`usability/` contains the working files of the ticket's usability assessment: each lens's report and each lens's evidence, which is screenshots in a browser assessment and transcripts in a CLI assessment. The `usability-findings` artifact cites the evidence by paths relative to the ticket directory, so the evidence stays in the ticket directory. A CLI assessment's fixtures are scratch directories outside the ticket directory, and nothing keeps them.
|
|
81
|
+
|
|
82
|
+
### Code-health working files
|
|
83
|
+
|
|
84
|
+
`code-health/` contains the working files of the ticket's code-health assessment: the sense document with each check's log beside it, the test reports that the sensors read, each lens's report and checked proposals, and the merged proposals. The `code-health-findings` artifact cites code by paths relative to the repository root, so it does not depend on these files; they record what the run measured.
|
|
85
|
+
|
|
86
|
+
### Triage working files
|
|
87
|
+
|
|
88
|
+
`triage/` contains the working files of a triage of the ticket's findings: a local copy of the findings when they came from an artifact URL, the inventory, the recommendations that the challenger reads, the challenger's reply, the dispositions record from which the `dispositions` artifact is rendered, and the comments rendered from that record: `preview/` with placeholders for the confirmation, `rendered/` with every number for posting. The record stays here as a working file; the artifact is the rendered text.
|
|
46
89
|
|
|
47
90
|
### Run directories
|
|
48
91
|
|
|
@@ -60,11 +103,7 @@ projects/{project-slug}/tickets/{ticket-id}/{run-id}/
|
|
|
60
103
|
|
|
61
104
|
Example: `20260221-034100Z-interactive`
|
|
62
105
|
|
|
63
|
-
A ticket's **active run** is its newest run directory of mode `interactive`, by the timestamp in its name. A review
|
|
64
|
-
|
|
65
|
-
### Persistent export destination
|
|
66
|
-
|
|
67
|
-
Artifacts under `{base_dir}/` are ephemeral when `base_dir` is a git-ignored path (the default). In worktrees, they are lost on deletion. The `export-ai-artifacts.sh` script copies them to `~/ai-artifacts/projects/{project-slug}/` for long-term retention, preserving the same directory structure. Exported artifacts are immutable (first export wins).
|
|
106
|
+
A ticket's **active run** is its newest run directory of mode `interactive`, by the timestamp in its name. A review is saved into the active run, and the author's response is saved into the run that contains the review, so a review, the response, and a re-review share one run. A new run directory is created, when the review is written, only when the ticket directory does not contain an active run. A run of mode `orchestrated` is never active. `resolve-review-run` applies this definition.
|
|
68
107
|
|
|
69
108
|
## Path resolution
|
|
70
109
|
|
|
@@ -107,11 +146,12 @@ Ticket-level artifacts and run directories are both stored here. Invoke the bund
|
|
|
107
146
|
| chats | `chats` | `{base_dir}/projects/{project-slug}/chats/` |
|
|
108
147
|
| deferred-findings | `deferred-findings` | `{base_dir}/projects/{project-slug}/deferred-findings/` |
|
|
109
148
|
| devlogs | `devlogs` | `{base_dir}/projects/{project-slug}/devlogs/` |
|
|
149
|
+
| feedback-triage | `feedback-triage` | `{base_dir}/projects/{project-slug}/feedback-triage/` |
|
|
110
150
|
| plans | `plans` | `{base_dir}/projects/{project-slug}/plans/` |
|
|
111
151
|
|
|
112
|
-
Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with
|
|
152
|
+
Non-ticket paths are relative to the project directory. Category names remain configurable via `artifacts.paths.{category}` in preferences.yaml, with two exceptions: `deferred-findings` and `feedback-triage` are hardcoded and cannot be overridden.
|
|
113
153
|
|
|
114
|
-
Devlogs
|
|
154
|
+
Devlogs, deferred-findings, and feedback-triage artifacts are dual-homed: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket-id}/`; otherwise they fall back to the project-scoped paths above (`devlogs/`, `deferred-findings/`, and `feedback-triage/`). All filenames in these types use the standard `YYYYMMDD-HHMMSSZ` ticket-level timestamp shape regardless of which directory they are written to.
|
|
115
155
|
|
|
116
156
|
## Naming conventions
|
|
117
157
|
|
|
@@ -125,7 +165,7 @@ Devlogs and deferred-findings artifacts are dual-homed: When a ticket is in sess
|
|
|
125
165
|
- **slug**: Kebab-case descriptor drawn from work context, e.g., branch description (`improve-artifact-naming`) or commit subject (`fix-login-validation`). Max 60 chars, filesystem-safe.
|
|
126
166
|
- **artifact-type**: One of the registered types (see below)
|
|
127
167
|
|
|
128
|
-
When the ticket directory already contains artifacts for this change, reuse their slug; derive a fresh one only when the change's descriptor has
|
|
168
|
+
When the ticket directory already contains artifacts for this change, reuse their slug; derive a fresh one only when the change's descriptor has changed. One change has one name, which keeps it legible where the enclosing path is not in view: an editor tab, a search result, an export.
|
|
129
169
|
|
|
130
170
|
### Run artifacts (review workflow)
|
|
131
171
|
|
|
@@ -236,7 +276,7 @@ Invocation surface:
|
|
|
236
276
|
node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs
|
|
237
277
|
```
|
|
238
278
|
|
|
239
|
-
The deriver prints the manifest JSON to stdout and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect.
|
|
279
|
+
The deriver prints the manifest JSON to stdout and writes it to `.agents/{sanitized-branch}.branch-manifest.json` as a side effect. Because every invocation recomposes the derived fields from the current preferences and git state, a preference change takes effect on the next call. The file keeps `created_at` and the URLs written by the mutation flags (recorded in `explicit_urls`), and the deriver rewrites it only when its content changes. On the default branch, the deriver drops any stored `ticket_url` or `pr_url` per [Stored ticket URL](ticket-source-resolution.md#stored-ticket-url). Diagnostics are printed to stderr; exit 0 on success, 1 on hard failure (corrupt preferences, detached HEAD, schema-validation error).
|
|
240
280
|
|
|
241
281
|
When authoring a new skill that needs session-context fields: Invoke the bundled deriver and read the fields from the emitted JSON. Do not rely on any other caller having populated the manifest first: The deriver is the single derivation surface and is safe to call from any context.
|
|
242
282
|
|
|
@@ -301,7 +341,7 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
|
|
|
301
341
|
|
|
302
342
|
Each override is recorded beside the field that it overrides rather than in its place. A skill that needs the effective record reads it from [`resolve-effective-record`](title-templates.md#resolve-effective-record) rather than applying the overrides itself.
|
|
303
343
|
|
|
304
|
-
**The change summary's body ends with the rendered `change-record` block**, which
|
|
344
|
+
**The change summary's body ends with the rendered `change-record` block**, which contains the change entries and the consolidated record for the pull request. `create-pr` copies the body from `## What` onward, so the block is copied into the pull-request body without being rendered again.
|
|
305
345
|
|
|
306
346
|
The frontmatter stays flat, whereas the `change-record` block nests the consolidated record, the overrides, and the entries, because the artifact store is an Obsidian vault and Obsidian's Properties editor does not handle nested maps. That is also why the entries are recorded in the block rather than as a nested frontmatter field.
|
|
307
347
|
|
|
@@ -323,7 +363,7 @@ This artifact uses the [universal artifact frontmatter](#universal-artifact-fron
|
|
|
323
363
|
|
|
324
364
|
## run-index.json
|
|
325
365
|
|
|
326
|
-
Machine-readable metadata for a run directory. The retired orchestration engine wrote it
|
|
366
|
+
Machine-readable metadata for a run directory. The retired orchestration engine wrote it; the current skills do not. `run-core` parses it.
|
|
327
367
|
|
|
328
368
|
Every example and value list in this section and in [V3 format](#v3-format-event-sourced-runs) describes runs written by the retired engine, so its roles, agents, phases, and modes are historical values.
|
|
329
369
|
|
|
@@ -707,16 +747,24 @@ The first `coder_change-summary` in a run does not have dispositions (nothing to
|
|
|
707
747
|
|
|
708
748
|
- `brief`: The shared brief that a round of prototype builders receives; `prepare-prototype-brief` saves it at its checkpoint
|
|
709
749
|
- `change-summary`: Branch change summary for PRs
|
|
710
|
-
- `
|
|
750
|
+
- `code-health-brief`: The brief that every lens of a code-health assessment reads: the unit and its hotspots, the reuse-candidate directory and library inventory, the lenses with their rulebooks and caps, and the exclusions; `assess-code-health` saves it at its checkpoint
|
|
751
|
+
- `code-health-findings`: The merged, ungraded proposals of a code-health assessment, ranked by reach and hotspot rank, with the proposed groupings, the proposals that a prior triage or an issue already tracks, the residual unknowns, and the lens reports; `assess-code-health` saves it, and `triage-spike-findings` reads it
|
|
752
|
+
- `comparison`: Findings across a round of prototypes: the points on which they agree and those on which they diverge, a table of every distinctive idea with an empty decision, and which decisions the round leaves open; `prepare-prototype-brief` saves it after the index
|
|
711
753
|
- `deferred-findings`: Record of findings deferred during a `wrap-up` session, with cross-references to created tickets (falls back to non-ticket path when a ticket is not in session)
|
|
754
|
+
- `dispositions`: The rendered dispositions of a triage of findings, the text that `triage-spike-findings` posts on the triage ticket: every item with its disposition, its confidence and value, where it went, and its reason, with the challenge's summary; the JSON record from which it is rendered stays in `triage/`
|
|
712
755
|
- `devlog`: Development log entry (falls back to non-ticket path when a ticket is not in session)
|
|
756
|
+
- `feedback-triage`: The record of a `triage-feedback` run: each surfaced cluster of feedback events with its signals, priority, challenge, disposition, and result, and the remainder left in the pool. A deferred event's `addressed-by` names the artifact, whose filename timestamp dates the deferral; the run's working files stay in `{timestamp}_work/` beside it (falls back to non-ticket path when a ticket is not in session)
|
|
757
|
+
- `idea-decisions`: The idea table of a round of prototypes with the decision on each idea filled; `prepare-prototype-brief` saves it after the developer decides each idea, and the end vision cites it
|
|
713
758
|
- `merge`: Record of a merged pull request; `capture-lede-decision` reads its `## Body` as the merged side of a lede episode
|
|
714
759
|
- `plan`: Implementation plan document
|
|
715
760
|
- `plan-review`: Plan review findings (completeness and correctness analysis)
|
|
716
761
|
- `plan-v2`: Refined implementation plan after review and revision
|
|
717
762
|
- `pull-request`: PR description file; `capture-lede-decision` reads its `## What` as the agent's side of a lede episode
|
|
763
|
+
- `refinement-log`: The accepted changes of one session of `refine-prototype`, grouped under the id of the version that each one entered, with the transplants' sources and the open forks; the end vision reads it with the `idea-decisions` artifact
|
|
718
764
|
- `review`: Code review (ticket-level, commit scope)
|
|
719
765
|
- `ticket`: Issue ticket
|
|
766
|
+
- `usability-brief`: The brief that every lens of a usability assessment reads: the medium, the targets and their write rules, the lenses with their minimum use cases, and the exclusions; `assess-usability` saves it at its checkpoint
|
|
767
|
+
- `usability-findings`: The merged findings of a usability assessment, ranked by effect and reach, with the use-case outcomes, the ideas, the proposed groupings, the residual unknowns, and the lens reports; `assess-usability` saves it, and `triage-spike-findings` reads it
|
|
720
768
|
|
|
721
769
|
### Non-ticket artifacts
|
|
722
770
|
|
|
@@ -897,9 +945,9 @@ Insights never have criticality, never block a merge, and never count toward a r
|
|
|
897
945
|
|
|
898
946
|
A saved artifact is a point-in-time record of what its author produced at the moment of writing. Correct one that got its own subject wrong; never edit one toward what has happened since, whether a later human edit to the remote to which it was published, a rebase that leaves `baseSha` and `commit` unresolvable, or a subsequent turn of the session that wrote it. Divergence from current state is the artifact doing its job, so it is never reported as a defect or raised as a repair for the user to weigh. A step that discloses which of two candidate sources it measured against is reporting its own input, not proposing a reconciliation.
|
|
899
947
|
|
|
900
|
-
The `pull-request` and `merge` records
|
|
948
|
+
The `pull-request` and `merge` records contain a marker that directs a reading agent to leave the record unedited, stated in the file rather than left to standing guidance, because `capture-lede-decision` reads them and a rewrite corrupts it silently. The other artifacts do not have one.
|
|
901
949
|
|
|
902
|
-
A flow still composing its own artifact has
|
|
950
|
+
A flow still composing its own artifact has not yet passed it to anything downstream, so overwriting that artifact finishes its record rather than revising a finished one.
|
|
903
951
|
|
|
904
952
|
A later flow that revises a finished record writes a new artifact rather than editing the old one. `refine-plan` saves its output as `plan-v2` under a later timestamp, leaving the plan that it refines intact.
|
|
905
953
|
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Branch currency
|
|
2
|
+
|
|
3
|
+
A branch whose base is behind the remote's default branch gets designed, planned, or implemented without the changes that the default branch has gained since. Check the branch before such work starts, so that the check reveals the gap while it is still cheap to close.
|
|
4
|
+
|
|
5
|
+
## When to check
|
|
6
|
+
|
|
7
|
+
Check a branch other than the default branch, before the work starts. Skip the check on the default branch, comparing `branch_name` with `default_branch` stripped of its remote (everything after its first `/`), and on a detached HEAD, which the manifest reports as an empty `branch_name`. Read both values from the session-context manifest, never from git directly, so that the remote and the default branch follow the repository's preferences.
|
|
8
|
+
|
|
9
|
+
## Invocation
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
node {harness_home_dir}/scripts/check-branch-currency.mjs --base {default_branch} [--path {path}]...
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Pass one `--path` for each file or directory that the work touches, relative to the repository root, as the calling skill names them. Pass only paths that exist in the tree; a ticket that describes its area in prose does not supply any. The helper fetches the default branch, which is read-only, and prints one JSON object. It exits non-zero on a usage error, or when git fails after the fetch; act on a non-zero exit as on `fetched: false`, with the helper's stderr as the error.
|
|
16
|
+
|
|
17
|
+
## Acting on the result
|
|
18
|
+
|
|
19
|
+
**`fetched: false`.** Report in one line that the branch check did not run, with the `error`, and continue. Never report the branch as current. When the `consult-sandbox-conventions` skill is deployed, consult it before reading the error as a missing credential or an unreachable network.
|
|
20
|
+
|
|
21
|
+
**`behind: 0`.** Say nothing.
|
|
22
|
+
|
|
23
|
+
**`behind` above 0, `ahead: 0`, and `clean: true`.** The branch does not have any commits of its own or uncommitted changes, so a fast-forward loses nothing and can be undone. Run `git merge --ff-only {default_branch}` without asking, and report in one line that the branch was fast-forwarded by `behind` commits, followed by the [commit list](#commit-list). When the fast-forward fails, act on the result as in the next case.
|
|
24
|
+
|
|
25
|
+
**`behind` above 0 otherwise.** Report the gap and the [commit list](#commit-list), and ask how to proceed before the work starts, as a numbered gradient menu:
|
|
26
|
+
|
|
27
|
+
1. Bring the base in: by rebase onto `{default_branch}`, or by merging `{default_branch}` into the branch when `pushed` is true, because rebasing pushed commits would then need a force-push.
|
|
28
|
+
2. Proceed against the current base.
|
|
29
|
+
|
|
30
|
+
Recommend the first unless none of the gained commits touches the work. When `clean` is false, say that the tree has uncommitted changes, and do not run a git operation that would touch them before the developer answers.
|
|
31
|
+
|
|
32
|
+
## Commit list
|
|
33
|
+
|
|
34
|
+
Name each gained commit by its short SHA and subject. When paths were passed, name only the commits whose `touchesWork` is true, and state how many others the default branch gained; when none touches the work, say so. When paths were not passed, name the first 10 commits of `gained`, which is ordered newest first, and state the count of the rest.
|
|
35
|
+
|
|
36
|
+
The calling skill states what follows the report.
|
|
@@ -76,9 +76,9 @@ entries:
|
|
|
76
76
|
|
|
77
77
|
The payload is YAML rather than a surface template because `overrides` and `entries` nest, and a template renders one flat line. Nesting also leaves room for the block to gain structured keys, such as a grammar version or a ticket reference. Its inverse is a YAML parse rather than a compiled pattern, so this pair needs none of the round-trip verification required by the title grammar.
|
|
78
78
|
|
|
79
|
-
**The scalars precede `entries
|
|
79
|
+
**The scalars precede `entries`** so that the bulky list does not separate the title from the overrides.
|
|
80
80
|
|
|
81
|
-
**The block records the change entries as data**, which is how a reader downstream of the merge gets them without parsing them back out of the rendered `## Details` prose. The change summary's `changes` frontmatter field is a different list: It
|
|
81
|
+
**The block records the change entries as data**, which is how a reader downstream of the merge gets them without parsing them back out of the rendered `## Details` prose. The change summary's `changes` frontmatter field is a different list: It contains the commit entries, which record what the branch's commits declared.
|
|
82
82
|
|
|
83
83
|
**The block is the body's last element.** A reader takes the last `change-record` fence in the body, and the merge body that `resolve-merge` composes from the pull request excludes every block.
|
|
84
84
|
|
|
@@ -49,7 +49,7 @@ Each consuming skill defines which complexity levels qualify for its "simple eno
|
|
|
49
49
|
| `design-and-plan` / `plan` handoff pass | 1–2 | Skip the handoff pass; the session reports the skip in one line that names the level, and saves the artifacts |
|
|
50
50
|
| `next-steps-after-plan` | 1–2 | Recommend "Implement". When a review pass would catch nothing meaningful (e.g., a typo or unused-import removal), note on the option that the review can be skipped at `implement-plan`'s closing menu. |
|
|
51
51
|
| `implement-plan` closing menu | 1–2 | Recommend "Create PR without review"; the realized diff is trivial enough that a review pass would catch nothing meaningful |
|
|
52
|
-
| `
|
|
52
|
+
| `review-branch` closing menu | n/a | Trivial findings usually name a single change, for which the skill recommends "Implement directly and commit"; the recommendation depends on the finding's shape rather than on the level. |
|
|
53
53
|
|
|
54
54
|
When characteristics span two levels, prefer the higher level.
|
|
55
55
|
|
|
@@ -8,7 +8,7 @@ Design options have two kinds of properties.
|
|
|
8
8
|
|
|
9
9
|
**Correctness** (what makes the design right):
|
|
10
10
|
|
|
11
|
-
- Behavioral correctness: Does it produce the right results across the cases that matter?
|
|
11
|
+
- Behavioral correctness: Does it produce the right results across the cases that matter? The project's declared stage sets which cases matter; see [project stage](project-stage.md).
|
|
12
12
|
- API quality: Clear contracts, expressive interfaces, sensible boundaries
|
|
13
13
|
- Architectural soundness: Modularity, separation of concerns, single responsibility, composability, SOLID
|
|
14
14
|
- Testability: The design can be verified in isolation
|
|
@@ -25,7 +25,7 @@ Rank options on correctness. Convenience is secondary: a tiebreaker among correc
|
|
|
25
25
|
|
|
26
26
|
## Why
|
|
27
27
|
|
|
28
|
-
Correctness determines what it costs to live with the system over its remaining life. A clean design can be evolved; a wrong one accumulates patches around its wrongness. Convenience
|
|
28
|
+
Correctness determines what it costs to live with the system over its remaining life. A clean design can be evolved; a wrong one accumulates patches around its wrongness. Convenience saves effort only once, at the moment of change.
|
|
29
29
|
|
|
30
30
|
## Before / after
|
|
31
31
|
|
|
@@ -63,13 +63,24 @@ The factual lists about each option are similar; the **ranking** flips because t
|
|
|
63
63
|
|
|
64
64
|
When designing a change, ask: _How would we have written this if the new behavior had been there from the start?_ Aim the design at that target.
|
|
65
65
|
|
|
66
|
-
|
|
66
|
+
Four patterns signal a design that hasn't reached it:
|
|
67
67
|
|
|
68
68
|
- **Workarounds**: Changing surrounding code to accommodate a fix instead of changing the code that's wrong.
|
|
69
69
|
- **Carve-outs**: Special cases or conditional branches that exist because the change couldn't be integrated cleanly, not because the cases are genuinely distinct.
|
|
70
70
|
- **Bolt-ons**: New modules or extension points appended alongside existing structure when the existing structure should have evolved to absorb the change.
|
|
71
|
+
- **Hand-offs**: Steps that a person performs on each machine or environment because the design did not give the agent a way to apply the change there. See [who applies the change](#who-applies-the-change).
|
|
71
72
|
|
|
72
|
-
A fresh codebase wouldn't have these shapes; their presence means the change was attached to the system rather than integrated into it. Reaching the target may require touching code outside the ticket's literal
|
|
73
|
+
A fresh codebase wouldn't have these shapes; their presence means the change was attached to the system rather than integrated into it. Reaching the target may require touching code outside the ticket's literal scope: renaming, restructuring, generalizing. That cost is real but bounded; the cost of keeping a poorly integrated change compounds.
|
|
74
|
+
|
|
75
|
+
## Who applies the change
|
|
76
|
+
|
|
77
|
+
The developer's manual steps are a cost of the design, counted across the session rather than per turn: Every command that a person runs on a machine, and every result that they paste back, is a step that the design failed to script. Rank a design that the agent applies and verifies itself above one that needs a person to act on each machine, whatever the convenience properties say. A step that a person must run on each machine is a defect of the design: Raise it at design time, and never ship it as README steps, written after the merge, for a person to follow.
|
|
78
|
+
|
|
79
|
+
When the design cannot remove the step, shape it on this ladder, and stop at the first rung that works:
|
|
80
|
+
|
|
81
|
+
1. Reach the machine through the access that its own tooling already uses, such as `ssh`, and apply the step there. When this rung needs a credential or a grant, ask for it once, naming the command that runs once it arrives.
|
|
82
|
+
2. Route the step through provisioning that the machine already runs, such as the ensure scripts of its configuration repository, so that the agent commits the change and the machine applies it on its next run.
|
|
83
|
+
3. Leave one script per machine, run once, that checks its own result and prints only the facts that the agent needs. The agent writes and commits the script and keeps every other part, including the records of what was done.
|
|
73
84
|
|
|
74
85
|
## Reconciliation
|
|
75
86
|
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
# Project stage
|
|
2
|
+
|
|
3
|
+
A project declares its stage in its own `.agents/preferences.yaml`, under `project`, and the session-context manifest reports each value as `project_maturity`, `project_sensitivity`, and `project_audience`, `null` when the project does not declare it. The global preferences file never supplies a stage, because a stage describes one repo.
|
|
4
|
+
|
|
5
|
+
## Values
|
|
6
|
+
|
|
7
|
+
| Key | Value | Meaning |
|
|
8
|
+
| ------------- | -------------- | -------------------------------------------------------------------------------- |
|
|
9
|
+
| `maturity` | `hobby` | Built for the owner's own use or learning; breakage costs only the owner's time. |
|
|
10
|
+
| | `early` | In use by others, but the shape is still changing; downtime is tolerated. |
|
|
11
|
+
| | `production` | Others depend on it; downtime and data loss have real costs. |
|
|
12
|
+
| `sensitivity` | `low` | Nothing that would harm anyone if published. |
|
|
13
|
+
| | `personal` | Personal data about the owner or identifiable individuals. |
|
|
14
|
+
| | `confidential` | Secrets, credentials, or data that a third party is obliged to protect. |
|
|
15
|
+
| `audience` | `owner` | Only the repo's owner uses it. |
|
|
16
|
+
| | `team` | A known, bounded group uses it. |
|
|
17
|
+
| | `public` | Anyone who can reach it uses it. |
|
|
18
|
+
|
|
19
|
+
## What each value implies
|
|
20
|
+
|
|
21
|
+
- **Security.** `owner` with `low` sensitivity needs only what keeps the owner's own credentials out of the repository; access control beyond the host's own login is machinery without an asset to protect. `personal` data warrants access limited to the people that it concerns. Authentication with several factors, rate limits, and origin checks are needed for `public` users or `confidential` data.
|
|
22
|
+
- **Availability.** `hobby` tolerates a service that runs only while the owner works, such as a local process or a database on the owner's machine. `early` tolerates downtime and manual recovery. Hosted, always-available infrastructure and backups are needed for `production`.
|
|
23
|
+
- **Infrastructure.** Choose the least infrastructure on which the project runs at its declared stage: a file before a database, a local process before a hosted service, one environment before several.
|
|
24
|
+
|
|
25
|
+
## Rules
|
|
26
|
+
|
|
27
|
+
- **The declared values are premises.** Design for the stage that the project declares, not for the stage that a general-purpose system would assume. A design that serves requirements beyond the declared stage is wrong for this project, however sound it would be elsewhere.
|
|
28
|
+
- **Default to the least machinery that works for the declared stage.** Read [design priorities](design-priorities.md) against the stage: Behavioral correctness covers the cases that matter at that stage.
|
|
29
|
+
- **Escalate only for a named asset or need.** Add security, availability, or infrastructure beyond what the stage implies only when the design names what it protects or serves, such as "the tokens table holds the owner's API keys". State the asset or need in the ticket.
|
|
30
|
+
- **Make added hardening switchable.** A safeguard added beyond the stage, such as an origin check or a rate limit, is switched by configuration, so that a preview deployment or a local run can work without it.
|
|
31
|
+
- **Ask for an undeclared value; never infer it.** An undeclared value is a preference for which the agent holds no evidence, so it is in the gated class: Ask the developer rather than infer enterprise requirements from silence. Once the developer answers, declare the value in the project's `.agents/preferences.yaml` and run `node {harness_home_dir}/scripts/validate-preferences.mjs` on the edited file, so that the question is asked once.
|
|
32
|
+
- **Record the premises.** State each value that decided a security, availability, or infrastructure question where the work records its decisions: in a ticket's `## Context`, one sentence per premise naming the value and the decision that it settled, and in a product's design doc.
|
|
@@ -8,21 +8,23 @@ The render contract comes first; the doctrine behind it follows. Skills that ask
|
|
|
8
8
|
|
|
9
9
|
## Why the gate comes first
|
|
10
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
|
|
11
|
+
Asking is not a neutral act. It is cheap for the agent (it discharges responsibility for the call, rules out being wrong, and takes one paragraph) and expensive twice over: The developer must switch context 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
12
|
|
|
13
|
-
The gate reads the markers rather than asking for judgment, because a
|
|
13
|
+
The gate reads the markers rather than asking for judgment, because a step that says to ask overrides a judgment gate: 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
14
|
|
|
15
|
-
|
|
15
|
+
The leader check is not only for the gate. A gated decision renders its menu whatever the markers say, so a check read as deciding whether a menu renders looks pointless there and is skipped. The marker still does its other job: It tells the developer how much deliberation the ask needs. A leader marked ■■□ above a disqualified alternative reads as a close call, and the developer must re-derive the analysis to find out that the alternative was never viable before approving. An honest ■■■ lets them approve at a glance. A cost that disqualifies an alternative often follows from the constraints or the acceptance criteria of the work at hand rather than from the option itself, which is why the check searches each alternative for such a cost before marking.
|
|
16
16
|
|
|
17
|
-
A
|
|
17
|
+
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 had the diff, the commits, the taxonomy, and the test that decides the type; the developer had 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 is published.
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
A wrong-but-stated recommendation is cheaper to correct than a decision handed back: Correcting one takes a word; answering one takes an evaluation and a wait. The record keeps the developer's veto and makes it cheaper to use. They read the record 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.
|
|
20
|
+
|
|
21
|
+
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 have 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
22
|
|
|
21
23
|
## Why a manufactured bullet costs more than none
|
|
22
24
|
|
|
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
|
|
25
|
+
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 reader spends that attention before discovering that the con is worthless. That makes it waste rather than merely noise.
|
|
24
26
|
|
|
25
|
-
The
|
|
27
|
+
The menu's existence also depends on the con: 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
28
|
|
|
27
29
|
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
30
|
|
|
@@ -11,7 +11,7 @@ By default, fold into the current change the work that the ticket didn't name (a
|
|
|
11
11
|
|
|
12
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
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
|
|
14
|
+
**Authority.** The agent recommends the disposition of discovered work and builds on the recommendation; the developer vetoes. A fold-in is provisional, and the agent reports it at the ticket checkpoint with its reason. Because a spin-off creates remote state, the agent asks before creating the ticket. Never declare work "out of scope" as settled fact, and never drop discovered work without reporting it.
|
|
15
15
|
|
|
16
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
17
|
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
# Spike conventions
|
|
2
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.
|
|
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, and the [closing post](#closing-post) that ends every spike.
|
|
4
|
+
|
|
5
|
+
The ticket is the record of a spike, and the findings artifact is its log: The artifact holds the full findings and the evidence, and the ticket holds what the spike concluded. See [Purpose](artifact-conventions.md#purpose) for the artifact directory's role.
|
|
4
6
|
|
|
5
7
|
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
8
|
|
|
@@ -37,12 +39,12 @@ The concision and content-placement doctrines for feature tickets and plans appl
|
|
|
37
39
|
|
|
38
40
|
- [ ] {A decision that the findings must make possible.}
|
|
39
41
|
|
|
40
|
-
Deliverable: a findings & recommendation artifact.
|
|
42
|
+
Deliverable: a findings & recommendation artifact, and the closing post on this ticket.
|
|
41
43
|
```
|
|
42
44
|
|
|
43
45
|
`Context` and `Scope` are opt-in: Include either only when it adds signal on which the reader must act.
|
|
44
46
|
|
|
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).
|
|
47
|
+
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), and the [closing post](#closing-post) on the ticket.
|
|
46
48
|
|
|
47
49
|
## Spike plan template
|
|
48
50
|
|
|
@@ -59,7 +61,7 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
|
|
|
59
61
|
|
|
60
62
|
## Decisions taken
|
|
61
63
|
|
|
62
|
-
- {A decision that the agent took without asking, with its one-line reason
|
|
64
|
+
- {🔲 while it awaits the checkpoint} {A decision that the agent took without asking, with its one-line reason.}
|
|
63
65
|
|
|
64
66
|
## Timebox
|
|
65
67
|
|
|
@@ -79,10 +81,23 @@ Differences from the feature ticket: `Question` replaces `Problem`; `Timebox` is
|
|
|
79
81
|
|
|
80
82
|
## Deliverable
|
|
81
83
|
|
|
82
|
-
{The findings & recommendation artifact
|
|
84
|
+
{The findings & recommendation artifact (the answers reached, a recommendation, and residual unknowns), and the closing post on the ticket, offered at the closing checkpoint and made on consent, per `spike-conventions.md` § Closing post.}
|
|
83
85
|
```
|
|
84
86
|
|
|
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.
|
|
87
|
+
Differences from the feature plan: Investigation steps, each framed by the question that it probes, replace tasks with create/modify/test file lists; `Timebox` is first-class; `Deliverable` replaces `Verification`, since a spike produces findings rather than verifiable behavior, and it names the [closing post](#closing-post); a step does not have a test or documentation criterion.
|
|
88
|
+
|
|
89
|
+
## Closing post
|
|
90
|
+
|
|
91
|
+
The agent that ends a spike posts its conclusion on the ticket as a comment. The post contains:
|
|
92
|
+
|
|
93
|
+
- The answer to each of the ticket's questions to answer.
|
|
94
|
+
- The recommendation on each of the ticket's decisions to enable.
|
|
95
|
+
- The counts and the proposed groupings, when the spike produced them.
|
|
96
|
+
- Links to the published page, when the spike published one, and to the findings artifact, with the artifact's path written `~/`-relative, so that the post does not publish a home-directory path.
|
|
97
|
+
|
|
98
|
+
Offer the post as an item in the closing action-items block, show its body, and post it only on consent: It is a remote write, and the developer is the one who can tell whether a finding is fit for the ticket's tracker. When the session does not have a ticket, do not offer it.
|
|
99
|
+
|
|
100
|
+
Pass the body through a file, per [gh body file](ticket-source-resolution.md#gh-body-file). Before posting, read the ticket's comments, and skip the post when a comment already opens with the post's first line, so that a rerun does not post it twice.
|
|
86
101
|
|
|
87
102
|
## Aligning a spike
|
|
88
103
|
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
# Ticket evaluation
|
|
2
2
|
|
|
3
|
-
A ticket
|
|
3
|
+
A ticket is a request, report, or suggestion, not a contract. Treat its content as unsourced, whichever account created the ticket, until you trace it to a source. 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
4
|
|
|
5
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
6
|
|
|
7
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:
|
|
8
|
+
- **Is the scope right?** Look for related instances of the same defect class, neighboring code paths, or assumptions that don't hold beyond the ticket's frame. Scope can grow, not only shrink: By default, the agent folds work required by the problem into the current change rather than deferring it; see [scope-and-deferral](./scope-and-deferral.md). Scope can also be too large: When the ticket contains two or more pieces that can each be merged and verified on their own, raise the split before design begins, while the cut still requires an edit rather than a rewrite of the ticket, new children, a re-cut plan, and work already committed against it.
|
|
9
9
|
- **Is the proposed solution sound?** A ticket may include a recommended fix that solves the symptom but not the cause, or that fixes the cause less well than an alternative. Apply the [design priorities](./design-priorities.md) criteria: A convenient-but-wrong fix is unsound, even if it matches surrounding code.
|
|
10
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
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.
|
|
@@ -75,7 +75,15 @@ Skills may request a subset of these fields. The `updatedAt` field is needed by
|
|
|
75
75
|
|
|
76
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
77
|
|
|
78
|
-
**Preferred: `acli`.**
|
|
78
|
+
**Preferred: `acli`.** `acli` reads from whichever site it is signed in to, and a ticket on another site fails with the same error as a missing one. Before the first `acli` call, compare its active site with the ticket's host, taken from the ticket URL, or from `ticket_base_url` when the ticket URL is not known:
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
node {harness_home_dir}/scripts/manage-jira-ticket.mjs check-site --target {ticket URL or ticket_base_url}
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
The helper prints `{"activeSite": ..., "targetSite": ..., "match": ...}` and exits non-zero unless the two match. On a mismatch, read the ticket through another client below; a non-zero exit without JSON means that `acli` is unavailable. When neither URL is known, skip the check and read through `acli` as below.
|
|
85
|
+
|
|
86
|
+
Read the ticket body with the default view, which renders the description as text.
|
|
79
87
|
|
|
80
88
|
```
|
|
81
89
|
acli jira workitem view {key}
|
|
@@ -90,9 +98,31 @@ When a skill needs structured metadata, such as the `updated` timestamp for a st
|
|
|
90
98
|
- **Takes an issue URL**: Pass the ticket URL. Prefer this shape when both are connected, since it does not need site resolution.
|
|
91
99
|
- **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
100
|
|
|
93
|
-
**
|
|
101
|
+
**A client that the machine adds.** {skill?:update-jira-ticket} lists any Jira client that this machine adds to the cascade, with the sites that it can access and its rank. Read through it as its entry states.
|
|
102
|
+
|
|
103
|
+
**Last resort.** When no client can read the ticket and `check-site` reported a mismatch, report the wrong site rather than a missing ticket: Repeat the helper's stderr line, which names both sites and the `acli jira auth switch` command. Never run that command, because the active site is shared by every session on the machine. When no client 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.
|
|
104
|
+
|
|
105
|
+
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)). A site mismatch does not invalidate the stored URL, because it does not show that the ticket is missing.
|
|
106
|
+
|
|
107
|
+
## Open blockers
|
|
108
|
+
|
|
109
|
+
A ticket's open blockers are the tickets recorded natively as blocking it that are not yet done. Read them each time a skill resolves the ticket, even when the ticket is already in context, because a blocker can close or appear during a session.
|
|
94
110
|
|
|
95
|
-
|
|
111
|
+
**GitHub.** A blocker is open while its `state` is `OPEN`, so one closed as not planned counts as resolved. A blocker can be in another repository:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
gh issue view {number} --json blockedBy --jq '.blockedBy.nodes[] | select(.state == "OPEN") | [.url, .title] | @tsv'
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Name a blocker `#N` when its URL has the same `owner/repo` as the ticket's, and `owner/repo#N` otherwise.
|
|
118
|
+
|
|
119
|
+
**Jira.** Read the links through the Jira clients that [platform-specific fetch](#platform-specific-fetch) ranks, after the same site check: `acli jira workitem view {key} --json --fields issuelinks`, or a connected read tool asked for the `issuelinks` field. A blocker is a link whose `type.name` is `Blocks`, or whose `type.inward` reads `is blocked by`, and that has an `inwardIssue`. It is open while `inwardIssue.fields.status.statusCategory.key` is not `done`. Name it by its key and `fields.summary`.
|
|
120
|
+
|
|
121
|
+
**A file.** A ticket artifact copies a remote ticket, so a ticket that resolved from a file is checked against the remote ticket that its frontmatter `ticket_ref` names, resolved per [shorthand reference resolution](#shorthand-reference-resolution). A file without a `ticket_ref` is not checked.
|
|
122
|
+
|
|
123
|
+
**Other sources.** A ticket that resolved from plain text or from another platform is not checked, and the skill says nothing about blockers. Because a project hosted on Bitbucket keeps its tickets in Jira, its tickets are checked as Jira tickets.
|
|
124
|
+
|
|
125
|
+
**Report.** When the ticket has open blockers, report them in one line, each by reference and title: `⚠️ {ticket_ref} is blocked by {blocker_ref} ({title}), …`. When it has none, report nothing. When the read fails or no client can make it, report in one line that the blocker check did not run, and why; never report the ticket as unblocked. The calling skill states what follows the report.
|
|
96
126
|
|
|
97
127
|
## Platform-specific write
|
|
98
128
|
|
|
@@ -116,6 +146,8 @@ gh issue edit {number} --body-file "$body_path"
|
|
|
116
146
|
|
|
117
147
|
Update through {skill?:update-jira-ticket}, which states the tool-shape branch and bundles the pre-flight checker that its HTML surface needs.
|
|
118
148
|
|
|
149
|
+
<!-- include: ../_partials/jira-task-list-flattening.md / -->
|
|
150
|
+
|
|
119
151
|
`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
152
|
|
|
121
153
|
### Other platforms
|
|
@@ -142,6 +174,7 @@ After resolution, store the following metadata for use by the calling skill:
|
|
|
142
174
|
- **Issue number**: The numeric identifier, if applicable
|
|
143
175
|
- **Last-updated date**: The ticket's last-modified timestamp, if available from the platform
|
|
144
176
|
- **Ticket content**: The title, body, labels, and any other retrieved fields
|
|
177
|
+
- **Open blockers**: For a skill that checks them, each open blocker's reference and title, read per [Open blockers](#open-blockers)
|
|
145
178
|
- **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
179
|
|
|
147
180
|
<!-- include: ../_partials/gh-body-file.md / -->
|