Audit Spec

Audit Spec

Audit, generate, or compare specifications for an existing feature.

Usage:

/audit-spec {featurename}              # generate spec from code
/audit-spec {featurename} --compare    # detect drift between spec and code

When to Use

Scenario	Use this?	Instead use
Legacy feature without spec	Yes	—
Check spec ↔ code consistency	Yes (--compare)	—
New feature creation	No	/creating-kmp-feature (spec is generated as part of the workflow)
Modifying existing feature	No	/modifying-kmp-feature (it updates the spec via review gate)

SDD best practice: specs should be written before implementation. /audit-spec is for auditing existing code or documenting legacy features.

Mode 1 — Generate Spec (default)

Process

1. Validate: ls feature/{featurename}/src/commonMain/kotlin/
2. Discover Package: grep "namespace" feature/{featurename}/build.gradle.kts
3. Analyze Implementation:
   • data/model/*.kt
   • data/datasource/*.kt
   • data/repository/*.kt
   • presentation/*ViewModel.kt
   • presentation/ui/*Screen.kt
   • presentation/navigation/*.kt
   • di/*Modules.kt
4. Check for PRD to preserve WHY content (Goals, Non-Goals, Background & Rationale, Design Decisions).
5. Generate .claude/docs/{featurename}/spec.md from _shared/spec-template.md.

Output

## Specification Generated
**Feature:** {featurename}
**Output:** .claude/docs/{featurename}/spec.md
**Action:** Review and fill TODO sections

Generated specs have TODO markers for any WHY section that couldn't be inferred from code.

Mode 2 — Drift Detection (--compare)

/audit-spec dashboard --compare

1. Load existing .claude/docs/{featurename}/spec.md.
2. Analyze current implementation (same scan as Mode 1).
3. Emit a drift report:

## Spec Drift Report: {featurename}
**Spec Version:** {version}

| Category | Status |
|----------|--------|
| Data Models | ✅ In sync / ⚠️ N drifts |
| Interfaces | ✅ In sync / ⚠️ N drifts |
| State Management | ✅ In sync / ⚠️ N drifts |
| Navigation | ✅ In sync / ⚠️ N drifts |

### Drift Details
{specific differences with file:line references}

### Proposed Spec Updates
{diff-format changes to apply}

Example Drift

### Data Models Drift
**File:** `LoginDto.kt:15`

| Aspect | Spec Says | Code Has |
|--------|-----------|----------|
| Fields | 3 fields | 4 fields |

**Missing from spec:**
```kotlin
val rememberMe: Boolean

## Notes

- Specs should be authored BEFORE implementation when possible.
- Run `--compare` periodically to detect drift (great for code-review checklists).
- After modifying a feature, prefer `/modifying-kmp-feature` over `/audit-spec` — modifying-kmp-feature updates the spec atomically with the code through its review gate.

---

Back to [[Commands]]