Business Conflict Analyzer

⚠️ IMPORTANT — Companion files (scripts/, references/) download automatically via fetch

Do NOT manually download, clone, or fetch any companion files from the GitHub repository. The fetch frontmatter above handles this automatically when the skill is loaded. Manually downloading files will override the automatic mechanism and may cause duplicates.

重要 — fetch 前奏会自动下载配套文件（scripts/、references/）

不要手动从 GitHub 下载、克隆或抓取任何配套文件。 上述 fetch 前奏会在 skill 加载时自动处理。手动下载会干扰自动机制，可能产生重复文件。

Business Conflict Analyzer / 业务冲突分析 Skill

Overview / 概述

This Skill is an inherent instinct of the AI coding assistant. While generating or modifying code, the AI spontaneously detects changes that affect external contracts (API upgrades, field changes, protocol changes), automatically triggers the analysis pipeline, and outputs a plain-business-language Impact Analysis Report for human decision-making.

本 Skill 是 AI 的"内置本能"。AI 在执行代码生成或修改任务时，自发感知到涉及外部依赖变更（API 升级、字段变更、协议变化），自动触发分析流程，输出纯业务语言的《影响分析报告》并推送人类决策。

Core idea / 核心理念: No human needs to manually navigate to any system to "start analysis" — the AI notices the change while writing code, analyzes it, pushes the report, and waits for a decision.

Trigger Conditions / 触发条件

The AI should auto-trigger this Skill when performing any of the following operations: AI 在执行以下任一操作时，应自动触发本 Skill：

Auto-Trigger / 自动触发（无需人类指令）

On-Demand / 按需触发（建议分析）

Analysis Pipeline / 分析流程

Step 1: Extract Diff / 提取差异

• Run scripts/diff_analyzer.py
• Input: git diff (or IDE changes)
• Output: Structured change manifest with file paths, change types (ADD/MODIFY/DELETE), symbols (field/method names), and granularity

Step 2: Map Impact / 映射影响

• Run scripts/impact_mapper.py
• Input: Step 1 structured manifest
• Core logic: Traverse each change, search project references, consult references/common_patterns.md
• Output: Impact matrix (consumer impacts, data compatibility, frontend/test impacts)

Step 3: Generate Report / 生成报告

• Run scripts/report_generator.py
• Input: Step 2 impact matrix
• Core logic: Translate technical language → business language
• Output: Plain-business-language Business Impact Analysis Report

Step 4: Push for Decision / 推送决策

• Report pushed directly to human (code review comment / IM / inline display)
• Wait for human feedback:
  • [1] Accept / 采纳 → AI proceeds with changes (see Post-Guard Follow-up Protocol and Auto-Fix below)
  • [2] Reject / 拒绝 → AI rolls back, records reason
  • [3] Revise / 修改建议 → AI adjusts approach based on feedback and re-analyzes

i18n: All three options support auto-detection via scripts/lang.py Translator._detect_lang() which checks system locale or LANG env var. Present options in the detected language ONLY — never show both languages. No extra user action needed.

Output Specification / 输出规范

Report Structure / 报告结构

## ⚠️ Business Impact Analysis Report / 业务影响分析报告

### Change Summary / 变更摘要
[One sentence: what changed]

### Change Details / 变更明细
[Per-file: tech change → business language translation]

### Impact Scope / 影响范围
[Affected features / services / data compatibility]

### Risk Assessment & Recommendation / 风险等级与建议
Risk level: High / Medium / Low

### Decision / 决策
_Options auto-translated — shown in detected language only (system locale or LANG env var). Example below is English; the actual output matches the user's system language._

> Reply with number:

- **[1] Accept** — proceed, auto-fix all impacted consumers
- **[2] Reject** — rollback change
- **[3] Revise** — adjust approach

Risk Levels / 风险等级

Translation Rules / 翻译规则

Resources / 配套资源

• scripts/diff_analyzer.py — Diff extraction / 差异提取
• scripts/impact_mapper.py — Impact mapping / 影响映射
• scripts/report_generator.py — Report generation / 报告生成
• references/common_patterns.md — Conflict pattern library / 常见冲突模式库

Guard Installation / Guard 安装

When the user says "帮我安装 commit guard" or similar, the AI should:

1. Locate install_hook.sh at .claude/skills/business-conflict-analyzer/scripts/install_hook.sh (relative to project root)
2. Run it directly:

bash .claude/skills/business-conflict-analyzer/scripts/install_hook.sh

This registers a PreToolUse hook (via .claude/settings.local.json) that intercepts git commit and runs conflict analysis.

When the user says "卸载 commit guard" or "uninstall the guard", delete the PreToolUse entry from .claude/settings.local.json:

# Remove the PreToolUse hook entry from settings.local.json

Note: commit_guard.py must exist at .claude/skills/business-conflict-analyzer/scripts/commit_guard.py for the hook to work. The fetch frontmatter in this SKILL.md ensures it's auto-downloaded when the skill loads.

Prerequisites / 前置依赖

AI should verify before calling scripts / AI 在调用脚本前应确认：

1. Current directory is a git repo root (git rev-parse --show-toplevel)
2. There are uncommitted or staged changes (git diff --stat)
3. Network is available (if using MCP extensions)

