spec-import-guard

Validates spec import pipeline changes through version checks, corpus tests, and AI round-trip harnesses.

Updated Jun 15, 2026
One-click install
npx skills add https://github.com/ravenslight2010/Production-run-calculator --skill spec-import-guard-ravenslight2010
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: spec-import-guard
Source: https://github.com/ravenslight2010/Production-run-calculator/tree/main/.agents/skills/spec-import-guard
Command: npx skills add https://github.com/ravenslight2010/Production-run-calculator --skill spec-import-guard-ravenslight2010

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Changes to the pizza spec import pipeline (AI parse prompts, sanitizers, alias logic, chunk merging) can silently corrupt production data through stale parse caches, dropped rows, poisoned aliases, or mis-routed recipes. This Skill provides a mandatory validation checklist that catches these regressions before they reach managers re-importing spec sheets. ## Core Features & Use Cases - Cache Version Enforcement: Ensures SPEC_PARSE_VERSION is bumped whenever the parse prompt, sanitizer output, or pipeline ordering changes, preventing stale cached parses from being served. - Deterministic Regression Testing: Runs the corpus harness against checked-in snapshots and the lib/spec-import unit tests to catch dropped rows, routing errors, and alias hygiene violations without AI calls. - Real-AI Round-Trip Harnesses: Verifies large-spec imports and parse-rule stress scenarios against the live model to detect silent data loss when prompts or models change. - Use Case: After rewording the AI parse prompt, follow the checklist to bump SPEC_PARSE_VERSION, run the corpus tests, and execute the smoke round-trip harness to confirm no profiles or recipes are lost. ## Quick Start Ask the AI to run the spec import guard checklist for your changes to the parse prompt in aiParseSpecSheet.ts.

Frequently Asked Questions about spec-import-guard

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I test spec import pipeline changes before deploying?

Run the corpus harness with pnpm --filter @workspace/corpus-harness run test for deterministic snapshot regression, then the lib/spec-import vitest suite. If the AI prompt or model changed, also run the real-AI round-trip harnesses.

When do I need to bump SPEC_PARSE_VERSION?

Bump SPEC_PARSE_VERSION whenever the parse prompt, sanitizer output shape, chunk limits, or pipeline ordering changes. Without the bump, the saved_spec_sheets cache serves stale parses and managers see old broken results.

Why does the spec import create duplicate recipes?

Duplicates occur when the spec sheet is imported before the master-data workbooks, leaving the AI match-import pass with empty target pools. Cheese dedupes by exact name only, while mixes and dough/sauce use a loose key tolerating case and filler-token drift.

Can I skip the real-AI harnesses for sanitizer-only changes?

Yes, purely deterministic changes to the sanitizer, chunk logic, alias system, or link passes only require the corpus harness and lib/spec-import unit tests. Real-AI harnesses are required only after prompt or model changes.

Why do aliases get poisoned and reappear after cleanup?

Alias poison self-perpetuates when the suggestion-build step reads unsanitized aliases, surfacing bad entries as pre-selected picks that get re-learned on confirmation. Sanitize at all four layers: suggestion build, learn path, commit save, and server backstop.