ship-a-detector: the playbook for authoring a hook or gate detector - #331
Merged
mergify[bot] merged 2 commits intoSep 10, 2026
Conversation
65 of 185 merged PRs in this repo touch engine/hooks/, 13 of 28 hooks needed post-ship repair, and 37 PRs did nothing but repair a shipped detector. gh-write-verification hit two already-known kinds in three days (#322, #323, #324). create-skill never mentions hooks, CONTRIBUTING has no hook section, and 10 of 31 hooks have no docs/ecosystem.md row. The playbook is a verbatim 20-step ordered list, copied into a todolist before task-specific work; a step that does not apply stays in the list marked `skip: <reason>`. Steps 4-10 are the seven recurring defect kinds, one per step. Steps 14-18 are the install, README, and inventory tail that this repo measurably drops. Step 20 hands off to make-pr. Every numbered step cites the PRs that motivated it. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…authoring a detector follows one written, ordered sequence whose steps come from the repair history rather than from memory. Review lane: behavior Safety invariant: the playbook adds no new mechanical gate and changes no existing hook, so a detector that passes CI today still passes; it can only change what a future author does before opening a PR. Slice rationale: the sequence has to exist before anything can route to it, and its steps are derived from thirty-seven specific PRs, so writing it is a separate reviewable claim from wiring the routing. Architectural effect: adds the repo's second playbook package; its final step calls the existing make-pr skill rather than duplicating publication. Goal: add product/skills/ship-a-detector with a playbook carrying the ordered steps that the thirty-seven repair PRs imply. Effectiveness measurement: each of the seven recurring defect kinds maps to a numbered step, and each step cites the PR numbers that motivated it, so a reader can check the step against the incident rather than trusting the author. Motivation: gh-write-verification shipped this month and hit two of the seven known kinds within three days, authored by an agent with the whole corpus available; the knowledge existed and was not reachable. Alternative considerations: adding the steps to create-skill was rejected because that skill covers skills rather than hooks and mixing them would bury both; a new hook was rejected because the gap is a missing order, not a missing check. Implementation details: the seven kinds are target and scope resolution, false positive on quoted or fenced content, missed near-miss shape, retry-loop behaviour under stop_hook_active, first-failure exit hiding a second check, unreadable input reported as clean, and lifecycle state across turns. Non-goals: does not modify any existing hook, does not add a CI gate, does not change create-skill, does not reimplement what make-pr does. Layer: domain Feature state: active Files: product/skills/ship-a-detector/** (new) Change types: new skill, new playbook Acceptance criteria: check_skill_test_coverage.py passes for the new skill, and every numbered step cites at least one PR number. Exit code: 0
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_f4edefff-78d5-4176-a66f-5bf1481cd812) |
Contributor
|
Queued — the merge queue status continues in this comment ↓. |
Owner
Author
|
@Mergifyio queue |
Contributor
Merge Queue Status
This pull request spent 4 minutes 49 seconds in the queue, including 3 minutes 27 seconds running CI. Required conditions to merge
|
5 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
product/skills/ship-a-detector, a playbook for writing a hook or gate detector in this repo. Sixty-five of one hundred eighty-five merged PRs touchengine/hooks/, and thirty-seven of those were post-ship repairs across thirteen hooks. The repairs collapse into seven recurring defect kinds, each already solved somewhere in the corpus and none reachable by the next author.The playbook is an ordered list meant to be copied into a todolist before work starts. A step that does not apply stays in the list marked
skip: <reason>rather than disappearing.Review Claim
Authoring a detector follows one written, ordered sequence whose steps come from the repair history rather than from memory.
Review Lane
behavior
Safety Invariant
Adds no mechanical gate and changes no existing hook. A detector that passes CI today still passes. The only thing that changes is what a future author does before opening a PR. Confirmed by the repository owner.
Slice Rationale
The sequence must exist before anything can route to it, and its steps derive from thirty-seven specific PRs, so writing it is a separate reviewable claim from wiring the routing. The router ships as its own PR.
Non-goals
Does not modify any existing hook. Does not add a CI gate. Does not change
create-skill. Does not reimplement whatmake-prdoes; the final step calls it.Test Plan
Built and verified by Invoker workflow
wf-1788992325476-4. Both the implementation task and itsverify-ship-a-detectortask completed, runningcheck_skill_test_coverage.py,check_skill_trigger_mechanism.pyand the full suite. The workflow's terminal__merge__task then failed on a git conflict, which is why this branch is opened as a PR directly rather than merged by Invoker.Revert Plan
git revertthe merge commit. The change is additive: one new skill directory plus adocs/skill-triggers.mdrow. Nothing existing depends on it.🤖 Generated with Claude Code
https://claude.ai/code/session_01F43CBUnsDEs6J2zEC1r8a8
Note
Low Risk
Additive documentation and a new product skill only; no hook, gate, or install script changes.
Overview
Introduces
ship-a-detector, an auto-fire product skill that agents should run before writing or widening anything underengine/hooks/orscripts/check_*.py. It does not change runtime behavior, hooks, or CI — only adds procedural guidance.The skill points authors at
playbooks/detector-lifecycle.md, a 20-step checklist (paste verbatim into a todo; useskip: <reason>instead of deleting steps) covering the seven recurring detector defect classes, fixtures and fail-before/pass-after evidence, install/settings wiring, README anddocs/ecosystem.mdinventory, full CI commands, thenmake-prat step 20.SKILL.mdplusfires_example.md/stays_silent_example.mddocument when description-match should fire vs stay silent.docs/ecosystem.mdgains a product inventory row;docs/skill-triggers.mdregenerated so auto-fire count is 19 andship-a-detectoris listed.Reviewed by Cursor Bugbot for commit ac34e88. Bugbot is set up for automated code reviews on this repo. Configure here.