Branch Comparison & Specification Update

Expert full-stack analyst for branch diff analysis, impact assessment, and spec synchronization.

⚠️ MUST READ .claude/skills/shared/anti-hallucination-protocol.md — validation checkpoints, evidence chains, confidence levels

Phase 1: Branch Analysis

Build structured analysis in .ai/workspace/analysis/[comparison-name].md.

Git Change Detection

git diff --name-status [source]..[target]
git diff --stat [source]..[target]
git log --oneline [source]..[target]

Change Classification

For each changed file, document:

• filePath, changeType (A/M/D), impactLevel (Critical/High/Medium/Low)
• serviceContext (Frontend/Backend/Config/DB)
• Purpose: Feature, Bug Fix, Refactor

Related Files Discovery

For each changed file, find: importers, dependencies, test files, API consumers, UI components.

If file list exceeds 75, prioritize by impactLevel (Critical > High > Medium > Low).

Phase 2: Analysis & Planning

Code Review Analysis

• Strengths, weaknesses, security concerns, performance implications

Refactoring Recommendations

• Immediate improvements, structural changes, technical debt

Specification Update Plan

• New requirements discovered, test spec updates needed, documentation gaps

Phase 3: Approval Gate

CRITICAL: Present analysis and plan for approval before executing updates.

Phase 4: Execution

Update specification documents with: requirements, test specs, architecture docs, review findings.

Spec Update Mode

⚠️ MUST READ .claude/skills/branch-comparison/references/spec-update-workflow.md

Provides:

• Pattern-based discovery - grep patterns for finding spec files and cross-referencing
• Gap analysis template - Component | Specified | Implemented | Gap
• Update checklist - Entities, commands, queries, events, API endpoints
• 3 update patterns - Entity spec, command spec, API endpoint spec

Phase 5: Validation

Verify updated specifications accurately reflect all changes. Cross-reference:

# Verify all commands are documented
grep -r "class.*Command" --include="*.cs" -l  # Find implementations
grep -r "CommandName" docs/specifications/     # Check in specs

Guidelines

• Evidence-based: All updates grounded in concrete git diff output
• Comprehensive impact: Analyze direct and indirect effects, including cross-service
• Platform-aware: Respect CQRS, Clean Architecture, platform patterns
• Full traceability: Ensure links between code, requirements, and tests

IMPORTANT Task Planning Notes

• Always plan and break many small todo tasks
• Always add a final review todo task to review the works done at the end to find any fix or enhancement needed