ship-a-detector: the playbook for authoring a hook or gate detector

docs/ecosystem.md

@@ -127,6 +127,7 @@ full install.
 | `diu` | portable brevity |
 | `land-stack` | land stacked PRs |
 | `loop-generator` | loop workflows |
+| `ship-a-detector` | hook/gate detector authoring playbook |
 | `split-scope` | PR slice shaping |
 | `visual-proof` | UI proof |
 | `show-me-your-work` | decision log |

docs/skill-triggers.md

@@ -57,11 +57,11 @@ instead share vocabulary with its `description:`.
 
 <!-- BEGIN generated: skill-triggers (scripts/check_skill_trigger_policy.py) -->
 
-### Auto-fire (18)
+### Auto-fire (19)
 
 The model may invoke these from a description match. Everything here is a gate or a procedure that is useless if it only runs when named.
 
-`create-skill`, `draft-pr`, `make-pr`, `thrash-reflect-automate`, `principle-prove-it`, `principle-subagent-inherits-scope`, `prove-it-ship-gate`, `alternatives-considered`, `diu`, `how`, `land-stack`, `loop-generator`, `narrow-the-scope`, `show-me-your-work`, `spike-and-validate`, `split-scope`, `visual-proof`, `why`
+`create-skill`, `draft-pr`, `make-pr`, `thrash-reflect-automate`, `principle-prove-it`, `principle-subagent-inherits-scope`, `prove-it-ship-gate`, `alternatives-considered`, `diu`, `how`, `land-stack`, `loop-generator`, `narrow-the-scope`, `ship-a-detector`, `show-me-your-work`, `spike-and-validate`, `split-scope`, `visual-proof`, `why`
 
 ### Explicit invocation only (33)
 

product/skills/ship-a-detector/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ship-a-detector
+description: >
+  Author a hook or gate detector end to end: the seven defect kinds this
+  repo keeps re-shipping, then the install, test, README, and inventory
+  wiring a detector is not finished without. Trigger before writing or
+  widening anything under engine/hooks/ or a scripts/check_*.py gate —
+  a new PreToolUse/Stop/UserPromptSubmit hook, a new detector inside an
+  existing hook, or a regex change to one that already ships.
+---
+
+# ship-a-detector
+
+Use this before writing or widening a detector — a hook under
+`engine/hooks/`, or a CI gate under `scripts/check_*.py`. Both decide
+"does this input match the bad thing", and both break the same seven ways
+here.
+
+## Why this exists
+
+Measured on this repo's own history: 65 of 185 merged PRs touch
+`engine/hooks/`, 13 of 28 hooks needed post-ship repair, and 37 PRs did
+nothing but repair a shipped detector. `diu-stop` took 8, `pr-schema-gate`
+7, `wrong-check-reflect` 6, `scope-lock` 4. `gh-write-verification` hit two
+separate known kinds in three days (#322, #323, #324). None of those were
+new problems; each was a kind already fixed in another hook.
+
+## The playbook
+
+Read and copy [playbooks/detector-lifecycle.md](playbooks/detector-lifecycle.md)
+before any task-specific work. It is a verbatim ordered list: paste all 20
+steps into your todolist first, then work them. A step that does not apply
+stays in the list marked `skip: <reason>` — deleting it is how a kind gets
+re-shipped.
+
+The same list covers both jobs. A new hook works every step. A widening of
+a shipped detector skips the wiring tail with reasons and still works the
+detection steps, because 37 of this repo's repair PRs were repairs of
+detection, not of wiring.
+
+## Two rules that outrank the list
+
+- Every numbered step names the PRs that motivated it. If you add a step,
+  it names its prior art or says "no known prior art" — a step invented
+  from a guess is the thing this repo already tried.
+- The list ends by calling the installed `make-pr` skill. `make-pr` opens
+  the PR; it does not own the install, README, or inventory steps. Those
+  are steps 14–18 here, because that is measurably where this repo breaks:
+  10 of 31 hooks have no `docs/ecosystem.md` row, and 8 got theirs in a
+  later PR.