Diff Analysis

Table of Contents

• Overview
• When to Use
• Activation Patterns
• 4-Step Methodology
• Exit Criteria

Diff Analysis Methodology

Overview

Structured method for analyzing changesets: categorize changes, assess risks, generate insights. Works for git diffs, configuration changes, API migrations, schema updates, or document revisions.

When To Use

• Extracting insights from raw change data
• Categorizing and prioritizing changes before code reviews
• Preparing release notes or changelogs
• Assessing migration scope and risk

When NOT To Use

• Quick context catchup - use catchup instead
• Full PR review - use review-core with pensive skills

Activation Patterns

Trigger Keywords: diff, changes, release notes, changelog, migration, impact, risk assessment

Auto-Load When: Git diffs present, change analysis requested, impact assessment needed.

Progressive Loading

Load modules based on workflow stage:

Always Load

• modules/semantic-categorization.md for change categorization workflow

Conditional Loading

• modules/risk-assessment-framework.md when risk assessment is needed
• modules/git-diff-patterns.md when working with git repositories

Integration

• Use sanctum:git-workspace-review for git data gathering
• Use imbue:proof-of-work for capturing analysis evidence
• Use imbue:structured-output for formatting final deliverables

Required TodoWrite Items

1. diff-analysis:baseline-established 2. diff-analysis:changes-categorized 3. diff-analysis:risks-assessed 4. diff-analysis:summary-prepared

Mark each item complete as you finish the corresponding step.

4-Step Methodology

Step 1: Establish Baseline (diff-analysis:baseline-established)

Define comparison scope: what states are being compared, boundary of analysis, and scale metrics.

For git contexts, load modules/git-diff-patterns.md. For other contexts, compare relevant artifacts.

Step 2: Categorize Changes (diff-analysis:changes-categorized)

Group changes by semantic type. Load modules/semantic-categorization.md for change categories, semantic categories, and prioritization.

Step 3: Assess Risks (diff-analysis:risks-assessed)

Evaluate impact. Load modules/risk-assessment-framework.md for risk indicators, levels, and scoring methodology.

Step 4: Prepare Summary (diff-analysis:summary-prepared)

Synthesize findings: theme, scope with counts, risk level, review focus, dependencies. Format for downstream consumption (PR descriptions, release notes, reviews).

Exit Criteria

• All TodoWrite items completed with categorized changes and risk assessment
• Downstream workflows have semantic understanding of the changeset
• Summary ready for appropriate consumption (review, release notes, planning)

Git Diff Patterns

Baseline Establishment

Define comparison scope in git repositories:

# Show latest commit for context
git log --oneline -1 HEAD

# Find common ancestor between branches
git merge-base HEAD main

# Show summary of changes between baseline and HEAD
git diff --stat <baseline>..HEAD | tail -1

# Count changed files
git diff --name-only <baseline>..HEAD | wc -l

Change Type Isolation

Use --diff-filter to focus on specific change categories:

git diff --name-only --diff-filter=A <baseline>  # Additions
git diff --name-only --diff-filter=M <baseline>  # Modifications
git diff --name-only --diff-filter=D <baseline>  # Deletions
git diff --name-only --diff-filter=R <baseline>  # Renames

Integration with Sanctum

Before running diff analysis on git repositories, use sanctum:git-workspace-review to gather repository context:

• Repository confirmation (pwd, branch)
• Status overview (staged vs unstaged)
• Diff statistics
• Diff details

Then proceed with imbue-specific semantic analysis and risk assessment.

Usage Pattern

1. Sanctum First: Use sanctum:git-workspace-review to gather raw git data 2. Imbue Second: Apply semantic categorization and risk assessment to findings 3. Evidence: Use imbue:proof-of-work to capture analysis artifacts 4. Output: Format with imbue:structured-output for downstream consumption

Risk Assessment Framework

Risk Indicators

Evaluate each change category for potential impact across these dimensions:

Breaking Changes

