agentleFS
DScardini91DScardini91/agentic-os/.claude/skills/spec-cross-check/SKILL.md

spec-cross-check

Skill2 starsChanged 5 months agoMITView on GitHub

Diff between implemented code and the canonical spec — identifies drift (code does more/less/differently than spec), categorizes by severity, suggests spec amendments or code corrections. Antidote to "implementation creep" — code growing past what the spec actually licenses.

The file

We split this skill into the rules it gives an agent

2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before merging a PR for a substantive feature, or when drift is suspected between the canonical spec (e.g.

    line 15
  2. Distinctive:

    If the spec lacks these sections, list the gap as finding #0: "spec missing minimum structure".

    line 43

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Skill: spec-cross-check

When to use

Before merging a PR for a substantive feature, or when drift is suspected between the canonical spec (e.g. docs/harness/specs/<module>.md) and the implementation (e.g. src/<module>/).

NOT for:

  • Purely technical code review → use pr-review.
  • Validating business logic with data → notebook in the repo.
  • New methodological decision → decision-log-entry.

Inputs

  • spec_path (required) — path to the canonical spec.
  • code_path (required) — directory of the implementation.
  • mode (optional) — "quick" (5 high-level dimensions) or "deep" (each acceptance criterion checked individually).

Sequence

Step 1 — Read the canonical spec

Identify and extract:

  • Goal — what the module / feature must produce.
  • Acceptance criteria — verifiable tests (verbatim when stated).
  • Output schema — expected fields, types.
  • Locked premises — things the code MUST respect (filters, distinctions, etc.).
  • Negative space ("is not") — things the code MUST NOT do.

If the spec lacks these sections, list the gap as finding #0: "spec missing minimum structure".

Step 2 — Read the implementation

For each .py (or equivalent) file under code_path:

  • Module docstring.
  • Public functions and their docstrings.
  • Output schema (if applicable, often in a config file).

Step 3 — Cross-check across 5 dimensions

DimensionQuestionTypical severity
D1. Goal alignmentDoes what the code produces match the spec's goal?High
D2. Schema matchDeclared output schema == spec's output schema?High
D3. Locked premisesAre spec-mandated filters / distinctions enforced in code?Critical
D4. Acceptance criteriaDoes each testable AC have evidence (test, notebook)?Medium
D5. Negative spaceDoes the code do something the spec explicitly forbids?High

Severity ladder:

  • 🔴 Critical — violates a locked premise / does something the spec forbids.
  • 🟠 High — substantive goal or schema misalignment.
  • 🟡 Medium — AC without evidence / outdated docstring / minor technical drift.
  • 🟢 Info — observation without immediate action.

Step 4 — Decide direction of fix

For each finding:

  • Spec amendment — code is correct, spec is outdated → escalate to decision-log-entry + edit the spec.
  • Code fix — spec is correct, code drifted → open an issue or fix PR.
  • Discuss — ambiguous, requires methodological decision (escalate to decision-log-entry with type: methodology).

Step 5 — Structured output

## Spec cross-check — <module/feature>

**Spec:** <path>
**Code:** <path>
**Mode:** quick | deep

### Findings

#### 🔴 Critical — N
- <finding> · spec: <line/section> · code: <file:line> · direction: <spec-amend / code-fix / discuss>

#### 🟠 High — N
- ...

#### 🟡 Medium — N
- ...

#### 🟢 Info — N
- ...

### Recommended action queue
1. <highest severity> · <direction> · owner: <who>
2. ...

### Drift summary
- Code does <X> that spec doesn't license: ...
- Spec mandates <Y> that code doesn't implement: ...
- Both diverge on <Z>: ...

Anti-patterns

  • Mass-categorizing every difference as 🔴 — severity exists to focus attention. Use the ladder honestly.
  • Failing to choose a direction — every finding gets one of {spec-amend, code-fix, discuss}. "Both could be right" is not a direction.
  • Skipping the negative space check (D5) — implementation creep usually surfaces here, not in the positive-space dimensions.
  • Reading code without reading the spec first — the order matters: spec defines the question, code is the answer being graded. Reading code first biases what is seen.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.