Feature: /sync-standards - detect drift between your standards and codebase

[shah-siddd]

Problem & Motivation

Standards drift. You document how your API handles errors, how tests are structured, how naming works - and then the codebase evolves. Someone introduces error classes instead of error code strings. Tests move from Jest to Vitest. A pattern gets deprecated quietly.

Today, /discover-standards creates standards from scratch and /inject-standards pushes them into context. But nothing checks whether existing standards still reflect reality. You don't find out they're stale until an agent follows an outdated standard and produces wrong code.

There's no feedback loop. Discover writes, inject reads, but nothing validates.

Proposed Change & Alternatives

Proposed: a /sync-standards command that reviews existing standards against the actual codebase, surfaces what's drifted, and helps you reconcile.

The flow:

1. Load all current standards from index.yml
2. For each standard, sample relevant files in the codebase (prioritizing recently modified files)
3. Classify each standard as: in sync, drifted, partially drifted, or obsolete
4. Present a grouped summary of findings
5. For each drifted standard, show what the standard says vs. what the code does - with concrete file references
6. Offer per-standard actions: update standard, flag code (standard is correct, code needs fixing), merge (update with manual edits), remove, or skip
7. Surface any new undocumented patterns noticed during the scan
8. Update index.yml and report a final summary

Supports scoping: /sync-standards (all), /sync-standards api (folder), /sync-standards api/response-format (single file).

Alternatives considered:

• Automatic sync during /inject-standards - Too slow. Injection should be fast; drift detection requires reading many files. Coupling them would make inject unusable for quick context loading.
• Git-diff based detection - Compare standards files against git history to find when code changed after a standard was last modified. Lighter weight, but misses drift that happened gradually or across many commits. Also wouldn't catch standards that were wrong from the start.
• Lint-style continuous checking - Run drift detection on every commit or in CI. Potentially useful as a future addition, but overkill as a starting point. The interactive command-based approach lets users build the habit first.

User Experience Impact

• New command: /sync-standards - no changes to existing commands
• Workflow fit: Intended to be run periodically (e.g., after a sprint, before a major feature, or when something feels off). Not a daily command.
• Interactive by default: Every change goes through the user. Nothing gets updated silently. The "flag code" option lets users mark cases where the code is wrong instead of the standard - preserving intent.
• Low friction entry point: If you have 8 or fewer standards, it syncs all of them without asking for scope. Larger projects get a scope picker.

Updating & Compatibility Considerations

• No changes to existing commands -/discover-standards, /inject-standards, and /index-standards continue to work exactly as they do today
• No changes to file formats - Standards files and index.yml use the same structure. Updated standards follow the same concise markdown format
• Installation - The new command file gets copied alongside existing commands during project-install.sh (same mechanism as all other commands, no script changes needed)
• Works with any existing standards - Since it reads from index.yml and the standards directory, it works immediately with any project that already has standards set up

---