boocode/data/skills/boocode/verify-gate/SKILL.md

name, description

name	description
verify-gate	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:

## 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:

## 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:

## 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:

## 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:

## 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.