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.
In this repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- control-plane/AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- control-plane/CLAUDE.mdCLAUDE.md
- agentic-os-reference-syncSkill
- branch-cleanupSkill
- capture-triageSkill
- darwin-housekeepingSkill
- darwin-path-modeSkill
- decision-log-entrySkill
- eodSkill
- expert-interview-guideSkill
- feedback-intakeSkill
- harness-onboardingSkill
- ingest-contentSkill
- meeting-to-work-itemsSkill
- memory-consolidateSkill
- morning-briefSkill
- os-bootstrap-extendSkill
- os-bootstrapSkill
- pr-reviewSkill
- scheduleSkill
- ux-critiqueSkill
- weekly-retroSkill
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
- Very specific: line 15
Before merging a PR for a substantive feature, or when drift is suspected between the canonical spec (e.g.
- Distinctive: line 43
If the spec lacks these sections, list the gap as finding #0: "spec missing minimum structure".
≈ “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.
Files
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
| Dimension | Question | Typical severity |
| D1. Goal alignment | Does what the code produces match the spec's goal? | High |
| D2. Schema match | Declared output schema == spec's output schema? | High |
| D3. Locked premises | Are spec-mandated filters / distinctions enforced in code? | Critical |
| D4. Acceptance criteria | Does each testable AC have evidence (test, notebook)? | Medium |
| D5. Negative space | Does 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-entrywithtype: 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.
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
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.

