skilldrop-cli 0.16.9 → 0.16.10
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/README.md +2 -2
- package/contracts/guide.schema.json +5 -1
- package/package.json +1 -1
- package/packs/career/loops/apply/LOOP.md +11 -11
- package/packs/career/loops/apply/evals/evals.json +2 -2
- package/packs/career/loops/apply/loop.json +2 -2
- package/packs/core/loops/ship-a-draft/LOOP.md +6 -6
- package/packs/core/loops/ship-a-draft/evals/evals.json +2 -2
- package/packs/core/loops/ship-a-draft/loop.json +1 -1
- package/packs/core/pack.json +1 -1
- package/packs/dev-team/loops/release/LOOP.md +15 -15
- package/packs/dev-team/loops/release/loop.json +3 -3
- package/packs/sre-oncall/loops/operate/LOOP.md +4 -4
- package/packs/sre-oncall/loops/operate/evals/evals.json +1 -1
- package/packs/sre-oncall/loops/operate/loop.json +1 -1
- package/packs/sre-oncall/pack.json +1 -1
package/README.md
CHANGED
|
@@ -55,14 +55,14 @@ In Claude Code you can use the plugin marketplace instead: run `/plugin marketpl
|
|
|
55
55
|
## How it works
|
|
56
56
|
|
|
57
57
|
- **A skill produces one file you own.** Each ships a quality bar, named anti-patterns and acceptance evals, so the output is an artifact, not a conversation. See [every skill, by category](guides/reference/skill-catalogue.md).
|
|
58
|
-
- **Loops order skills, and a gate decides when work moves on.** Five loops cover the lifecycle (`discover`, `design`, `build`, `release`, `operate`), plus the `ship-a-draft` wrapper for any document and `apply` for a job application. Each gate is a script, a review panel or a person, chosen by how expensive the mistake is to undo. See [the loops, stage by stage](guides/reference/loops.md) and [why loops](guides/explanation/loops.md).
|
|
58
|
+
- **Loops order skills, and a gate decides when work moves on.** Five loops cover the lifecycle (`discover`, `design`, `build`, `release`, `operate`), plus the `ship-a-draft` wrapper for any document and `apply` for a job application. Each gate is a script, a review panel or a person, chosen by how expensive the mistake is to undo. See [the operating model](guides/explanation/operating-model.md) for every stage and gate on one page, [the loops, stage by stage](guides/reference/loops.md), and [why loops](guides/explanation/loops.md).
|
|
59
59
|
- **Measured, not asserted.** `run_bench.py` runs each acceptance eval with the skill and without it, in a sandbox, and reports the lift, a blind preference from two judges, and the cost per run. The results are published whether or not they flatter the skills. See [how skills are checked](https://sananthanarayan.github.io/skilldrop/evals/) and [RFC-0040](docs/rfcs/0040-skill-benchmark.md).
|
|
60
60
|
- **Copy, never transform.** A skill is a plain `SKILL.md` folder in the [Agent Skills](https://agentskills.io) format, at `packs/<pack>/skills/<name>/`. What runs in your agent is byte-identical to what is reviewed here. There is no runtime, and the tooling has zero dependencies.
|
|
61
61
|
- **Updates keep your edits.** `npx skilldrop-cli update` replaces files you haven't touched. For any file you changed, it leaves the new version beside it as `<file>.upstream`. See [upgrade installed skills](guides/how-to/upgrade-skills.md).
|
|
62
62
|
|
|
63
63
|
## Go deeper
|
|
64
64
|
|
|
65
|
-
- **Use it:** [docs portal](https://sananthanarayan.github.io/skilldrop/docs/) · [a guide for every pack](guides/README.md#per-pack) · [install in any IDE](guides/how-to/install-per-ide.md) · [try skills in a repo you don't own](guides/how-to/install-per-ide.md#trying-skills-in-a-repo-you-dont-own) · [profiles](guides/how-to/profiles.md) · [hooks](guides/how-to/wire-a-hook.md)
|
|
65
|
+
- **Use it:** [the operating model](guides/explanation/operating-model.md) · [docs portal](https://sananthanarayan.github.io/skilldrop/docs/) · [a guide for every pack](guides/README.md#per-pack) · [install in any IDE](guides/how-to/install-per-ide.md) · [try skills in a repo you don't own](guides/how-to/install-per-ide.md#trying-skills-in-a-repo-you-dont-own) · [profiles](guides/how-to/profiles.md) · [hooks](guides/how-to/wire-a-hook.md)
|
|
66
66
|
- **Run it in CI:** [a skill on every pull request](guides/how-to/run-a-skill-in-ci.md) · [how skills are checked](https://sananthanarayan.github.io/skilldrop/evals/) · [benchmark skills yourself](guides/how-to/benchmark-skills.md) · [measure your loops](guides/how-to/measure-your-loops.md)
|
|
67
67
|
- **Roll it out:** [across your org, including an internal mirror](guides/how-to/enterprise-distribution.md) · [publish your own catalogue](guides/how-to/publish-a-catalogue.md) · [security and the OWASP Top 10s](guides/reference/owasp-mapping.md)
|
|
68
68
|
- **Reviewers:** three subagents that push back on generated work: `devils-advocate`, `security-reviewer` and `code-quality`. See [`agents/`](agents/README.md).
|
|
@@ -13,6 +13,10 @@
|
|
|
13
13
|
"enum": ["tutorial", "how-to", "reference", "explanation"],
|
|
14
14
|
"description": "tutorial = learning by doing. how-to = a task with a goal. reference = look it up. explanation = why it is this way. A page that cannot pick one is doing two jobs and should be split."
|
|
15
15
|
},
|
|
16
|
-
"status": { "enum": ["draft", "review", "stable", "deprecated"], "default": "stable" }
|
|
16
|
+
"status": { "enum": ["draft", "review", "stable", "deprecated"], "default": "stable" },
|
|
17
|
+
"stage": {
|
|
18
|
+
"enum": ["discover", "design", "build", "release", "operate"],
|
|
19
|
+
"description": "RFC-0044. The lifecycle stage a page belongs to, when it belongs to one. The docs sidebar groups staged pages under that stage, beside the stage's loop; a page that spans every stage, or none, leaves it out."
|
|
20
|
+
}
|
|
17
21
|
}
|
|
18
22
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "skilldrop-cli",
|
|
3
|
-
"version": "0.16.
|
|
3
|
+
"version": "0.16.10",
|
|
4
4
|
"description": "Portable AI-agent skills, measured against the agent without them. ADRs, PRDs, runbooks, decks and reviews, installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
|
|
5
5
|
"author": {
|
|
6
6
|
"name": "Sanjay Ananthanarayan",
|
|
@@ -14,18 +14,18 @@ can say what the resume shows, but only the candidate knows what is true and wha
|
|
|
14
14
|
|
|
15
15
|
| # | Stage | Type | Skills | Gate |
|
|
16
16
|
|---|---|---|---|---|
|
|
17
|
-
| 1 | `fit` | gate | [`job-fit-analysis`](../../skills/job-fit-analysis/SKILL.md) | **
|
|
17
|
+
| 1 | `fit` | gate | [`job-fit-analysis`](../../skills/job-fit-analysis/SKILL.md) | **G6** human |
|
|
18
18
|
| 2 | `tailor` | generate | [`resume-tailor`](../../skills/resume-tailor/SKILL.md) | — |
|
|
19
19
|
| 3 | `letter` | generate | [`cover-letter`](../../skills/cover-letter/SKILL.md) | — |
|
|
20
20
|
| 4 | `form` | generate | [`application-form-answers`](../../skills/application-form-answers/SKILL.md) | — |
|
|
21
|
-
| 5 | `confirm` | verify | [`output-hygiene`](../../../core/skills/output-hygiene/SKILL.md) | **G6** human |
|
|
21
|
+
| 5 | `confirm` | verify | [`output-hygiene`](../../../core/skills/output-hygiene/SKILL.md) | **G6.1** human |
|
|
22
22
|
|
|
23
23
|
## How to run this loop
|
|
24
24
|
|
|
25
25
|
1. **Check the fit and stop.** Run `job-fit-analysis` on the posting, the resume and any
|
|
26
26
|
other material of the candidate's: a LinkedIn summary, a portfolio, a project. Put its
|
|
27
27
|
verdict, what could get the application rejected and its questions to the candidate,
|
|
28
|
-
including whether anything outside the resume covers a gap, then wait at
|
|
28
|
+
including whether anything outside the resume covers a gap, then wait at G6.
|
|
29
29
|
- `PROCEED`: they are applying. Go on.
|
|
30
30
|
- `PROCEED WITH CONDITIONS`: they are applying and have answered the questions. Save
|
|
31
31
|
their answers to `notes.md`; from here on those answers are source material alongside
|
|
@@ -41,7 +41,7 @@ can say what the resume shows, but only the candidate knows what is true and wha
|
|
|
41
41
|
the documents, run `application-form-answers` with those questions and the tailored
|
|
42
42
|
resume. Skip this stage when there is no form.
|
|
43
43
|
5. **Clean the documents.** Run `output-hygiene` on the resume and the letter.
|
|
44
|
-
6. **Confirm at G6.** Show the candidate the documents with four short lists: what the
|
|
44
|
+
6. **Confirm at G6.1.** Show the candidate the documents with four short lists: what the
|
|
45
45
|
posting asks for that the documents do not claim; every fact added from outside the
|
|
46
46
|
resume and where it came from; every line cut from the resume; and the form questions
|
|
47
47
|
that are theirs alone to answer. Ask them to confirm every line is true. `NOT READY` returns to `tailor` with their
|
|
@@ -49,8 +49,8 @@ can say what the resume shows, but only the candidate knows what is true and wha
|
|
|
49
49
|
|
|
50
50
|
## Verdicts
|
|
51
51
|
|
|
52
|
-
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json).
|
|
53
|
-
`PROCEED`, `PROCEED WITH CONDITIONS`, `RECONSIDER` or `BLOCKED`. G6 emits `READY`,
|
|
52
|
+
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G6 emits
|
|
53
|
+
`PROCEED`, `PROCEED WITH CONDITIONS`, `RECONSIDER` or `BLOCKED`. G6.1 emits `READY`,
|
|
54
54
|
`NOT READY` or `BLOCKED`. `RECONSIDER` leaves the loop: the candidate's time goes to a
|
|
55
55
|
better posting.
|
|
56
56
|
|
|
@@ -64,7 +64,7 @@ produce documents carrying their name that they have not confirmed.
|
|
|
64
64
|
|
|
65
65
|
Name the missing skill and skilldrop as its source, do the minimal inline version of that
|
|
66
66
|
stage under the same rule (nothing the candidate didn't supply), and record that it ran
|
|
67
|
-
degraded. Never skip G6.
|
|
67
|
+
degraded. Never skip G6.1.
|
|
68
68
|
|
|
69
69
|
## Run log (opt-in)
|
|
70
70
|
|
|
@@ -73,7 +73,7 @@ gate's verdict, append one JSON line to that file. Nothing else is recorded, and
|
|
|
73
73
|
sent anywhere. When the variable isn't set, or you can't read it, skip this section.
|
|
74
74
|
|
|
75
75
|
```bash
|
|
76
|
-
printf '%s\n' '{"ts":"2026-10-05T14:03:00Z","loop":"apply","stage":"fit","gate":"
|
|
76
|
+
printf '%s\n' '{"ts":"2026-10-05T14:03:00Z","loop":"apply","stage":"fit","gate":"G6","verdict":"PROCEED","round":1}' >> "$SKILLDROP_LOOP_LOG"
|
|
77
77
|
```
|
|
78
78
|
|
|
79
79
|
Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
|
|
@@ -83,9 +83,9 @@ The log holds verdicts only: never the posting, the resume or the candidate's na
|
|
|
83
83
|
## Quality bar
|
|
84
84
|
|
|
85
85
|
- **The candidate decides to apply before anything is written.** A tailored resume for a job they would have skipped is wasted work.
|
|
86
|
-
- **Every claim in both documents traces to the resume or to something the candidate said.** Answers given at
|
|
86
|
+
- **Every claim in both documents traces to the resume or to something the candidate said.** Answers given at G6 are written to `notes.md`, so the trace exists.
|
|
87
87
|
- **The resume, the letter and the form agree.** Same titles, dates and numbers in all three.
|
|
88
|
-
- **The candidate confirms and sends.** G6 is their signature; the loop never submits an application.
|
|
88
|
+
- **The candidate confirms and sends.** G6.1 is their signature; the loop never submits an application.
|
|
89
89
|
|
|
90
90
|
## Anti-patterns to avoid
|
|
91
91
|
|
|
@@ -93,5 +93,5 @@ The log holds verdicts only: never the posting, the resume or the candidate's na
|
|
|
93
93
|
- ❌ **Treating a `Not shown` item as true** because the candidate proceeded. Only what they answered goes in.
|
|
94
94
|
- ❌ **Writing the letter from the original resume.** The letter follows the tailored one, or the two will disagree.
|
|
95
95
|
- ❌ **Answering a declaration on the form** for the candidate, or leaving out the list of what was added and cut.
|
|
96
|
-
- ❌ **Self-confirming at G6.** A clean claim check says the words are in the source; it cannot say they are true.
|
|
96
|
+
- ❌ **Self-confirming at G6.1.** A clean claim check says the words are in the source; it cannot say they are true.
|
|
97
97
|
- ❌ **Submitting the application.** Sending is the candidate's act.
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"assertions": [
|
|
8
8
|
"Starts with job-fit-analysis and delivers its verdict before any resume or letter is written",
|
|
9
9
|
"Names the unmet bachelor's degree as a screening requirement",
|
|
10
|
-
"Stops at
|
|
10
|
+
"Stops at G6 and asks the candidate whether to apply; does not tailor the resume in the same turn",
|
|
11
11
|
"Does not advise claiming the degree or adding any keyword the resume does not support"
|
|
12
12
|
]
|
|
13
13
|
},
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"The tailored resume includes Spanish and does not claim SAP",
|
|
20
20
|
"The cover letter is written after the tailored resume and uses the same titles, dates and numbers",
|
|
21
21
|
"Runs output-hygiene on both documents before the final gate",
|
|
22
|
-
"Stops at G6 and asks the candidate to confirm every line is true; does not submit or send anything",
|
|
22
|
+
"Stops at G6.1 and asks the candidate to confirm every line is true; does not submit or send anything",
|
|
23
23
|
"Lists what the posting asks for that neither document claims"
|
|
24
24
|
]
|
|
25
25
|
}
|
|
@@ -13,7 +13,7 @@
|
|
|
13
13
|
"intent": "Say honestly where the candidate stands against the posting, then let them decide whether this application is worth writing.",
|
|
14
14
|
"skills": ["job-fit-analysis"],
|
|
15
15
|
"gate": {
|
|
16
|
-
"id": "
|
|
16
|
+
"id": "G6",
|
|
17
17
|
"kind": "human",
|
|
18
18
|
"verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "RECONSIDER", "BLOCKED"]
|
|
19
19
|
}
|
|
@@ -42,7 +42,7 @@
|
|
|
42
42
|
"intent": "Strip what the machine left behind, then have the candidate confirm that every line in the documents is true and theirs, and that anything added from outside the resume is right.",
|
|
43
43
|
"skills": ["output-hygiene"],
|
|
44
44
|
"gate": {
|
|
45
|
-
"id": "G6",
|
|
45
|
+
"id": "G6.1",
|
|
46
46
|
"kind": "human",
|
|
47
47
|
"verdicts": ["READY", "NOT READY", "BLOCKED"],
|
|
48
48
|
"revise_to": "tailor"
|
|
@@ -16,7 +16,7 @@ check the argument and the surface after.
|
|
|
16
16
|
|---|---|---|---|---|
|
|
17
17
|
| 1 | `intake` | generate | [`brief-intake`](../../skills/brief-intake/SKILL.md) | — |
|
|
18
18
|
| 2 | `draft` | generate | any generator (`*`) | — |
|
|
19
|
-
| 3 | `critique` | verify | [`doc-critique`](../../skills/doc-critique/SKILL.md) | **
|
|
19
|
+
| 3 | `critique` | verify | [`doc-critique`](../../skills/doc-critique/SKILL.md) | **G5** review |
|
|
20
20
|
| 4 | `polish` | verify | [`output-hygiene`](../../skills/output-hygiene/SKILL.md) | — |
|
|
21
21
|
|
|
22
22
|
## How to run this wrapper
|
|
@@ -29,7 +29,7 @@ check the argument and the surface after.
|
|
|
29
29
|
chosen generator will refuse to start without. Resolve those before drafting.
|
|
30
30
|
3. **Draft.** Run the chosen generator on the brief. It is a normal skilldrop skill with its
|
|
31
31
|
own quality bar — this wrapper does not override it.
|
|
32
|
-
4. **Critique at
|
|
32
|
+
4. **Critique at G5.** Run `doc-critique`, which dispatches to the same rubric the generator
|
|
33
33
|
was held to. `MAJOR REWRITE` returns to `intake` (not to `draft` — a rewrite usually means
|
|
34
34
|
the input was wrong, not the prose). `WRONG ARTIFACT` leaves the wrapper entirely.
|
|
35
35
|
5. **Polish last.** Run `output-hygiene` only once the argument is settled. It is a surface
|
|
@@ -37,14 +37,14 @@ check the argument and the surface after.
|
|
|
37
37
|
|
|
38
38
|
## Verdicts
|
|
39
39
|
|
|
40
|
-
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json).
|
|
40
|
+
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G5 emits the critique
|
|
41
41
|
vocabulary. `SHIP WITH CHANGES` carries its changes forward to `polish`; it does not mean the
|
|
42
42
|
changes are optional.
|
|
43
43
|
|
|
44
44
|
## When a stage's skill is not installed
|
|
45
45
|
|
|
46
46
|
Name the missing skill and skilldrop as its source, do the minimal inline version of that
|
|
47
|
-
stage, and say the stage ran degraded. Do not skip
|
|
47
|
+
stage, and say the stage ran degraded. Do not skip G5 — an unreviewed artifact is the failure
|
|
48
48
|
mode this wrapper exists to prevent.
|
|
49
49
|
|
|
50
50
|
## Run log (opt-in)
|
|
@@ -54,7 +54,7 @@ gate's verdict, append one JSON line to that file. Nothing else is recorded, and
|
|
|
54
54
|
sent anywhere. When the variable isn't set, or you can't read it, skip this section.
|
|
55
55
|
|
|
56
56
|
```bash
|
|
57
|
-
printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"ship-a-draft","stage":"critique","gate":"
|
|
57
|
+
printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"ship-a-draft","stage":"critique","gate":"G5","verdict":"SHIP IT","round":1}' >> "$SKILLDROP_LOOP_LOG"
|
|
58
58
|
```
|
|
59
59
|
|
|
60
60
|
Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
|
|
@@ -71,7 +71,7 @@ which end in `BLOCKED`.
|
|
|
71
71
|
|
|
72
72
|
## Anti-patterns to avoid
|
|
73
73
|
|
|
74
|
-
- ❌ **Running `polish` as the whole review.** Clean prose with a broken argument still fails; that is what
|
|
74
|
+
- ❌ **Running `polish` as the whole review.** Clean prose with a broken argument still fails; that is what G5 is for.
|
|
75
75
|
- ❌ **Skipping `intake` because the input "is already structured."** A Slack thread that looks organized is still untagged — nobody downstream can tell what was inferred.
|
|
76
76
|
- ❌ **Looping `critique` → `draft` instead of `critique` → `intake`.** Re-drafting from the same incomplete brief reproduces the same gaps with new words.
|
|
77
77
|
- ❌ **Treating `WRONG ARTIFACT` as a severe `MAJOR REWRITE`.** It is a redirect: the user wanted a different document, and revising this one cannot get there.
|
|
@@ -7,7 +7,7 @@
|
|
|
7
7
|
"assertions": [
|
|
8
8
|
"Chooses the target generator (exec-summary) BEFORE running intake, because the brief is shaped for a target",
|
|
9
9
|
"Runs brief-intake and tags every field explicit / implied / inferred / missing",
|
|
10
|
-
"Runs doc-critique at
|
|
10
|
+
"Runs doc-critique at G5 against the same rubric the generator was held to",
|
|
11
11
|
"Runs output-hygiene last, only once the argument is settled",
|
|
12
12
|
"Reports what output-hygiene did not touch"
|
|
13
13
|
]
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
"id": "major-rewrite-returns-to-intake",
|
|
17
17
|
"prompt": "The critique on my draft came back MAJOR REWRITE. Continue the ship-a-draft wrapper.",
|
|
18
18
|
"assertions": [
|
|
19
|
-
"Routes back to `intake`, not to `draft`, because
|
|
19
|
+
"Routes back to `intake`, not to `draft`, because G5's revise_to names intake",
|
|
20
20
|
"Explains that re-drafting from the same incomplete brief reproduces the same gaps",
|
|
21
21
|
"Does not run output-hygiene on a draft that is about to be rewritten"
|
|
22
22
|
]
|
|
@@ -25,7 +25,7 @@
|
|
|
25
25
|
"intent": "Review the draft against the same rubric the generator was held to.",
|
|
26
26
|
"skills": ["doc-critique"],
|
|
27
27
|
"gate": {
|
|
28
|
-
"id": "
|
|
28
|
+
"id": "G5",
|
|
29
29
|
"kind": "review",
|
|
30
30
|
"verdicts": ["SHIP IT", "SHIP WITH CHANGES", "MAJOR REWRITE", "WRONG ARTIFACT", "BLOCKED"],
|
|
31
31
|
"revise_to": "intake"
|
package/packs/core/pack.json
CHANGED
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"skill": "doc-critique",
|
|
38
38
|
"you_do": "Hand over the draft you wrote from the brief, by hand or with any generator skill.",
|
|
39
39
|
"you_get": "A critique that opens with a verdict and lists findings as blocker, major, minor or nit, each pointing to the section and suggesting a fix.",
|
|
40
|
-
"decide": "Gate
|
|
40
|
+
"decide": "Gate G5: SHIP IT or SHIP WITH CHANGES moves on; MAJOR REWRITE sends you back to the brief; WRONG ARTIFACT means you need a different kind of document."
|
|
41
41
|
},
|
|
42
42
|
{
|
|
43
43
|
"skill": "output-hygiene",
|
|
@@ -15,9 +15,9 @@ being folded into either neighbour.
|
|
|
15
15
|
| # | Stage | Type | Skills | Gate |
|
|
16
16
|
|---|---|---|---|---|
|
|
17
17
|
| 1 | `plan` | generate | [`migration-plan`](../../skills/migration-plan/SKILL.md) | — |
|
|
18
|
-
| 2 | `ready` | verify | [`launch-readiness`](../../skills/launch-readiness/SKILL.md) | **
|
|
18
|
+
| 2 | `ready` | verify | [`launch-readiness`](../../skills/launch-readiness/SKILL.md) | **G3** review |
|
|
19
19
|
| 3 | `announce` | generate | [`release-notes`](../../skills/release-notes/SKILL.md) | — |
|
|
20
|
-
| 4 | `go` | gate | [`council-review`](../../../core/skills/council-review/SKILL.md) | **
|
|
20
|
+
| 4 | `go` | gate | [`council-review`](../../../core/skills/council-review/SKILL.md) | **G3.1** human |
|
|
21
21
|
|
|
22
22
|
## How to run this loop
|
|
23
23
|
|
|
@@ -25,34 +25,34 @@ being folded into either neighbour.
|
|
|
25
25
|
rollback for each one, and at most one named point of no return. For a code-only change
|
|
26
26
|
behind a flag, the plan can be short: the flag, the stages and how to turn it off. It still
|
|
27
27
|
has to exist.
|
|
28
|
-
2. **Judge readiness at
|
|
28
|
+
2. **Judge readiness at G3.** `launch-readiness` lists the change's own failure modes, then
|
|
29
29
|
checks rollback, detection, response, measured targets, data and privacy, comms and
|
|
30
30
|
exposure, each with evidence. `REVISE` returns to `plan`, and the report names which gap to
|
|
31
31
|
close and which skill closes it. A missing rollback is `BLOCKED` on its own.
|
|
32
32
|
3. **Announce only once it is ready.** `release-notes` drafts the customer-facing and
|
|
33
|
-
internal notes from the git range. Writing them before
|
|
33
|
+
internal notes from the git range. Writing them before G3 risks announcing a launch that
|
|
34
34
|
then does not happen.
|
|
35
|
-
4. **A human decides at
|
|
35
|
+
4. **A human decides at G3.1.** The release owner decides whether to ship *now*, given
|
|
36
36
|
timing, freeze windows and on-call coverage. When that decision is contested, use
|
|
37
37
|
`council-review`. `RECONSIDER` means it is ready but this is the wrong time, and the work
|
|
38
38
|
waits instead of going back to `plan`.
|
|
39
39
|
|
|
40
|
-
After `PROCEED`, the change is live and the work moves to `operate`. Gaps that
|
|
40
|
+
After `PROCEED`, the change is live and the work moves to `operate`. Gaps that G3 sent to
|
|
41
41
|
`observability-plan` or `runbook-generator` are the first things `operate` picks up.
|
|
42
42
|
|
|
43
43
|
## Verdicts
|
|
44
44
|
|
|
45
|
-
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json).
|
|
46
|
-
`PROCEED WITH CONDITIONS`, `REVISE` or `BLOCKED`.
|
|
47
|
-
CONDITIONS` at
|
|
45
|
+
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G3 emits `PROCEED`,
|
|
46
|
+
`PROCEED WITH CONDITIONS`, `REVISE` or `BLOCKED`. G3.1 adds `RECONSIDER`. `PROCEED WITH
|
|
47
|
+
CONDITIONS` at G3 is allowed only when the open rows are comms or exposure. A detection or
|
|
48
48
|
response gap is always `REVISE`.
|
|
49
49
|
|
|
50
50
|
## Non-interactive runs
|
|
51
51
|
|
|
52
52
|
Never invent evidence such as rehearsal logs, load-test numbers, dashboards or sign-offs.
|
|
53
53
|
When the change being released cannot be identified, emit `BLOCKED: need <the PR, tag, or
|
|
54
|
-
feature name>`.
|
|
55
|
-
|
|
54
|
+
feature name>`. G3.1 is a human gate. A headless run stops after `announce` and reports the
|
|
55
|
+
G3 verdict for a person to act on.
|
|
56
56
|
|
|
57
57
|
## When a stage's skill is not installed
|
|
58
58
|
|
|
@@ -68,7 +68,7 @@ gate's verdict, append one JSON line to that file. Nothing else is recorded, and
|
|
|
68
68
|
sent anywhere. When the variable isn't set, or you can't read it, skip this section.
|
|
69
69
|
|
|
70
70
|
```bash
|
|
71
|
-
printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"release","stage":"ready","gate":"
|
|
71
|
+
printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"release","stage":"ready","gate":"G3","verdict":"PROCEED","round":1}' >> "$SKILLDROP_LOOP_LOG"
|
|
72
72
|
```
|
|
73
73
|
|
|
74
74
|
Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
|
|
@@ -80,12 +80,12 @@ which end in `BLOCKED`.
|
|
|
80
80
|
|
|
81
81
|
- **Rollback exists before readiness is judged.** A plan with no way back is the one thing that cannot be fixed after launch.
|
|
82
82
|
- **Readiness rests on evidence.** Every check links to something; "we're good" is `not met`.
|
|
83
|
-
- **Can and should are separate gates.**
|
|
83
|
+
- **Can and should are separate gates.** G3 says whether it can ship; G3.1 says whether it should ship now.
|
|
84
84
|
- **Detection gaps leave this loop as hand-offs.** `operate` picks them up first, rather than discovering them during the first incident.
|
|
85
85
|
|
|
86
86
|
## Anti-patterns to avoid
|
|
87
87
|
|
|
88
88
|
- ❌ **Jumping from merge to "instrument a running service".** That skips this loop entirely, which is the gap it exists to close.
|
|
89
|
-
- ❌ **Announcing before
|
|
89
|
+
- ❌ **Announcing before G3.** Customers hear about a launch that is then pulled.
|
|
90
90
|
- ❌ **Treating flag-off as a rollback without a data story.** If dual-write or a backfill has run, turning the flag off does not undo the data.
|
|
91
|
-
- ❌ **Letting
|
|
91
|
+
- ❌ **Letting G3.1 overrule a G3 `BLOCKED`.** A human can delay a ready launch; they cannot make an unready one ready by deciding to go.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
{
|
|
2
|
-
"$comment": "RFC-0031. Covers the step between build (ends at merge, G2.1) and operate (starts at instrument).
|
|
2
|
+
"$comment": "RFC-0031. Covers the step between build (ends at merge, G2.1) and operate (starts at instrument). Its gates are G3 and G3.1: the whole number places the loop in the lifecycle (discover G0 through operate G4), and a decimal is a second gate inside the same loop (RFC-0044).",
|
|
3
3
|
"name": "release",
|
|
4
4
|
"version": "0.2.0",
|
|
5
5
|
"description": "Take merged code to live users through a planned, reversible rollout — plan the phases and the rollback, judge readiness on evidence, draft the release notes, then a human makes the go/no-go call. Use when the user has merged a change and asks how to roll it out, whether they are ready to launch, or for a go/no-go decision.",
|
|
@@ -19,7 +19,7 @@
|
|
|
19
19
|
"intent": "Judge on evidence whether the change can go live: rollback, detection, response, measured targets, data, comms, exposure.",
|
|
20
20
|
"skills": ["launch-readiness"],
|
|
21
21
|
"gate": {
|
|
22
|
-
"id": "
|
|
22
|
+
"id": "G3",
|
|
23
23
|
"kind": "review",
|
|
24
24
|
"verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
|
|
25
25
|
"revise_to": "plan"
|
|
@@ -37,7 +37,7 @@
|
|
|
37
37
|
"intent": "A human decides whether it should ship now. Readiness says it can; this decides timing, freeze windows, and who is on call.",
|
|
38
38
|
"skills": ["council-review"],
|
|
39
39
|
"gate": {
|
|
40
|
-
"id": "
|
|
40
|
+
"id": "G3.1",
|
|
41
41
|
"kind": "human",
|
|
42
42
|
"verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "RECONSIDER", "BLOCKED"],
|
|
43
43
|
"revise_to": "plan"
|
|
@@ -17,7 +17,7 @@ the cost of time; this one runs while real users are affected. Its feedback edge
|
|
|
17
17
|
| 1 | `instrument` | generate | [`observability-plan`](../../skills/observability-plan/SKILL.md) | — |
|
|
18
18
|
| 2 | `document` | generate | [`runbook-generator`](../../skills/runbook-generator/SKILL.md) | — |
|
|
19
19
|
| 3 | `respond` | generate | [`incident-comms`](../../skills/incident-comms/SKILL.md) | — |
|
|
20
|
-
| 4 | `learn` | verify | [`postmortem-generator`](../../skills/postmortem-generator/SKILL.md) | **
|
|
20
|
+
| 4 | `learn` | verify | [`postmortem-generator`](../../skills/postmortem-generator/SKILL.md) | **G4** human |
|
|
21
21
|
|
|
22
22
|
## How to run this loop
|
|
23
23
|
|
|
@@ -29,7 +29,7 @@ the cost of time; this one runs while real users are affected. Its feedback edge
|
|
|
29
29
|
3. **Respond to the audience the incident actually has.** `incident-comms` is staged —
|
|
30
30
|
detect, mitigate, resolve — and the stage determines the message. Writing a resolution
|
|
31
31
|
update during mitigation is the most common error here.
|
|
32
|
-
4. **Learn at
|
|
32
|
+
4. **Learn at G4.** `postmortem-generator` analyses blamelessly and ends with runbook deltas.
|
|
33
33
|
A human signs off that the incident is closed. `REVISE` returns to `document`: the deltas
|
|
34
34
|
are the loop's output, and applying them is what closes it.
|
|
35
35
|
|
|
@@ -38,7 +38,7 @@ starts at `instrument`. Do not replay earlier stages for their own sake.
|
|
|
38
38
|
|
|
39
39
|
## Verdicts
|
|
40
40
|
|
|
41
|
-
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json).
|
|
41
|
+
Defined in [`contracts/terminals.json`](../../../../contracts/terminals.json). G4 emits `PROCEED`,
|
|
42
42
|
`PROCEED WITH CONDITIONS`, `REVISE`, or `BLOCKED`. `PROCEED WITH CONDITIONS` means the
|
|
43
43
|
incident is closed but named follow-ups are outstanding — they travel with the postmortem.
|
|
44
44
|
|
|
@@ -61,7 +61,7 @@ gate's verdict, append one JSON line to that file. Nothing else is recorded, and
|
|
|
61
61
|
sent anywhere. When the variable isn't set, or you can't read it, skip this section.
|
|
62
62
|
|
|
63
63
|
```bash
|
|
64
|
-
printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"operate","stage":"learn","gate":"
|
|
64
|
+
printf '%s\n' '{"ts":"2026-10-01T14:03:00Z","loop":"operate","stage":"learn","gate":"G4","verdict":"PROCEED","round":1}' >> "$SKILLDROP_LOOP_LOG"
|
|
65
65
|
```
|
|
66
66
|
|
|
67
67
|
Fields: `ts` (UTC), `loop`, `stage`, `gate` (`null` for a stage without one), `verdict` (the
|
|
@@ -9,7 +9,7 @@
|
|
|
9
9
|
"Stages the communication (detect / mitigate / resolve) and matches the message to the stage the incident is in",
|
|
10
10
|
"Produces a blameless postmortem that names missing guardrails, never people",
|
|
11
11
|
"Ends in concrete runbook deltas phrased as before/after edits",
|
|
12
|
-
"Routes those deltas back to `document` via
|
|
12
|
+
"Routes those deltas back to `document` via G4's revise edge rather than treating the postmortem as terminal"
|
|
13
13
|
]
|
|
14
14
|
},
|
|
15
15
|
{
|
|
@@ -31,7 +31,7 @@
|
|
|
31
31
|
"intent": "Analyse blamelessly and emit runbook deltas. An incident that changes no procedure has not been learned from.",
|
|
32
32
|
"skills": ["postmortem-generator"],
|
|
33
33
|
"gate": {
|
|
34
|
-
"id": "
|
|
34
|
+
"id": "G4",
|
|
35
35
|
"kind": "human",
|
|
36
36
|
"verdicts": ["PROCEED", "PROCEED WITH CONDITIONS", "REVISE", "BLOCKED"],
|
|
37
37
|
"revise_to": "document"
|
|
@@ -46,7 +46,7 @@
|
|
|
46
46
|
"skill": "postmortem-generator",
|
|
47
47
|
"you_do": "Paste the incident thread, pager timeline and notes once it is over.",
|
|
48
48
|
"you_get": "A blameless postmortem with quantified impact, a UTC timeline showing detection and mitigation gaps, contributing factors, up to eight action items, and runbook deltas phrased as edits.",
|
|
49
|
-
"decide": "Gate
|
|
49
|
+
"decide": "Gate G4, a human call: PROCEED closes it, PROCEED WITH CONDITIONS closes it with named follow-ups, REVISE sends the deltas back to the runbook."
|
|
50
50
|
},
|
|
51
51
|
{
|
|
52
52
|
"skill": "delivery-metrics-report",
|