feat(skills): add self-healing and verify-gate skills from pskoett-skills fork
Self-healing: heal loop with verify-before-persist discipline, Pattern-Key dedup, HEAL entry format, 3 scripts, examples reference, eval.yaml. Verify-gate: 4-step process (Discover -> Run -> Fix Loop -> Gate Signal) with 3-attempt fix loop, scope-to-fix-only discipline, command discovery. .learnings/HEALS.md with template entry.
This commit is contained in:
178
data/skills/boocode/verify-gate/SKILL.md
Normal file
178
data/skills/boocode/verify-gate/SKILL.md
Normal file
@@ -0,0 +1,178 @@
|
||||
---
|
||||
name: verify-gate
|
||||
description: "Runs project compile, test, and lint commands between implementation and quality review. Gates simplify-and-harden behind machine verification. If checks fail, enters a fix loop with diagnostics. If checks pass, signals ready for quality pass. Use after any implementation work completes and before signaling done. Essential for the inner loop's verify step."
|
||||
---
|
||||
|
||||
# Verify Gate
|
||||
|
||||
Machine verification gate between implementation and quality review. Runs the project's compile, test, and lint commands. If any fail, enters a fix loop. If all pass, unblocks the quality pass.
|
||||
|
||||
This is the inner loop's **verify** step. Without it, the agent hands off code with zero machine signal about whether it actually works.
|
||||
|
||||
## When to Use
|
||||
|
||||
- After any implementation work completes, before signaling "done"
|
||||
- Before running simplify-and-harden or quality review
|
||||
- After fixing audit findings from code review
|
||||
- Any time you want a machine-verified green signal
|
||||
|
||||
## Pipeline Position
|
||||
|
||||
```
|
||||
[implementation] → verify-gate → [quality review / simplify-and-harden]
|
||||
↻ fix loop — on failure, diagnose and retry
|
||||
```
|
||||
|
||||
## Step 1: Discover Project Commands
|
||||
|
||||
Read the project's configuration to find verification commands. Check these sources in order:
|
||||
|
||||
1. **Project instruction files** (`CLAUDE.md`, `data/AGENTS.md`) — look for a `## Verification` or `## Test Commands` section
|
||||
2. **package.json** — `scripts.test`, `scripts.lint`, `scripts.typecheck`, `scripts.build`. BooCode uses pnpm, so prefer `pnpm run <script>` when `pnpm-lock.yaml` is present.
|
||||
3. **Makefile** / **Justfile** — `test`, `lint`, `check`, `build` targets
|
||||
4. **Cargo.toml** — `cargo build`, `cargo test`, `cargo clippy`
|
||||
5. **pyproject.toml** / **setup.cfg** — `pytest`, `mypy`, `ruff`
|
||||
6. **go.mod** — `go build ./...`, `go test ./...`, `go vet ./...`
|
||||
7. **deno.json** / **deno.jsonc** — `deno task <name>` for any defined tasks
|
||||
|
||||
If no commands are discoverable, ask the user once and suggest they add a `## Verification` section to `CLAUDE.md` for future sessions:
|
||||
|
||||
```markdown
|
||||
## Verification
|
||||
|
||||
- Build: `pnpm run build`
|
||||
- Test: `pnpm test`
|
||||
- Lint: `pnpm run lint`
|
||||
- Type check: `npx tsc -p apps/server/tsconfig.json --noEmit`
|
||||
```
|
||||
|
||||
## Step 2: Run Verification
|
||||
|
||||
Run discovered commands in this order. Stop at the first failure category.
|
||||
|
||||
### Phase 1: Compile / Type Check
|
||||
Run the build or type-check command. These catch structural errors before wasting time on tests.
|
||||
|
||||
```
|
||||
Exit 0 → proceed to Phase 2
|
||||
Exit non-zero → enter fix loop with compiler output
|
||||
```
|
||||
|
||||
### Phase 2: Tests
|
||||
Run the test command. Scope to changed files if the test runner supports it.
|
||||
|
||||
```
|
||||
Exit 0 → proceed to Phase 3
|
||||
Exit non-zero → enter fix loop with test output
|
||||
```
|
||||
|
||||
### Phase 3: Lint (optional, skippable with --skip-lint)
|
||||
Run the lint command. Lint failures are lower severity but still worth catching.
|
||||
|
||||
```
|
||||
Exit 0 → all phases green, gate passes
|
||||
Exit non-zero → enter fix loop with lint output
|
||||
```
|
||||
|
||||
## Step 3: Fix Loop
|
||||
|
||||
When a phase fails:
|
||||
|
||||
1. **Read the output.** Parse the error output for actionable diagnostics — file paths, line numbers, error messages.
|
||||
2. **Scope the fix.** Only fix what the verification caught. Do not refactor, improve, or touch unrelated code.
|
||||
3. **Apply the fix.** Make the minimal change to resolve the failure.
|
||||
4. **Re-run the failed phase.** Not all phases — just the one that failed.
|
||||
5. **If it passes**, continue to the next phase.
|
||||
6. **If it fails again**, increment the attempt counter.
|
||||
|
||||
### Fix Loop Limits
|
||||
|
||||
- **Default max attempts:** 3 per phase (configurable via `--fix-limit N`)
|
||||
- **Counter increments on every attempt**, even if the error changes. Fixing Error A and uncovering Error B counts as attempt 2, not attempt 1. The counter tracks fix attempts, not unique errors.
|
||||
- **If limit reached:** Stop. Report what failed, what was tried, and the remaining error output. Do not guess further — signal to the user that manual intervention is needed.
|
||||
- **Total budget:** The fix loop should not exceed 20% of the original implementation effort. If fixes are snowballing, stop and report.
|
||||
|
||||
## Step 4: Gate Signal
|
||||
|
||||
When all phases pass:
|
||||
|
||||
```markdown
|
||||
## Verify Gate: PASSED
|
||||
|
||||
- Build: passed
|
||||
- Tests: passed (N tests, M suites)
|
||||
- Lint: passed (or skipped)
|
||||
|
||||
Ready for quality review.
|
||||
```
|
||||
|
||||
When the fix loop is exhausted:
|
||||
|
||||
```markdown
|
||||
## Verify Gate: BLOCKED
|
||||
|
||||
- Build: passed
|
||||
- Tests: FAILED (attempt 3/3)
|
||||
- [file:line] error description
|
||||
- [file:line] error description
|
||||
- Lint: not reached
|
||||
|
||||
Fix loop exhausted. Manual intervention needed before quality review.
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### boocode simplify-and-harden / quality review
|
||||
verify-gate should gate any quality pass. Run verify-gate first; only proceed to review if the gate passes.
|
||||
|
||||
### self-healing (if available)
|
||||
On any failure during the verify run, consider handing the diagnostics to a self-healing loop (diagnose → patch → verify → persist). Verify-gate then re-runs the checks. Up to 3 heal attempts per phase before abandoning.
|
||||
|
||||
### self-improvement
|
||||
If a recurring error pattern emerges across verify runs, capture it in `CLAUDE.md` or as a new skill under `data/skills/boocode/` so future verify-gate runs don't rediscover the same fix.
|
||||
|
||||
## What This Skill Does NOT Do
|
||||
|
||||
- Does not review code quality (that's a separate review pass)
|
||||
- Does not check security
|
||||
- Does not verify spec compliance
|
||||
- Does not modify test files or add new tests
|
||||
- Does not run tests for code it didn't change (unless the test runner doesn't support scoping)
|
||||
|
||||
## Configuration
|
||||
|
||||
If the project has a `verify-gate` section in `CLAUDE.md` or `data/AGENTS.md`:
|
||||
|
||||
```yaml
|
||||
## Verify Gate Config
|
||||
|
||||
build: pnpm run build
|
||||
test: pnpm test
|
||||
lint: pnpm run lint
|
||||
type_check: npx tsc -p apps/server/tsconfig.json --noEmit
|
||||
fix_limit: 3
|
||||
skip_lint: false
|
||||
test_scope: changed # changed | all
|
||||
```
|
||||
|
||||
If no configuration exists, discover commands automatically (Step 1) and suggest persisting them.
|
||||
|
||||
### Custom Verification Steps
|
||||
|
||||
Projects with custom invariants can define additional verification phases. These run as extra phases after the standard compile/test/lint checks.
|
||||
|
||||
Example — a project that needs API schema validation:
|
||||
|
||||
```yaml
|
||||
## Verify Gate Config
|
||||
|
||||
custom_checks:
|
||||
- name: validate-schema
|
||||
command: python scripts/validate_schema.py --strict
|
||||
- name: check-no-legacy-imports
|
||||
command: grep -r "from legacy" src/ --include="*.py" && exit 1 || exit 0
|
||||
```
|
||||
|
||||
When custom checks are defined, verify-gate runs them as **Phase 4** after lint. Each check's exit code determines pass/fail. Failed checks enter the same fix loop as standard phases.
|
||||
|
||||
This moves project-specific invariants from "knowledge in your head" to "knowledge in the harness" — exactly where the agent can reach it.
|
||||
Reference in New Issue
Block a user