global-skills/skills/check/SKILL.md

name, description, concerns

name	description	concerns
check	Read-only drift detector comparing SPEC.md against current codebase. Audits invariants (§V), interface shapes (§I), and task completion (§T), reporting violations with file:line citations. Use when asked to "check drift", "audit spec", "spec vs code", or before releasing.	system-one-balance

Check — Drift Detector

Pure diagnostic audit. Reports violations and interface drift. Strictly read-only; writes nothing.

Spec drifting silently from code is the primary failure mode of long-lived projects. check catches drift before it becomes production defects.

---

Phase 0: Setup and Protocols

1. Non-Negotiable Invariants:
   • Zero Writes: Never edit code or SPEC.md. Report findings only.
   • Every violation must cite file:line evidence.
   • If SPEC.md is absent at repo root, report "no spec found" and exit.

---

Phase 1: Ingest and Check

1. Ingest SPEC.md from the project root.
2. Parse audit scope from arguments:
   • §V: Audit invariants only (default).
   • §I: Audit external interfaces only.
   • §T: Audit task status against reality.
   • --all (or empty): Audit all three sections.

---

Phase 2: Processing (Core Logic)

Step 1: Audit Invariants (§V)

For each V<n> invariant:

1. Translate invariant into a verifiable assertion about code.
2. Search and inspect corresponding files.
3. Classify state:
   • HOLD: Invariant actively satisfied with test or code assertion.
   • VIOLATE: Invariant actively violated in implementation.
   • UNVERIFIABLE: Invariant has no corresponding automated test or code guard.

Step 2: Audit Interfaces (§I)

For each interface defined in §I:

1. Locate implementation in routes, CLI, or exported functions.
2. Classify state:
   • MATCH: Code shape matches §I specification exactly.
   • DRIFT: Implementation exists but signatures, parameters, or return types diverge.
   • MISSING: Interface declared in spec but absent from code.
   • EXTRA: Code exposes public endpoints/flags not documented in §I.

Step 3: Audit Tasks (§T)

For each T<n> row:

1. If status is x: verify claimed files/tests exist in git. If absent, flag STALE.
2. If status is ~: note as in-progress.
3. If status is .: note as pending.

---

Phase 3: The System One Balance Pass

• Augment, Don't Handcuff:
  • Report findings concisely without lecturing or auto-triggering refactors.
  • Provide actionable remedy hints for each class of drift, leaving decisions to the user.

---

Phase 4: Output Execution & Verification

Emit the structured Caveman drift report:

## Drift Report

### §V Invariants
- V2 VIOLATE: src/auth/mw.ts:47 uses `<` instead of `≤`.
- V5 UNVERIFIABLE: no test covers concurrent refund boundary.

### §I Interfaces
- I.api DRIFT: POST /v1/charge returns `{result}` instead of `{id}`. routes/charge.py:82.
- I.cmd MISSING: `limiter bench` absent from CLI definitions.

### §T Tasks
- T3 STALE: marked `x` but auth middleware file not found in tree.

### Summary
- X violations, Y drifts, Z missing, W stale.
- **Remedy Hints**:
  - VIOLATE / DRIFT: Invoke `spec` with `bug: <V.n>` or fix code at cited lines.
  - MISSING: Invoke `build §T.n` or `spec amend §T`.
  - STALE: Invoke `spec amend §T` to reset status.