skills: decompose prove-it into a principle plus four evidence products - #302
Merged
Conversation
## Context - Problem: catstack ships three hooks that enforce prove-it (prove-it-ship-gate, hedge-runs-prove-it, diu-stop) and eight skills that cite it, but does not own the rule. diu-stop tells the agent to read "skills/prove-it/SKILL.md in the Invoker repo"; ~/.claude/skills/ invoker-prove-it is a real directory written by Invoker's installer, so ./install.sh cannot update it. Engine-only mode cites a file it does not install. - Trigger: reading lauren (@poteto)'s pstack guide (mirrored at github.com/cursor/plugins/pstack/docs/guide) surfaced /how and /why as understand-before-edit skills catstack has no equivalent of. The gap is real: our only git-history rule is one bullet in principle-fix-root-causes:22, not a procedure. ## Considerations - Chose: split the rule from the procedures. principle-prove-it holds the claim gate (corpus, because check_ecosystem_boundaries.py:206 requires principle-* live there). how / why / alternatives-considered / spike-and-validate hold the fan-outs (product, human-authored portable workflows per docs/ecosystem.md). - Chose: principle-prove-it is the one principle that does NOT carry disable-model-invocation. The other 25 are steering vocabulary you invoke by name; this one is a gate whose job is to intercept a claim as it forms. A gate that only fires when someone remembers to name it is not a gate. prove-it-ship-gate already auto-fires from corpus, so there is precedent. - Rejected: reusing independent-judge-swarm's board shape. That grades a finished artifact (verdict/score/blocking_issues); these four return findings about work that has not happened yet, so there is nothing to grade. Shared shape lives in principle-prove-it/references/ finding-shape.md instead, reusing the fan-out mechanic and the document-the-null rule from reflect/references/lenses.md. - Rejected: treating alternatives-considered as symmetric with how/why. how and why read what exists and can return an honest null; alternatives generates, so it can always produce three plausible options and manufacture evidence for the very gate it feeds. Every option is labeled considered (cited) or invented (untested), and an invented option may not decide anything until spike-and-validate turns it into a run with real output. - Not done here: retiring invoker-prove-it, repointing diu-stop's message at the new principle, and documenting/enforcing which skills may auto-fire. The last one is the next slice in this stack — it found that product/skills/admin-bypass-sweep (force-merge past required checks) is auto-invocable today and held back only by prose in its description. ## Blast Radius - Adds only. No existing file modified, no hook logic touched. - New: corpus/skills/principle-prove-it/ (SKILL.md, references/ finding-shape.md, 2 test fixtures); product/skills/{how,why, alternatives-considered,spike-and-validate}/ (SKILL.md + 2 fixtures each). - principle-prove-it auto-fires, so it can now load on claim-shaped turns that previously loaded nothing. Cost is context on exactly the turns where the rule applies. - Risk: `how` and `why` are generic names in a flat installed skill namespace. Verified no collision in ~/.claude/skills at authoring time. - Revertable with git revert; ./install.sh prunes the symlinks on rerun. ## Verification - python3 scripts/check_ecosystem_boundaries.py -> ok - python3 scripts/check_skill_file_refs.py -> ok - python3 scripts/check_skills_three_harnesses.py -> ok - python3 scripts/check_skill_trigger_mechanism.py -> ok - python3 scripts/check_skill_test_coverage.py --base origin/main --head HEAD -> ok (rerun post-commit; the pre-commit run compared origin/main to an unchanged HEAD and passed vacuously) - check_codify_has_code.py run with --allow-prose-only: this slice adds rule prose whose enforcement already ships in engine/hooks/prove-it-ship-gate, engine/hooks/hedge-runs-prove-it, and engine/hooks/diu-stop. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JQMWSLRArEfEm1psa7RKdD
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_36b6abee-907f-442a-a22c-a19276db75a9) |
3 tasks
Contributor
|
Queued — the merge queue status continues in this comment ↓. |
Owner
Author
|
@Mergifyio queue |
Contributor
Merge Queue Status
This pull request spent 5 minutes 6 seconds in the queue, with no time running CI. Waiting for
All conditions
ReasonPull request #302 has been merged manually at 2dc9a9f HintYou were too fast! Tick the box to put this pull request back in the merge queue (same as
|
5 tasks
Contributor
☑️ The pull request has been merged manuallyDetailsThe pull request has been merged manually at 2dc9a9f |
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
Catstack now owns the prove-it rule instead of borrowing it. Three of our hooks already enforce prove-it and eight of our skills cite it, but the rule itself lived in Invoker's installed skill directory, which
./install.shcannot touch.This splits it in two.
principle-prove-itholds the claim gate: no claim settled without evidence in the same message. Four product skills gather that evidence —howfor the mechanism,whyfor the lineage,alternatives-consideredfor the option set,spike-and-validatefor the option nobody has run yet.Idea borrowed from lauren (@poteto)'s pstack guide, which has
/howand/whyas understand-before-edit skills. We had neither. Our only git-history rule was one bullet insideprinciple-fix-root-causes.Review Claim
Catstack should own the prove-it claim gate as a corpus principle, with the four evidence-gathering procedures as product skills.
Review Lane
policyReview Unit
product-skill(dominant: 12 of 16 files)Safety Invariant
Adds only — no existing file is modified and no hook logic changes. The single behavior change is that
principle-prove-itomitsdisable-model-invocation, so it can auto-load on claim-shaped turns. Its content restates evidence rules thatengine/CLAUDE.core.mdalready loads on every turn, so a load puts the agent under no rule it was not already under. The four products are inert until invoked.Slice Rationale
Two review units ship together because they cannot be separated: all four product skills cite
corpus/skills/principle-prove-it/references/finding-shape.md, so a products-only slice failsscripts/check_skill_file_refs.py, and a principle-only slice ships a routing table pointing at four skills that do not exist.check_codify_has_code.pywas run with--allow-prose-only. This slice adds rule prose whose enforcement already ships:engine/hooks/prove-it-ship-gate,engine/hooks/hedge-runs-prove-it, andengine/hooks/diu-stop. It relocates a rule into a loadable skill; it does not introduce an unenforced invariant.Non-goals
invoker-prove-it. Both exist after this.engine/hooks/diu-stop's message, which still cites the Invoker path.product/skills/admin-bypass-sweep— force-merges PRs past required checks — is auto-invocable today and held back only by prose in its own description../install.sh. From a worktree that would point the home skill roots at.worktrees/.Test Plan
Test Plan
python3 scripts/check_ecosystem_boundaries.py→ok ecosystem boundariespython3 scripts/check_skill_file_refs.py→ok skill file refspython3 scripts/check_skills_three_harnesses.py→ok skills three-harness checkpython3 scripts/check_skill_trigger_mechanism.py→ok skill trigger mechanismpython3 scripts/check_skill_test_coverage.py --base origin/main --head HEAD→ok skill test coveragepython3 scripts/check_no_dated_provenance.py --base origin/main→ok no dated provenancepython3 scripts/check_codify_has_code.py --base origin/main --allow-prose-only→ok codify-has-code: prose-only change explicitly allowedNote: the first
check_skill_test_coverage.pyrun passed vacuously — it comparedorigin/mainagainst an uncommittedHEAD. The result above is the post-commit rerun.Revert Plan
Revert Plan
git revert <sha>./install.shfrom the main checkout to prune the five skill symlinks from the three harness roots🤖 Generated with Claude Code
https://claude.ai/code/session_01JQMWSLRArEfEm1psa7RKdD
Note
Low Risk
Additive markdown skills only; prove-it behavior is already enforced by hooks and core engine rules—the main nuance is optional auto-invocation of the principle on claim-shaped turns.
Overview
Catstack now owns the prove-it workflow in-repo instead of relying on Invoker’s external skill: a corpus
principle-prove-itdefines the claim gate (same-turn evidence orUNVERIFIED:, hedges trigger verification) and routes to four investigation products. Unlike otherprinciple-*skills, it omitsdisable-model-invocationso it can auto-match claim-shaped turns.The four new product skills (
how,why,alternatives-considered,spike-and-validate) spell out fan-out/merge procedures for mechanism tracing, git/PR lineage, labeled option sets (consideredvsinvented), and throwaway spikes with pasted output. They share afinding-shape.mdcontract (grounding,evidence,null_result, merge rules). Each skill shipsfires_example/stays_silent_examplefixtures for trigger coverage.No hook or existing file edits in this diff—enforcement stays on existing
engine/hooks/*; this slice is documentation and loadable skill content wired forcheck_skill_file_refsand related skill harness checks.Reviewed by Cursor Bugbot for commit 251d82e. Bugbot is set up for automated code reviews on this repo. Configure here.