spec-diff

Skill: diff (Diff Awareness)

View precise .spec/ changes with collaborator attribution and divergence state tracking.

Parameters

• $ARGUMENTS: Optional diff range specifier:
  • --last or no argument: Smart default (see Step 3)
  • --commit=abc123: abc123~1..abc123 -- .spec/
  • --against=origin/main: origin/main..HEAD -- .spec/

Execution Steps

1. Read git config spec.member-code to determine current identity. Apply identity guard.
2. Read .spec/COLLABORATORS.md to determine collaborator directory mapping.
3. Parse $ARGUMENTS to determine the git diff range:
   • If --commit or --against specified → use that range directly.
   • If --last or no argument → smart default:
     1. Check git log @{u}..HEAD --oneline -- .spec/ for unpushed .spec/ commits.
     2. If unpushed commits exist → use @{u}..HEAD -- .spec/ (all local changes not yet pushed — most useful default).
     3. If no upstream or no unpushed commits → fallback to HEAD~1..HEAD -- .spec/.
     4. Display which range was used: 📎 Diff range: {range}.
4. Run the corresponding git diff command.
5. Output a structured diff summary grouped by member code:

   ### {code-1}
   - `design/{code-1}/file.md`: +{added} / -{deleted} lines
     Key changes: {summary of important content changes}
   
   ### {code-2}
   - (no changes)
   
   ### Core files
   - `THESIS.md`: +{added} / -{deleted} lines
     Key changes: {summary}
   

Step 6 — Divergence state transitions

If DIVERGENCES.md appears in the diff:

1. Parse the before/after content to detect state transitions.
2. Output a dedicated [Divergence State Transitions] section:

   ### Divergence State Transitions
   - D-001: `open` → `proposed` 🟡 (alice proposes: adopt REST API)
   - D-002: `proposed` → `resolved` ✅ (bob confirmed, decision: Kubernetes deployment)
   - D-003: `proposed` → `open` 🔴 (alice's proposal rejected by bob)
   

3. If no DIVERGENCES.md changes in the diff, skip this section.

Step 7 — Workflow impact analysis

Output:

• Whose documents were affected by whose changes
• Potential conflicts or synergies between collaborators
• Whether any changes conflict with THESIS.md
• Whether any changes affect open/proposed divergences (e.g., "alice modified design/alice/api.md, which is referenced in D-001 (open)")