CLI Reference
betterspec diff
Show drift between specs and the current project state
betterspec diff
Run a full drift analysis and show where your specs and project state have diverged. Detects stale changes, missing capabilities, incomplete specs, and outdated knowledge docs.
Usage
betterspec diff [change]If [change] is provided, results are filtered to items related to that change.
Options
| Option | Description |
|---|---|
-C, --cwd <path> | Run as if betterspec was started in the given path |
Output
Shows a drift score (0–100) and items grouped by severity:
- Critical — Missing spec files for in-progress changes
- Warning — Stale changes, pending tasks with no progress, knowledge docs not updated after archiving
- Info — Proposed changes with no activity, archived changes without extracted capabilities
A score of 100 means no drift detected.
What it detects
| Drift type | Description |
|---|---|
stale-spec | A change that hasn't been updated in too long given its status |
missing-capability | Archived change with no outcome or extracted capabilities |
incomplete-spec | Spec files that are missing or have minimal content |
outdated-knowledge | Knowledge files not updated since recent capabilities were archived |
Example
$ betterspec diff
╭─ Drift Report ─────────────────────────────────────────────────────╮
│ Score: 72/100 │
│ │
│ Warnings (2) │
│ ⚠ "add-oauth" in progress for 9 days since last update │
│ ⚠ "add-oauth" is in-progress but all 4 tasks are still pending │
│ │
│ Info (1) │
│ · Architecture not updated since 2 capabilities were archived │
╰─────────────────────────────────────────────────────────────────────╯Filter to a specific change:
$ betterspec diff add-oauth