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
1---2name: branch-comparison3description: Use when the user asks to compare branches, analyze git diffs, review changes, update specifications based on code changes, or sync specs with implementation. Triggers on keywords like "compare branches", "git diff", "what changed", "branch comparison", "spec update", "sync specs".4---5
6# Branch Comparison & Specification Update
7
8Expert full-stack analyst for branch diff analysis, impact assessment, and spec synchronization.
9
10**⚠️ MUST READ** `.claude/skills/shared/anti-hallucination-protocol.md` — validation checkpoints, evidence chains, confidence levels
11
12---
13
14## Phase 1: Branch Analysis
15
16Build structured analysis in `.ai/workspace/analysis/[comparison-name].md`.
17
18### Git Change Detection
19```bash
20git diff --name-status [source]..[target]
21git diff --stat [source]..[target]
22git log --oneline [source]..[target]
23```
24
25### Change Classification
26For each changed file, document:
27- `filePath`, `changeType` (A/M/D), `impactLevel` (Critical/High/Medium/Low)
28- `serviceContext` (Frontend/Backend/Config/DB)
29- Purpose: Feature, Bug Fix, Refactor
30
31### Related Files Discovery
32For each changed file, find: importers, dependencies, test files, API consumers, UI components.
33
34> If file list exceeds 75, prioritize by impactLevel (Critical > High > Medium > Low).
35
36## Phase 2: Analysis & Planning
37
38### Code Review Analysis
39- Strengths, weaknesses, security concerns, performance implications
40
41### Refactoring Recommendations
42- Immediate improvements, structural changes, technical debt
43
44### Specification Update Plan
45- New requirements discovered, test spec updates needed, documentation gaps
46
47## Phase 3: Approval Gate
48
49**CRITICAL**: Present analysis and plan for approval before executing updates.
50
51## Phase 4: Execution
52
53Update specification documents with: requirements, test specs, architecture docs, review findings.
54
55### Spec Update Mode
56**⚠️ MUST READ** `.claude/skills/branch-comparison/references/spec-update-workflow.md`
57
58Provides:
59- **Pattern-based discovery** - grep patterns for finding spec files and cross-referencing
60- **Gap analysis template** - Component | Specified | Implemented | Gap
61- **Update checklist** - Entities, commands, queries, events, API endpoints
62- **3 update patterns** - Entity spec, command spec, API endpoint spec
63
64## Phase 5: Validation
65
66Verify updated specifications accurately reflect all changes. Cross-reference:
67```bash
68# Verify all commands are documented
69grep -r "class.*Command" --include="*.cs" -l # Find implementations
70grep -r "CommandName" docs/specifications/ # Check in specs
71```
72
73## Guidelines
74
75- **Evidence-based**: All updates grounded in concrete `git diff` output
76- **Comprehensive impact**: Analyze direct and indirect effects, including cross-service
77- **Platform-aware**: Respect CQRS, Clean Architecture, platform patterns
78- **Full traceability**: Ensure links between code, requirements, and tests
79
80
81## IMPORTANT Task Planning Notes
82
83- Always plan and break many small todo tasks
84- Always add a final review todo task to review the works done at the end to find any fix or enhancement needed
majiayu000