# Remove Diff Command

## Problem

The `openspec diff` command adds unnecessary complexity to the OpenSpec CLI for several reasons:

1. **Redundant functionality**: The `openspec show` command already provides comprehensive visualization of changes through structured JSON output and markdown rendering
2. **Maintenance burden**: The diff command requires a separate dependency (jest-diff) and additional code complexity (~227 lines)
3. **Limited value**: Developers can achieve better diff visualization using existing tools:
   - Git diff for actual file changes
   - The `show` command for structured change viewing
   - Standard diff utilities for comparing spec files directly
4. **Inconsistent with verb-noun pattern**: The command doesn't follow the preferred verb-first command structure that other commands are migrating to

## Solution

Remove the `openspec diff` command entirely and guide users to more appropriate alternatives:

1. **For viewing change content**: Use `openspec show <change-name>` which provides:
   - Structured JSON output with `--json` flag
   - Markdown rendering for human-readable format
   - Delta-only views with `--deltas-only` flag
   - Full spec content visualization

2. **For comparing files**: Use standard tools:
   - `git diff` for version control comparisons
   - System diff utilities for file-by-file comparisons
   - IDE diff viewers for visual comparisons

## Benefits

- **Reduced complexity**: Removes ~227 lines of code and the jest-diff dependency
- **Clearer user journey**: Directs users to the canonical `show` command for viewing changes
- **Lower maintenance**: Fewer commands to maintain and test
- **Better alignment**: Focuses on the core OpenSpec workflow without redundant features

## Implementation

### Files to Remove
- `/src/core/diff.ts` - The entire diff command implementation
- `/openspec/specs/cli-diff/spec.md` - The diff command specification

### Files to Update
- `/src/cli/index.ts` - Remove diff command registration (lines 8, 84-96)
- `/package.json` - Remove jest-diff dependency
- `/README.md` - Remove diff command documentation
- `/openspec/README.md` - Remove diff command references
- Various documentation files mentioning `openspec diff`

### Migration Guide for Users

Users currently using `openspec diff` should transition to:

```bash
# Before
openspec diff add-feature

# After - view the change proposal
openspec show add-feature

# After - view only the deltas
openspec show add-feature --json --deltas-only

# After - use git for file comparisons
git diff openspec/specs openspec/changes/add-feature/specs
```

## Risks

- **User disruption**: Existing users may have workflows depending on the diff command
  - Mitigation: Provide clear migration guide and deprecation period
  
- **Loss of visual diff**: The colored, unified diff format will no longer be available
  - Mitigation: Users can use git diff or other tools for visual comparisons

## Success Metrics

- Successful removal with no broken dependencies
- Documentation updated to reflect the change
- Tests passing without the diff command
- Reduced package size from removing jest-diff dependency