Error Handling / 错误处理

If any script fails, AI should / 如果任何脚本执行失败，AI 应：

1. Check environment / 检查环境: Verify Python + Git, current directory is git repo
2. Check changes / 检查变更: Verify git diff --stat has output
3. Fallback / 回退策略: If scripts error, AI can manually analyze git diff following this SKILL.md
4. Notify human / 反馈人类: Report error and ask whether to continue

Common errors / 常见错误：

Post-Guard Follow-up Protocol / 拦截后闭环追问

When commit_guard.py blocks a commit (P0 detected), the AI MUST automatically engage the user in a closed-loop decision. Do not just report the block and stop — proactively ask for a decision.

当 commit_guard.py 拦截了 commit（检测到 P0 破坏性变更），AI 必须自动发起闭环追问决策。不要只报告拦截结果就结束——要主动问用户怎么处理。

Protocol Steps / 协议步骤

commit_guard.py blocks commit
    ↓
AI reads conflict-report.md
    ↓
AI summarizes P0 findings in 1-2 sentences
    ↓
AI asks user: Accept / Reject / Revise?
    ↓
User decides → AI executes → AI verifies

Step 1: Acknowledge & Summarize / 告知与摘要

• Tell the user the commit was blocked by Business Conflict Analyzer
• Read conflict-report.md and give a 1-2 sentence summary of the P0 risk in business language
• Do not dump the full report — just the key finding

Example:

"Commit was blocked by Business Conflict Analyzer. The change removes UserDTO.mobile field which is consumed by Profile Service and Order Service — this will break their field mappings."

Step 2: Ask for Decision / 追问决策

Present three options clearly. Use the detected language (check LANG env var or conversation language). Show ONLY one language:

How would you like to proceed?

[1] **Accept** — proceed, I'll auto-apply compatibility mitigations
    (@Deprecated, route retention, fallback, calling-site updates)
[2] **Reject** — roll back the change, no action taken
[3] **Revise** — adjust approach (tell me what to change)

If the conversation is in Chinese, present in Chinese:

请选择处理方式：

[1] **采纳** — 继续执行，自动修复所有受影响引用方
[2] **拒绝** — 回滚变更，不做任何修改
[3] **修改建议** — 调整方案（告诉我怎么改）

Wait for user input — do not proceed without a decision.

Step 3: Execute / 执行决策

Based on user's choice:

Important: The AI should autonomously execute these actions — no additional user instruction needed. If the user says "1" or "Accept", the AI should immediately start applying mitigations.

Step 4: Verify / 验证

After any modification (mitigations applied or revision made):

1. Re-run the analysis pipeline (run diff_analyzer.py + impact_mapper.py + report_generator.py on current changes)
2. If clean → tell user "No P0 risks remain, you can commit now"
3. If still blocked → loop back to Step 2 with updated findings

Implementation Note / 实现说明

This protocol does not require changes to commit_guard.py. The hook already:

• Prints the report to stderr ✅
• Saves conflict-report.md to project root ✅
• Outputs JSON stop signal ✅

The AI reads conflict-report.md to re-engage the conversation. No additional Python code needed.

Auto-Fix Impacted Consumers / 引用方批量修复

After the user accepts a change (whether via the Post-Guard protocol or in normal conversation), the AI MUST automatically fix all impacted consumer sites identified by impact_mapper.py, not just the original code being changed.

用户确认采纳变更后（无论是通过拦截后闭环追问还是在正常对话中），AI 必须自动修复 impact_mapper.py 识别的所有受影响引用方，而不仅仅是原改动代码。

Why This Is Explicitly Enforced / 为什么显式要求

Protocol / 协议

Step 1: Collect Consumer Sites / 收集引用点

After user says "1" / "Accept" / "采纳" — or after the user chooses the Accept option in any language:

1. Read the impact analysis report or re-run impact_mapper.py
2. Extract the complete list of impacted consumer sites (file + line + symbol)
3. Build a fix plan: for each site, determine the corresponding change needed

Step 2: Auto-Fix All Sites / 批量自动修复

For each impacted consumer site, apply the matching fix automatically:

Important: Do not ask the user per-consumer. Fix all sites autonomously, then report the summary.

Step 3: Report Summary / 汇报结果

After all fixes are applied, report:

Auto-fix completed:
- 9 impacted consumers found
- 9 auto-fixed (getMobile() → getPhone()) ✅
- 0 skipped
- Compilation: verified clean

If some sites could not be auto-fixed (ambiguous change, or file outside project scope), list them explicitly as manual action items.

Performance / 性能说明

• impact_mapper.py uses grep for project reference search; large projects (>100K files) may take 5-10s
• grep automatically skips .git, node_modules, target, build directories
• For performance issues, restrict scope or use --since HEAD~1

Boundary Principles / 边界原则

1. Not a replacement for Rules / 不替代 Rule: Technical red lines (SQL injection prevention, security policies) are defined in CLAUDE.md
2. Not a replacement for Tests / 不替代测试: This Skill generates business conflict analysis, not test reports
3. Blocks only P0 / 仅拦截 P0: commit_guard.py blocks P0 (compile-breaking) changes only — lower-risk changes pass through and are reported without blocking. The human always has final say via the Accept/Reject/Revise loop.