• Public API modifications (function signatures, return types)
• Schema changes (database, data structures, serialization formats)
• Contract alterations (protocols, interfaces, message formats)
• Dependency version changes with incompatible APIs

Security-Sensitive

• Authentication mechanisms or credential handling
• Authorization logic or permission checks
• Cryptography usage (encryption, hashing, signing)
• Input validation or sanitization
• Network communication or protocol handling

Data Integrity

• Database operations (writes, updates, migrations)
• State management logic
• Persistence logic or serialization
• Transaction handling
• Data validation or constraints

External Dependencies

• Third-party service integrations
• Library updates or version bumps
• API client changes
• Infrastructure dependencies (databases, queues, caches)

Performance-Critical

• Hot paths or frequently-executed code
• Caching mechanisms
• Resource allocation (memory, file handles, connections)
• Algorithmic changes in core operations

Risk Levels

Classify overall risk based on indicators:

• Low: Internal refactors, documentation updates, test additions with no production code changes
• Medium: Feature additions with detailed tests, non-breaking API extensions, configuration changes with rollback plans
• High: Breaking changes requiring coordination, security modifications, schema migrations, changes to critical paths

Test Coverage Flagging

Identify changes requiring additional testing attention:

• Untested Changes: New code or modifications without corresponding test updates
• Test-Only Changes: Test updates without production code (potential false positives)
• Coverage Gaps: High-risk changes with insufficient test scenarios
• Integration Points: Changes affecting external systems without integration tests

Risk Scoring Methodology

1. Identify Indicators: Note which risk dimensions apply to each change 2. Count High-Risk Indicators: Breaking, security, data integrity take precedence 3. Assess Test Coverage: Reduce risk level if detailed tests present 4. Consider Scope: Smaller, isolated changes generally lower risk than widespread modifications 5. Assign Level: Use conservative assessment (when in doubt, elevate risk)

Output Format

For each high or medium risk change:

• Change: Brief description
• Risk Level: Low/Medium/High
• Indicators: Which dimensions triggered the assessment
• Mitigation: What testing/review would reduce risk
• Dependencies: Related changes or prerequisite work

Semantic Categorization

Change Categories

Group changes by their structural nature:

• Additions: New capabilities, files, or entities introduced
• Modifications: Changes to existing behavior or structure
• Deletions: Removed capabilities or deprecated items
• Renames/Moves: Reorganization without functional change

Semantic Categories

Classify changes by their purpose and impact:

• Features: New user-facing capabilities or functionality
• Fixes: Corrections to existing behavior, bug resolutions
• Refactors: Structural improvements without behavior change
• Tests: Test coverage additions or modifications
• Documentation: Explanatory content, guides, or inline documentation changes
• Configuration: Settings, environment variables, infrastructure, or build configuration changes

Entity-Level Diff (Primary: sem)

When sem is available (see leyline:sem-integration), use entity-level diffs:

# Check sem availability
if command -v sem &>/dev/null; then
  sem diff --format json <baseline>
fi

This returns entities (functions, classes, methods) with change_type of added, modified, deleted, or renamed. Group by change_type to populate the structural categories above.

File-Level Diff (Fallback: git)

When sem is unavailable, use git's --diff-filter flag to isolate change types at file level:

git diff --name-only --diff-filter=A <baseline>  # Added files
git diff --name-only --diff-filter=M <baseline>  # Modified files
git diff --name-only --diff-filter=D <baseline>  # Deleted files
git diff --name-only --diff-filter=R <baseline>  # Renamed files

Cross-Cutting Changes

Identify changes that span multiple categories or subsystems:

• Feature additions that also update tests and documentation
• Refactors that touch multiple modules
• Configuration changes that affect multiple environments
• Breaking changes that require coordinated updates

Categorization Workflow

1. Structural First: Group by addition/modification/deletion 2. Semantic Second: Within each structural group, classify by purpose 3. Cross-Reference: Note changes that appear in multiple semantic categories 4. Prioritize: Order by impact (breaking > feature > fix > refactor)