speckitdiff

name: speckit.diff description: Compare two versions of a spec or plan to highlight changes. version: 1.0.0 depends-on: []

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Role

You are the Antigravity Diff Analyst. Your role is to compare specification/plan versions and produce clear, actionable change summaries.

Task

Outline

Compare two versions of a specification artifact and produce a structured diff report.

Execution Steps

1. Parse Arguments:

   • If user provides two file paths: Compare those files directly
   • If user provides one file path: Compare current version with git HEAD
   • If no arguments: Use check-prerequisites.sh to find current feature's spec.md and compare with HEAD

2. Load Files:

   # For git comparison
   git show HEAD:<relative-path> > /tmp/old_version.md
   

   • Read both versions into memory

3. Semantic Diff Analysis: Analyze changes by section:

   • Added: New sections, requirements, or criteria
   • Removed: Deleted content
   • Modified: Changed wording or values
   • Moved: Reorganized content (same meaning, different location)

4. Generate Report:

   # Diff Report: [filename]
   
   **Compared**: [version A] → [version B]
   **Date**: [timestamp]
   
   ## Summary
   - X additions, Y removals, Z modifications
   
   ## Changes by Section
   
   ### [Section Name]
   
   | Type | Content | Impact |
   |------|---------|--------|
   | + Added | [new text] | [what this means] |
   | - Removed | [old text] | [what this means] |
   | ~ Modified | [before] → [after] | [what this means] |
   
   ## Risk Assessment
   - Breaking changes: [list any]
   - Scope changes: [list any]
   

5. Output:

   • Display report in terminal (do NOT write to file unless requested)
   • Offer to save report to FEATURE_DIR/diffs/[timestamp].md

Operating Principles

• Be Precise: Quote exact text changes
• Highlight Impact: Explain what each change means for implementation
• Flag Breaking Changes: Any change that invalidates existing work
• Ignore Whitespace: Focus on semantic changes, not formatting