Pain
specter doctor v0.9.0+ pattern-analysis block is excellent for large-scale drift — it correctly identified that JWTMS had 1,934 parse errors across 14 recurring shapes during migration, which made the work tractable. During iterative transform development, every small change to the migration script produced the same large diagnostic block, and finding the new error shape introduced by the latest change required eyeballing two outputs side-by-side.
Proposed
specter doctor --diff <baseline.json> (or similar) that takes a previous output and reports only the deltas:
$ specter coverage --json > before.json
$ # ... iterate on migration script ...
$ specter doctor --diff before.json
new errors:
- 12 specs: missing 'context.system' (was 0 before)
new fixes:
- 247 specs: 'spec.objective' now valid (was failing)
unchanged:
- 1,675 errors of pre-existing type 'invalid_status_enum'
Why it matters for adoption
For migrations specifically — when iterating on a YAML-to-YAML transform script, knowing which errors are new since the last run is the actionable signal. Total error counts dominate the noise.
For ongoing work — pre-commit / pre-push hooks could --diff main to surface only newly-introduced doctor warnings.
Context
JWTMS migration: developed a ~500-line YAML transform script over ~3 weeks. Each iteration ran against 249 specs; the doctor output was 1,000+ lines of which maybe 20 lines were new. A delta mode would have shrunk each iteration's review surface by 95%.
Lower priority than FR-1 (specter migrate), but if FR-1 ships then --diff becomes a natural companion for the migrate iteration loop.
Pain
specter doctorv0.9.0+ pattern-analysis block is excellent for large-scale drift — it correctly identified that JWTMS had 1,934 parse errors across 14 recurring shapes during migration, which made the work tractable. During iterative transform development, every small change to the migration script produced the same large diagnostic block, and finding the new error shape introduced by the latest change required eyeballing two outputs side-by-side.Proposed
specter doctor --diff <baseline.json>(or similar) that takes a previous output and reports only the deltas:Why it matters for adoption
For migrations specifically — when iterating on a YAML-to-YAML transform script, knowing which errors are new since the last run is the actionable signal. Total error counts dominate the noise.
For ongoing work — pre-commit / pre-push hooks could
--diff mainto surface only newly-introduced doctor warnings.Context
JWTMS migration: developed a ~500-line YAML transform script over ~3 weeks. Each iteration ran against 249 specs; the doctor output was 1,000+ lines of which maybe 20 lines were new. A delta mode would have shrunk each iteration's review surface by 95%.
Lower priority than FR-1 (
specter migrate), but if FR-1 ships then--diffbecomes a natural companion for the migrate iteration loop.