@skitterbyte/skitterspec-jira 2.1.0 → 2.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/MIGRATION.md +42 -0
- package/assets/core/jira.config.md +2 -0
- package/assets/rules/spec-planning.md +91 -13
- package/assets/skills/spec/SKILL.md +70 -18
- package/assets/skills/spec-bug/SKILL.md +36 -0
- package/assets/skills/spec-complete/SKILL.md +39 -0
- package/assets/skills/spec-hotfix/SKILL.md +25 -0
- package/assets/skills/spec-incident/SKILL.md +164 -0
- package/assets/skills/spec-init/SKILL.md +2 -1
- package/package.json +1 -1
- package/src/cli.js +1 -1
- package/src/env/resolve.js +5 -4
- package/src/vendor/jira/api.js +58 -2
- package/src/vendor/jira/cli-sync.js +176 -13
- package/src/vendor/jira/config.js +6 -3
- package/src/vendor/provider-kit/src/config.js +44 -0
- package/src/vendor/sync-core/index.js +4 -1
- package/src/vendor/sync-core/src/normalize.js +111 -18
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,47 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## `issue` and `incident` spec kinds, per-type states, incident log (additive — nothing breaks)
|
|
4
|
+
|
|
5
|
+
Specs can now be **issues** (`issue-` prefix — non-code work done as recorded
|
|
6
|
+
manual steps) and **incidents** (`incident-` prefix, captured live by the new
|
|
7
|
+
`/spec-incident` skill; `/spec-complete` ends one by writing `incident-log.md`
|
|
8
|
+
and posting it onto the tracker item as a comment, via the new
|
|
9
|
+
`spec-sync comment <spec> --file <f>` verb). A lifecycle bucket can map to a
|
|
10
|
+
different state per work item type (`statesByType` on Azure Boards and Jira)
|
|
11
|
+
or per spec kind (`statesByKind` on GitHub and Linear), both top-level beside
|
|
12
|
+
`states`, with `null` meaning "send no state" — and the pre-write check now
|
|
13
|
+
validates each type's effective states against **that type's own** list, so a
|
|
14
|
+
state only one type lacks refuses before anything is written. On Azure and
|
|
15
|
+
Jira, `spec-sync states --json` now prints a per-type map
|
|
16
|
+
(`{ "<type>": [names] }`); a flat array from an older file is still accepted
|
|
17
|
+
and checked as the union. A fix spec can carry
|
|
18
|
+
`> **Incident:** incident-<name>` (linked as related on push) and
|
|
19
|
+
`> **Severity:**` (`1 - Critical` … `4 - Low`). Configs without any of the new
|
|
20
|
+
keys behave exactly as before, and `skitterspec update` ships the new skill
|
|
21
|
+
and rules.
|
|
22
|
+
|
|
23
|
+
Consumer config, by provider:
|
|
24
|
+
|
|
25
|
+
- **Azure Boards** —
|
|
26
|
+
`azure.workItemTypeByKind: { "issue": "Issue", "incident": "Incident" }`,
|
|
27
|
+
plus
|
|
28
|
+
`statesByType: { "Issue": { "complete": "Closed" }, "Incident": { "backlog": null, "complete": "Closed" } }`.
|
|
29
|
+
Severity writes the built-in `Microsoft.VSTS.Common.Severity` — nothing to
|
|
30
|
+
configure; a type without the field skips it with a note. The incident link
|
|
31
|
+
is `System.LinkTypes.Related`.
|
|
32
|
+
- **GitHub** — `github.labelsByKind` accepts the new kinds;
|
|
33
|
+
`statesByKind: { "issue": { "complete": "Done" } }` routes a kind's board
|
|
34
|
+
Status (`null` sends none); `github.severityLabels: { "2": "sev-high" }`
|
|
35
|
+
maps the header's leading digit to a label. The incident rides in the
|
|
36
|
+
generated body as a `Related incident: #N` line.
|
|
37
|
+
- **Jira** — `jira.issueTypeByKind` accepts the new kinds; `statesByType`
|
|
38
|
+
keys by issue type; `jira.severityField` names the field to write (e.g.
|
|
39
|
+
`customfield_10900`). The incident link is a `Relates` issue link, added
|
|
40
|
+
once.
|
|
41
|
+
- **Linear** — `linear.labelsByKind` accepts the new kinds; `statesByKind`
|
|
42
|
+
keys by spec kind; `linear.severityLabels` maps digits to team labels. The
|
|
43
|
+
incident link is a related-issue relation.
|
|
44
|
+
|
|
3
45
|
## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
|
|
4
46
|
|
|
5
47
|
Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
|
|
@@ -13,6 +13,8 @@ NAMES — never a credential. Credentials live in the user-level store
|
|
|
13
13
|
| `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
|
|
14
14
|
| `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
|
|
15
15
|
| `states.<bucket>` | The Jira STATUS name for each lifecycle bucket. Must match the project's workflow statuses exactly; moves are applied by workflow transition, and an unreachable status refuses loudly. `cancelled` defaults to `Done` because default Jira workflows carry no Cancelled status. Pick work statuses, not pipeline stages — see **Choosing your status map** below. | see example |
|
|
16
|
+
| `statesByType.<issue type>.<bucket>` | Per-TYPE override laid over `states` — statuses belong to the type's workflow, so `{ "Service Request": { "complete": "Closed" } }` completes that type differently. A bucket set to `null` sends no status; validation checks each type against its own workflow. | `{}` |
|
|
17
|
+
| `jira.severityField` | The field id the `Severity:` header is written to (e.g. `customfield_10900`). Empty, the header stays repo-only. A fix spec's `Incident:` header adds a `Relates` issue link to its incident, once. | `""` |
|
|
16
18
|
| `auth.emailEnv` / `auth.tokenEnv` | Env-var NAMES for the email + API-token pair (basic auth). | `JIRA_EMAIL` / `JIRA_API_TOKEN` |
|
|
17
19
|
| `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
|
|
18
20
|
| `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
|
|
@@ -7,9 +7,10 @@ and lifecycle stay consistent. Each sets a status on the spec header
|
|
|
7
7
|
|
|
8
8
|
| Skill | Purpose | Status | Folder |
|
|
9
9
|
|-------|---------|--------|--------|
|
|
10
|
-
| `/spec` | (Feature/Chore) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
|
|
10
|
+
| `/spec` | (Feature/Chore/Issue) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
|
|
11
11
|
| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
|
|
12
12
|
| `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
|
|
13
|
+
| `/spec-incident` | (Incident) Capture a live outage as a record written during it — grill, write in flight, fixes as separate linked specs | `In Progress` | `specs/in-progress/` |
|
|
13
14
|
| `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
|
|
14
15
|
| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
|
|
15
16
|
| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
|
|
@@ -587,26 +588,34 @@ none of them describes.
|
|
|
587
588
|
- **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
|
|
588
589
|
(architecture, code style, testing, database, etc.) rather than restating them.
|
|
589
590
|
|
|
590
|
-
## Spec types — Feature, Chore, Bug, Hotfix
|
|
591
|
+
## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident
|
|
591
592
|
|
|
592
|
-
Every spec is one of
|
|
593
|
+
Every spec is one of six types, recorded **both** in the header and the filename:
|
|
593
594
|
|
|
594
595
|
- **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
|
|
595
|
-
`> **Type:** Bug`,
|
|
596
|
+
`> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`, or
|
|
597
|
+
`> **Type:** Incident` (authoritative, greppable:
|
|
596
598
|
`grep -rl 'Type:.*Hotfix' specs/`).
|
|
597
599
|
- **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
|
|
598
|
-
`bug-<name>` for bugs, `hotfix-<name>` for
|
|
600
|
+
`issue-<name>` for issues, `bug-<name>` for bugs, `hotfix-<name>` for
|
|
601
|
+
hotfixes, `incident-<name>` for incidents (visible in listings;
|
|
599
602
|
glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
|
|
600
603
|
|
|
601
|
-
A **Chore** is work no end user sees — tooling, CI, dependency bumps,
|
|
602
|
-
refactors.
|
|
603
|
-
|
|
604
|
-
|
|
604
|
+
A **Chore** is code work no end user sees — tooling, CI, dependency bumps,
|
|
605
|
+
internal refactors. An **Issue** is work with **no code change at all** —
|
|
606
|
+
in-app configuration, a data fix, a support task — written as a spec of manual
|
|
607
|
+
steps so there is a record and a history; everything user-facing that changes
|
|
608
|
+
code is a feature. There is no
|
|
609
|
+
separate entry skill for either — `/spec` **proposes** feature, chore or issue
|
|
610
|
+
from what the
|
|
605
611
|
grilling defined, with a one-line reason, and the user confirms. A chore
|
|
606
612
|
defaults its `Gating:` to `none: not user-facing` (where gating is configured),
|
|
607
613
|
and its commits default to `chore`/`refactor`/`ci` types with **no**
|
|
608
614
|
`Release-Note:` footer — a chore is by definition not user-visible, so it has
|
|
609
|
-
no release note to write.
|
|
615
|
+
no release note to write. An issue defaults its `Gating:` to `none: no code`
|
|
616
|
+
and its commits to `docs` with no `Release-Note:`, and it closes when the spec
|
|
617
|
+
completes — nothing is released. Feature specs keep `feat`; bug specs keep
|
|
618
|
+
`fix`.
|
|
610
619
|
Where a ticketing provider maps kinds to tracker types (e.g. Azure's
|
|
611
620
|
`workItemTypeByKind`), the chore mapping is what keeps tooling work off the
|
|
612
621
|
customer-facing release ladder.
|
|
@@ -616,14 +625,75 @@ carries an extra `> **Base version:** <tag>` header, forks its worktree from tha
|
|
|
616
625
|
tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
|
|
617
626
|
fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
|
|
618
627
|
|
|
619
|
-
|
|
628
|
+
An **Incident** is an outage or degradation of a live service, captured by
|
|
629
|
+
**`/spec-incident`** during the outage, so it starts straight in
|
|
630
|
+
`specs/in-progress/`. It is a record, not delivery work: its fixes are
|
|
631
|
+
separate hotfix, bug, chore or issue specs, each carrying
|
|
632
|
+
`> **Incident:** incident-<name>` so the push links them, and they are never
|
|
633
|
+
its phases. It carries `> **Severity:**` (Azure's literal values,
|
|
634
|
+
`1 - Critical` … `4 - Low`) and a `## Timeline` appended to as the incident
|
|
635
|
+
unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
|
|
636
|
+
onto the tracker item as a comment.
|
|
637
|
+
|
|
638
|
+
### Kind routing — any door, the right spec
|
|
639
|
+
|
|
640
|
+
`/spec` is the default door, so the kind of work someone describes does not
|
|
641
|
+
always match the skill they typed — especially for someone new, for whom
|
|
642
|
+
"spec it" is the reflex. Every entry skill therefore
|
|
643
|
+
**watches its grill for the signals that mark the other kinds**, and proposes a
|
|
644
|
+
hand-off the moment one appears — never at the end of a grill already shaping
|
|
645
|
+
the wrong spec:
|
|
646
|
+
|
|
647
|
+
| In | Watches for | Hands to |
|
|
648
|
+
|----|-------------|----------|
|
|
649
|
+
| `/spec` | defect · defect on a released version · live outage | `/spec-bug` · `/spec-hotfix` · `/spec-incident` |
|
|
650
|
+
| `/spec-bug` | on a released version · live outage · not a defect | `/spec-hotfix` · `/spec-incident` · `/spec` |
|
|
651
|
+
| `/spec-hotfix` | live outage · not on a released version · not a defect | `/spec-incident` · `/spec-bug` · `/spec` |
|
|
652
|
+
| `/spec-incident` | no live outage to record | defect → `/spec-bug` (on a released version → `/spec-hotfix`), else `/spec` |
|
|
653
|
+
|
|
654
|
+
Feature, chore and issue all route to `/spec` — one door for the three kinds it
|
|
655
|
+
writes, where its kind proposal picks between them. Example signals, weighed in
|
|
656
|
+
context rather than matched as keywords: a **defect** is behaviour differing
|
|
657
|
+
from intended — "it's broken", a failing flow, a stack trace of a failure;
|
|
658
|
+
**on a released version** is that defect where what is deployed is named — "in
|
|
659
|
+
prod", "since v2.1"; a **live outage** is a service down or degraded
|
|
660
|
+
**right now**, users affected as we speak; **not a defect** is an ask for new or
|
|
661
|
+
changed behaviour rather than for restoring intended behaviour.
|
|
662
|
+
|
|
663
|
+
Three rules, the same in every skill:
|
|
664
|
+
|
|
665
|
+
- **Always confirm; never silently switch.** Name the signal in the user's own
|
|
666
|
+
words and propose the destination with a one-line reason; the user confirms
|
|
667
|
+
or declines. A decline ends the matter — the grill carries on where it was,
|
|
668
|
+
and the same signal is not raised again. A signal is a question, never a
|
|
669
|
+
verdict: a pasted stack trace in "handle this error nicely" is a feature
|
|
670
|
+
request, not a bug report.
|
|
671
|
+
- **Precedence: incident > hotfix > bug.** One description can carry several
|
|
672
|
+
signals; propose the most specific destination — the same reasoning the
|
|
673
|
+
intake label routing documents for hotfix-over-bug.
|
|
674
|
+
- **Hand off in-session, carrying the context.** On a confirmed switch the
|
|
675
|
+
current skill invokes the destination skill directly and seeds it with
|
|
676
|
+
everything the grilling has already established — symptom, version, impact,
|
|
677
|
+
repro material, decisions so far — so the destination grills only what it
|
|
678
|
+
still needs ("seed, don't skip, the grill", the principle issue adoption
|
|
679
|
+
already uses). Stop-and-retype is the **label** routing's shape, and right
|
|
680
|
+
there because it fires before any grilling; mid-grill it would throw away
|
|
681
|
+
the answers already given.
|
|
682
|
+
|
|
683
|
+
This is judgment, not configuration: the signals are examples, there is no
|
|
684
|
+
list to maintain, and nothing here reads a label. A ticketing provider's
|
|
685
|
+
intake label routing (`intake.bugLabels` / `intake.hotfixLabels`) is a
|
|
686
|
+
separate, earlier check and is unchanged by this.
|
|
687
|
+
|
|
688
|
+
All six types share the same lifecycle folders below — type is orthogonal to
|
|
620
689
|
status.
|
|
621
690
|
|
|
622
691
|
## Header fields & State log (audit trail)
|
|
623
692
|
|
|
624
693
|
Every spec header carries:
|
|
625
694
|
|
|
626
|
-
- `> **Name:**` — the spec's folder name
|
|
695
|
+
- `> **Name:**` — the spec's folder name
|
|
696
|
+
(`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-<kebab-name>`).
|
|
627
697
|
It's the handle you pass to `/spec-start` and the other lifecycle skills, surfaced
|
|
628
698
|
in the header so it's copy-pasteable without digging for the folder name.
|
|
629
699
|
- `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
|
|
@@ -634,6 +704,14 @@ Every spec header carries:
|
|
|
634
704
|
**only when `specs/.core/gating.config.json` exists**: a flag name, or
|
|
635
705
|
`none: <one-line reason>`. Absent entirely in a project that has not adopted
|
|
636
706
|
gating.
|
|
707
|
+
- `> **Severity:**` — on bug, hotfix and incident specs, optional except where
|
|
708
|
+
`/spec-incident` grills it: Azure's literal values
|
|
709
|
+
(`1 - Critical` … `4 - Low`). The push writes it where the provider has a
|
|
710
|
+
home for it; absent, nothing is sent.
|
|
711
|
+
- `> **Incident:**` — on a spec that is a **fix** for an open incident:
|
|
712
|
+
`incident-<name>`. The push links the two as related on the tracker
|
|
713
|
+
(one-way; the repo owns the link), and `/spec-complete` on the incident
|
|
714
|
+
counts the spec among its fixes. Absent on everything else.
|
|
637
715
|
|
|
638
716
|
Every spec also has a **State log** table — the audit trail of folder/status
|
|
639
717
|
transitions. Each lifecycle skill appends exactly one row when it changes state:
|
|
@@ -668,7 +746,7 @@ When asked for a plan, implementation strategy, or feature breakdown:
|
|
|
668
746
|
|
|
669
747
|
```
|
|
670
748
|
specs/backlog/ Ready (or Draft) specs (/spec)
|
|
671
|
-
specs/in-progress/ under active implementation (/spec-start, /spec-bug)
|
|
749
|
+
specs/in-progress/ under active implementation (/spec-start, /spec-bug, /spec-incident)
|
|
672
750
|
specs/complete/ finished (/spec-complete)
|
|
673
751
|
specs/cancelled/ abandoned, with a reason on the header (/spec-cancel)
|
|
674
752
|
specs/.core/ project rules — ALWAYS APPLY, never moved
|
|
@@ -188,31 +188,78 @@ not write the spec until this is resolved.
|
|
|
188
188
|
Stop grilling when there are no unresolved branches that would change the spec.
|
|
189
189
|
Briefly play back the agreed understanding before writing.
|
|
190
190
|
|
|
191
|
-
###
|
|
192
|
-
|
|
193
|
-
|
|
191
|
+
### Watch for the other doors — bug, hotfix, incident
|
|
192
|
+
|
|
193
|
+
`/spec` is the default door, so work that belongs to another skill arrives here
|
|
194
|
+
described in the user's own words — no issue, no labels for Phase 0 to route
|
|
195
|
+
on. While grilling, watch for the signals that mark the other kinds and raise
|
|
196
|
+
the hand-off **the moment one appears**, not at the end of the grill: for a
|
|
197
|
+
live outage especially, finishing a feature grill first is actively harmful,
|
|
198
|
+
because `/spec-incident` exists to be written *during* the outage.
|
|
199
|
+
|
|
200
|
+
- **Defect** — behaviour differing from intended ("it's broken", a failing
|
|
201
|
+
flow, a stack trace of a failure) → propose **`/spec-bug`**.
|
|
202
|
+
- **Defect on a released version** — the defect is on what is deployed ("in
|
|
203
|
+
prod", "since v2.1") → propose **`/spec-hotfix`**.
|
|
204
|
+
- **Live outage** — a service down or degraded **right now**, users affected
|
|
205
|
+
as we speak → propose **`/spec-incident`**.
|
|
206
|
+
|
|
207
|
+
**Always confirm; never silently switch.** Name the signal in the user's own
|
|
208
|
+
words, propose the destination with a one-line reason, and let them decide. A
|
|
209
|
+
decline carries the grill on where it was, and the same signal is not raised
|
|
210
|
+
again. A signal is a question, never a verdict: a pasted stack trace in
|
|
211
|
+
"handle this error nicely" is a feature request. When one description carries
|
|
212
|
+
several signals, propose the most specific destination —
|
|
213
|
+
**incident > hotfix > bug**.
|
|
214
|
+
|
|
215
|
+
**On a confirmed switch, hand off in-session and carry the context.** Invoke
|
|
216
|
+
the destination skill directly and seed it with everything the grilling has
|
|
217
|
+
already established — symptom, version, impact, repro material, decisions so
|
|
218
|
+
far — so it grills only what it still needs ("seed, don't skip, the grill",
|
|
219
|
+
exactly as issue adoption does). Do not stop and tell the user to retype: that
|
|
220
|
+
shape belongs to Phase 0's label routing, which fires before any grilling has
|
|
221
|
+
happened and so has nothing to lose. The full routing matrix lives in
|
|
222
|
+
`.claude/rules/spec-planning.md`.
|
|
223
|
+
|
|
224
|
+
### Propose the kind — feature, chore or issue
|
|
225
|
+
|
|
226
|
+
This skill writes three kinds of spec, and
|
|
194
227
|
**you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
|
|
195
228
|
The
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
229
|
+
lines that decide it: a **chore** is code work no end user sees — tooling, CI,
|
|
230
|
+
dependency bumps, internal refactors. An **issue** is work with
|
|
231
|
+
**no code change at all** — in-app configuration, a data fix, a support task —
|
|
232
|
+
written as a spec of manual steps so there is a record and a history.
|
|
233
|
+
Everything user-facing that changes code is a **feature**. So the proposal
|
|
234
|
+
reads like *"no user-visible surface → chore"*, *"no code change, manual
|
|
235
|
+
steps → issue"* or *"adds an endpoint users call → feature"*.
|
|
200
236
|
|
|
201
237
|
The kind is recorded twice, and both follow from the answer: the folder prefix
|
|
202
|
-
(`feat-` / `chore-`) and the `> **Type:**` header
|
|
238
|
+
(`feat-` / `chore-` / `issue-`) and the `> **Type:**` header
|
|
239
|
+
(`Feature` / `Chore` / `Issue`). A chore
|
|
203
240
|
also defaults its `Gating:` to `none: not user-facing` (only when gating is
|
|
204
241
|
configured — offer the default, let the user override it like any other
|
|
205
242
|
answer), and its commits default to `chore`/`refactor`/`ci` types with no
|
|
206
|
-
`Release-Note:` (see `.claude/rules/spec-planning.md`).
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
243
|
+
`Release-Note:` (see `.claude/rules/spec-planning.md`). An issue defaults its
|
|
244
|
+
`Gating:` to `none: no code`, and its commits to `docs` with no
|
|
245
|
+
`Release-Note:` — its phases are manual steps, not code, though `/spec-start`
|
|
246
|
+
still gives it a worktree, because the document needs one and the history is
|
|
247
|
+
the point.
|
|
248
|
+
|
|
249
|
+
There is no `/spec-chore` or `/spec-issue` and none should be added: one entry
|
|
250
|
+
point, one grill, and the kind is an output of understanding the work rather
|
|
251
|
+
than a door the user must pick before describing it. The kinds with their own
|
|
252
|
+
doors — bug, hotfix, and the **incident**, an outage or degradation of a live
|
|
253
|
+
service that needs a different grill and starts mid-flight — are the watch's
|
|
254
|
+
business above: when the grilling uncovers one, hand off to **`/spec-bug`**,
|
|
255
|
+
**`/spec-hotfix`** or **`/spec-incident`** rather than writing it here, and it
|
|
256
|
+
is never too late to propose that — reaching this proposal with the signal
|
|
257
|
+
unraised is a missed watch, not a reason to write the wrong kind.
|
|
211
258
|
|
|
212
259
|
## Phase B — write the spec
|
|
213
260
|
|
|
214
|
-
This skill is for **features and
|
|
215
|
-
(test-first, red→green)
|
|
261
|
+
This skill is for **features, chores and issues**. For bugs, use `/spec-bug`
|
|
262
|
+
(test-first, red→green); for a live outage, `/spec-incident`.
|
|
216
263
|
|
|
217
264
|
### Write it in its own worktree
|
|
218
265
|
|
|
@@ -280,7 +327,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
|
|
|
280
327
|
notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
|
|
281
328
|
into `00-overview.md`. This keeps each phase easy to dive into on its own.
|
|
282
329
|
- Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
|
|
283
|
-
a feature, `chore-` for a chore (the bug counterpart
|
|
330
|
+
a feature, `chore-` for a chore, `issue-` for an issue (the bug counterpart
|
|
331
|
+
uses `bug-`, the incident one `incident-`).
|
|
284
332
|
|
|
285
333
|
Use this template (keep it **as concise as possible** — no filler, no restating
|
|
286
334
|
the codebase, link rather than duplicate):
|
|
@@ -288,8 +336,8 @@ the codebase, link rather than duplicate):
|
|
|
288
336
|
```markdown
|
|
289
337
|
# <Feature title>
|
|
290
338
|
|
|
291
|
-
> **Type:** <Feature or
|
|
292
|
-
> **Name:** <feat- or
|
|
339
|
+
> **Type:** <Feature, Chore or Issue — the kind proposed after Phase A>
|
|
340
|
+
> **Name:** <feat-, chore- or issue-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
|
|
293
341
|
> **Status:** Ready — not started
|
|
294
342
|
> **Author:** <git user.name — `git config user.name`>
|
|
295
343
|
> **Developer:** —
|
|
@@ -297,6 +345,10 @@ the codebase, link rather than duplicate):
|
|
|
297
345
|
> **Area:** <comma-separated files/modules this touches>
|
|
298
346
|
> **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
|
|
299
347
|
> services; only acted on when isolation is enabled — see Phase A item 9>
|
|
348
|
+
> **Incident:** <incident-<name> — only when this spec is a fix for an open
|
|
349
|
+
> incident spec; the next push links the two as related on the tracker, and
|
|
350
|
+
> `/spec-complete` on the incident counts this spec among its fixes. Omit the
|
|
351
|
+
> line entirely otherwise>
|
|
300
352
|
> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
|
|
301
353
|
> is configured; omit the line entirely otherwise. A chore defaults to
|
|
302
354
|
> "none: not user-facing". An empty value or a bare
|
|
@@ -150,6 +150,38 @@ Bugs are concrete — confirm, don't over-grill. Establish:
|
|
|
150
150
|
against the broken one (the bug usually lives in the differential). Do NOT
|
|
151
151
|
patch a symptom before you understand the cause.
|
|
152
152
|
|
|
153
|
+
### Watch for the other doors — hotfix, incident, or not a bug at all
|
|
154
|
+
|
|
155
|
+
The investigation above is where mis-entry shows, so watch it for the signals
|
|
156
|
+
that mark the other kinds and raise the hand-off the moment one appears —
|
|
157
|
+
before the failing test is written, while nothing is on disk
|
|
158
|
+
(`.claude/rules/spec-planning.md` carries the full routing matrix):
|
|
159
|
+
|
|
160
|
+
- **On a released version** — the defect is on what is deployed ("in prod",
|
|
161
|
+
"since v2.1") → propose **`/spec-hotfix`**. This is the escalation that must
|
|
162
|
+
not be missed: a fix built here lands on `main` and never reaches the
|
|
163
|
+
running version.
|
|
164
|
+
- **Live outage** — a service down or degraded **right now** → propose
|
|
165
|
+
**`/spec-incident`**; the record comes first, and the fix returns as a
|
|
166
|
+
linked spec.
|
|
167
|
+
- **Not a defect** — the ask is new or changed behaviour, not restoring
|
|
168
|
+
intended behaviour → propose **`/spec`**, whose kind proposal picks feature,
|
|
169
|
+
chore or issue from there.
|
|
170
|
+
|
|
171
|
+
**Always confirm; never silently switch** — name the signal in the user's own
|
|
172
|
+
words with a one-line reason, and a decline carries this skill on where it
|
|
173
|
+
was, the same signal not raised again. When several signals appear at once,
|
|
174
|
+
propose the most specific destination — incident over hotfix.
|
|
175
|
+
**On a confirmed switch, hand off in-session and carry the context**: invoke
|
|
176
|
+
the destination skill directly and seed it with what §1 established — symptom,
|
|
177
|
+
repro, root-cause notes, any version named — so it grills only what it still
|
|
178
|
+
needs.
|
|
179
|
+
|
|
180
|
+
**Once the failing test exists, the repro is evidence, not a question to re-litigate**
|
|
181
|
+
— but evidence can still escalate: a red test that also fails at
|
|
182
|
+
the released tag is the hotfix signal with proof attached, and the hand-off
|
|
183
|
+
carries the failing test across.
|
|
184
|
+
|
|
153
185
|
## 2. Isolate the fix in a worktree — when isolation is enabled
|
|
154
186
|
|
|
155
187
|
**Only when per-spec isolation is enabled** (`specs/.core/env.config.json`
|
|
@@ -269,6 +301,10 @@ because work is already underway. Keep it lean:
|
|
|
269
301
|
> **Developer:** <git user.name — you, since you're fixing it now>
|
|
270
302
|
> **Raised:** <YYYY-MM-DD (today)>
|
|
271
303
|
> **Area:** <files/modules>
|
|
304
|
+
> **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
|
|
305
|
+
> the push writes it where the provider has a home for it. Omit otherwise>
|
|
306
|
+
> **Incident:** <incident-<name> — only when this bug is a fix for an open
|
|
307
|
+
> incident spec; the next push links the two as related. Omit otherwise>
|
|
272
308
|
> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
|
|
273
309
|
> is configured; omit the line entirely otherwise>
|
|
274
310
|
|
|
@@ -42,6 +42,45 @@ Before marking complete, confirm the work is actually finished:
|
|
|
42
42
|
is its own, and step 4 commits that.
|
|
43
43
|
|
|
44
44
|
|
|
45
|
+
### An incident spec — the log, and the open-fix check
|
|
46
|
+
|
|
47
|
+
**Only for `Type: Incident` specs** (folder prefix `incident-`); every other
|
|
48
|
+
kind skips this in silence.
|
|
49
|
+
|
|
50
|
+
1. **Check for open linked fixes.** Grep `specs/backlog/` and
|
|
51
|
+
`specs/in-progress/` for specs carrying `> **Incident:** <this spec's name>`.
|
|
52
|
+
Any hit is a fix still open: **refuse**, naming each one, and offer to
|
|
53
|
+
complete anyway with it listed as outstanding in the log — the operator
|
|
54
|
+
answers; record the choice in the spec's Changelog either way.
|
|
55
|
+
BLIND SPOT, named: a fix spec authored but not yet landed on the base branch
|
|
56
|
+
is invisible to this grep — acceptable, because `/spec`'s committing
|
|
57
|
+
verdicts land authored specs on the base
|
|
58
|
+
(`.claude/rules/negative-checks.md`).
|
|
59
|
+
2. **Write `incident-log.md`** into the spec folder — the stakeholder- and
|
|
60
|
+
support-facing record, built from the spec and its linked fixes:
|
|
61
|
+
summary · severity · timeline (started, detected, mitigated, resolved) ·
|
|
62
|
+
impact (who, what, for how long) · root cause · the fixes (each linked
|
|
63
|
+
spec, its ticket, and the release it shipped in — `spec-sync released`
|
|
64
|
+
answers that where a provider is installed; a fix completed but not yet
|
|
65
|
+
released is listed as such) · what went well and what didn't · follow-ups,
|
|
66
|
+
each offered as a `/spec` on the spot.
|
|
67
|
+
3. **Push the log onto the incident item as a comment** (only when a provider
|
|
68
|
+
is installed and the spec is linked):
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
skitterspec spec-sync comment <spec> --file specs/in-progress/<spec>/incident-log.md
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
A comment, deliberately: the item's description is generated from the spec,
|
|
75
|
+
so a log written there would be clobbered by the next push — comments are
|
|
76
|
+
the one surface one-way sync never touches. The command exits 0 on every
|
|
77
|
+
cannot-tell (unlinked, offline, no credentials) and says so; relay the line
|
|
78
|
+
and finish either way — the log in the repo is the record.
|
|
79
|
+
|
|
80
|
+
Completion then proceeds as normal: the per-type state map decides what the
|
|
81
|
+
tracker is sent (an Incident completes to whatever `statesByType` names for
|
|
82
|
+
it), and steps 3–7 below are unchanged.
|
|
83
|
+
|
|
45
84
|
### Release gating (only when configured)
|
|
46
85
|
|
|
47
86
|
**Only when `specs/.core/gating.config.json` exists.** Run
|
|
@@ -177,6 +177,27 @@ Hotfixes are concrete — confirm, don't over-grill. Establish:
|
|
|
177
177
|
- **Root cause:** read the code **at the base tag** and trace it to `file:line`.
|
|
178
178
|
The fix belongs on the tag's line, so reason about that code, not `main`'s.
|
|
179
179
|
|
|
180
|
+
### Watch for the other doors — incident, bug, or not a defect
|
|
181
|
+
|
|
182
|
+
This is the most specific defect door, so most mis-entries route *down*
|
|
183
|
+
(`.claude/rules/spec-planning.md` carries the full routing matrix):
|
|
184
|
+
|
|
185
|
+
- **Live outage** — the released version is not just wrong but down or
|
|
186
|
+
degraded **right now** → propose **`/spec-incident`**; the record comes
|
|
187
|
+
first, and the fix returns here as a linked hotfix spec.
|
|
188
|
+
- **Not on a released version** — §1 cannot name a deployed tag the defect is
|
|
189
|
+
on (it exists only on `main`, or prod runs something newer that is fine) →
|
|
190
|
+
propose **`/spec-bug`**; a hotfix branch for something `main` can carry is
|
|
191
|
+
waste, not safety.
|
|
192
|
+
- **Not a defect** — the ask is new or changed behaviour, not restoring
|
|
193
|
+
intended behaviour → propose **`/spec`**.
|
|
194
|
+
|
|
195
|
+
**Always confirm; never silently switch** — name the signal in the user's own
|
|
196
|
+
words with a one-line reason; a decline carries this skill on where it was.
|
|
197
|
+
**On a confirmed switch, hand off in-session and carry the context**
|
|
198
|
+
established so far — the symptom, the repro, any version discussion — so the
|
|
199
|
+
destination grills only what it still needs.
|
|
200
|
+
|
|
180
201
|
## 3. Provision the worktree from the tag, then write in it
|
|
181
202
|
|
|
182
203
|
**Provision before you write, not after.** §1 settled the tag and the name and
|
|
@@ -293,6 +314,10 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
|
|
|
293
314
|
> **Base version:** <tag prod is running, e.g. v33.16.4>
|
|
294
315
|
> **Raised:** <YYYY-MM-DD (today)>
|
|
295
316
|
> **Area:** <files/modules>
|
|
317
|
+
> **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
|
|
318
|
+
> the push writes it where the provider has a home for it. Omit otherwise>
|
|
319
|
+
> **Incident:** <incident-<name> — only when this hotfix is a fix for an open
|
|
320
|
+
> incident spec; the next push links the two as related. Omit otherwise>
|
|
296
321
|
> **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
|
|
297
322
|
> when release gating is configured, and overridable — see below>
|
|
298
323
|
|
|
@@ -0,0 +1,164 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-incident
|
|
3
|
+
description: Capture a live incident — an outage or degradation of a running service — as an Incident-type spec written during the outage. Grills for what is down, since when, who is affected, severity and what was tried, then writes the spec straight into specs/in-progress/ with a Timeline appended to as it unfolds. Fixes are separate linked specs, never phases. Use when the user says "/spec-incident", "we have an outage", "prod is down and I need an incident record", or asks to track an incident.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-incident — capture a live incident
|
|
7
|
+
|
|
8
|
+
> Stay silent while this runs — speak only to ask something you cannot answer
|
|
9
|
+
> yourself, or to report a failure at the moment it happens. Read
|
|
10
|
+
> `.claude/rules/spec-reports.md` before reporting; it defines the block this
|
|
11
|
+
> skill ends with.
|
|
12
|
+
|
|
13
|
+
An **incident** is an outage or degradation of a live service. It is not
|
|
14
|
+
delivery work: the fixes are separate hotfix, bug, chore or issue specs, each
|
|
15
|
+
linked back to it, and this spec is the **record** — what happened, when, to
|
|
16
|
+
whom, and what was done. It is written **during** the outage, so it starts in
|
|
17
|
+
`specs/in-progress/`, there is no backlog stop and no review page to wait on:
|
|
18
|
+
speed matters, and the record is reviewed at completion, when
|
|
19
|
+
`/spec-complete` writes the incident log from it.
|
|
20
|
+
|
|
21
|
+
**This skill is not the response.** Mitigating comes first, and nothing here
|
|
22
|
+
blocks it — the grill is short, the spec is small, and everything else is
|
|
23
|
+
appended as it happens.
|
|
24
|
+
|
|
25
|
+
## 1. Grill — short, and only what the record needs
|
|
26
|
+
|
|
27
|
+
Ask for exactly these, batched, with nothing speculative:
|
|
28
|
+
|
|
29
|
+
1. **What is down or degraded** — the service, and how it is failing.
|
|
30
|
+
2. **Since when** — first report, and detection time where they differ.
|
|
31
|
+
3. **Who is affected** — which users or systems, and how badly.
|
|
32
|
+
4. **Severity** — Azure's literal values: `1 - Critical`, `2 - High`,
|
|
33
|
+
`3 - Medium`, `4 - Low`. Propose one from the impact described; the user
|
|
34
|
+
confirms.
|
|
35
|
+
5. **What has been tried** — anything already attempted, and its effect.
|
|
36
|
+
|
|
37
|
+
A root cause is **not** grilled: nobody has it yet, and the Timeline is where
|
|
38
|
+
the investigation lands as it happens.
|
|
39
|
+
|
|
40
|
+
### No live outage to record — route to the right door
|
|
41
|
+
|
|
42
|
+
This is the costliest door to enter wrongly — no backlog stop, no review page,
|
|
43
|
+
straight into `specs/in-progress/` — so the grill's own answers are also its
|
|
44
|
+
exit. When items 1 and 2 establish there is **no outage to record** — nothing
|
|
45
|
+
is down or degraded, it never was live, or it is a risk rather than an event —
|
|
46
|
+
propose the right door instead of writing an incident
|
|
47
|
+
(`.claude/rules/spec-planning.md` carries the full routing matrix):
|
|
48
|
+
|
|
49
|
+
- a **defect** → **`/spec-bug`**, or **`/spec-hotfix`** when it is on a
|
|
50
|
+
released version;
|
|
51
|
+
- anything else → **`/spec`**, whose kind proposal picks feature, chore or
|
|
52
|
+
issue from there.
|
|
53
|
+
|
|
54
|
+
**A past outage someone wants a record of stays an incident**: "it is over" is
|
|
55
|
+
not "it never happened" — the signal is *no outage to record*, not *no outage
|
|
56
|
+
now*. This check is the grill's existing questions read honestly, never an
|
|
57
|
+
extra round trip, and the hand-off contract is the same as everywhere else:
|
|
58
|
+
confirm first, naming the signal in the user's own words; a decline carries
|
|
59
|
+
this skill on; on a confirmed switch invoke the destination skill in-session,
|
|
60
|
+
seeded with everything already established.
|
|
61
|
+
|
|
62
|
+
## 2. Write it, in flight
|
|
63
|
+
|
|
64
|
+
Pick a short kebab name prefixed `incident-` (e.g. `incident-api-outage`).
|
|
65
|
+
|
|
66
|
+
**With per-spec isolation** (`specs/.core/env.config.json` present), provision
|
|
67
|
+
before writing, exactly as `/spec` Phase B does: run
|
|
68
|
+
`skitterspec spec-env up <name> --docs`, run the commands it prints, `cd` into
|
|
69
|
+
the worktree, and confirm with a bare `skitterspec spec-env resolve` naming
|
|
70
|
+
this spec. Without isolation, write where you stand.
|
|
71
|
+
|
|
72
|
+
The spec is a folder in **`specs/in-progress/`** — never backlog — with
|
|
73
|
+
`00-overview.md` and one phase file:
|
|
74
|
+
|
|
75
|
+
```markdown
|
|
76
|
+
# Incident: <short title>
|
|
77
|
+
|
|
78
|
+
> **Type:** Incident
|
|
79
|
+
> **Name:** incident-<kebab-name>
|
|
80
|
+
> **Status:** In Progress — live (started <YYYY-MM-DD>)
|
|
81
|
+
> **Author:** <git user.name>
|
|
82
|
+
> **Developer:** <git user.name — whoever is running the incident>
|
|
83
|
+
> **Raised:** <YYYY-MM-DD (today)>
|
|
84
|
+
> **Severity:** <1 - Critical … 4 - Low>
|
|
85
|
+
> **Gating:** <pre-filled "none: incident record, no code"; only when release
|
|
86
|
+
> gating is configured, omit otherwise>
|
|
87
|
+
|
|
88
|
+
## Impact
|
|
89
|
+
|
|
90
|
+
<who is affected, what is failing, since when — from the grill>
|
|
91
|
+
|
|
92
|
+
## Timeline
|
|
93
|
+
|
|
94
|
+
- <YYYY-MM-DD HH:MM> — <first report / detected / what was tried / what changed>
|
|
95
|
+
|
|
96
|
+
## Fixes
|
|
97
|
+
|
|
98
|
+
<one line per fix spec as they are opened — see step 4. "None yet" until then.>
|
|
99
|
+
|
|
100
|
+
## State log
|
|
101
|
+
|
|
102
|
+
| Date | Status | Folder | By |
|
|
103
|
+
|------|--------|--------|----|
|
|
104
|
+
| <YYYY-MM-DD> | In Progress | in-progress | <author> |
|
|
105
|
+
|
|
106
|
+
## Changelog
|
|
107
|
+
|
|
108
|
+
- <YYYY-MM-DD> — Incident captured.
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
The phase file `01-response.md` holds the response as tasks — mitigate,
|
|
112
|
+
diagnose, open fix specs, verify recovery — manual steps, not code. Commits in
|
|
113
|
+
this spec default to `docs` with no `Release-Note:`.
|
|
114
|
+
|
|
115
|
+
## 3. Link to the tracker (only if a provider is installed)
|
|
116
|
+
|
|
117
|
+
Run the provider's linking push exactly as `/spec` Phase E describes — the
|
|
118
|
+
spec is already in `in-progress`, so the mint lands in the incident's
|
|
119
|
+
in-flight state (with Azure's `statesByType`, an Incident is created Active
|
|
120
|
+
and never sent New; the `Severity:` header is written where the provider has a
|
|
121
|
+
home for it). No provider, or an unreachable tracker, is one line and the
|
|
122
|
+
record stands in the repo.
|
|
123
|
+
|
|
124
|
+
## 4. Run the incident from the spec
|
|
125
|
+
|
|
126
|
+
- **Append to the Timeline** as things happen — dated lines, cheap and often.
|
|
127
|
+
- **Fixes are separate specs**: a prod-version fix is `/spec-hotfix`, a
|
|
128
|
+
mainline defect `/spec-bug`, tooling `/spec` (chore), manual remediation
|
|
129
|
+
`/spec` (issue). Each fix spec carries `> **Incident:** incident-<name>` in
|
|
130
|
+
its header, which the next push turns into a related link on the tracker.
|
|
131
|
+
They are never phases of this spec.
|
|
132
|
+
- **Mid-incident board states stay manual**: skitterspec writes states at
|
|
133
|
+
lifecycle moves only, so moving the ticket to a Mitigated-style state during
|
|
134
|
+
the outage is done on the board, and the next push leaves it until the spec
|
|
135
|
+
itself moves.
|
|
136
|
+
|
|
137
|
+
## 5. End of the outage is not the end of the spec
|
|
138
|
+
|
|
139
|
+
When the service is recovered, say so in the Timeline and keep the spec in
|
|
140
|
+
flight until the record is complete — root cause written, fixes linked.
|
|
141
|
+
`/spec-complete` is the ending: it writes `incident-log.md` from this spec and
|
|
142
|
+
its linked fixes, refuses while a linked fix is still open (and offers to
|
|
143
|
+
complete anyway with it listed as outstanding), and pushes the log onto the
|
|
144
|
+
incident item as a comment.
|
|
145
|
+
|
|
146
|
+
## Report
|
|
147
|
+
|
|
148
|
+
End with the block defined in `.claude/rules/spec-reports.md`. That file
|
|
149
|
+
carries the shape; this section carries only what is specific here.
|
|
150
|
+
|
|
151
|
+
**Verdicts**
|
|
152
|
+
|
|
153
|
+
- `✅` — the incident spec is written, in flight, and (where a provider is
|
|
154
|
+
installed) linked.
|
|
155
|
+
- `⚠️` — written and in flight, with something worth knowing (a mint that
|
|
156
|
+
failed, a worktree that could not be provisioned so it was written in
|
|
157
|
+
place).
|
|
158
|
+
- `⏸` — the grill could not establish what is down, so nothing was written.
|
|
159
|
+
|
|
160
|
+
**Fields:** `Tracker` · `Branch` · `Spec` · `Built` · `Worktree` ·
|
|
161
|
+
`Follow-ups` · `Next`
|
|
162
|
+
|
|
163
|
+
`Next` is the response itself — the first task of `01-response.md` — never a
|
|
164
|
+
review page: nothing here waits on a verdict while a service is down.
|