cc-version-analysisCC CLI version upgrade impact analysis — research changes, analyze bkit impact, generate report. Triggers: cc-version-analysis, CC upgrade, version analysis
Independent GitHub snapshot · Automated classification · Original documentation governs
name: cc-version-analysis classification: workflow classification-reason: Orchestrates multi-phase research and analysis pipeline independent of model capability deprecation-risk: none effort: high description: | CC CLI version upgrade impact analysis — research changes, analyze bkit impact, generate report. Triggers: cc-version-analysis, CC upgrade, version analysis argument-hint: "[from_version] [to_version]" user-invocable: true
agents: research: bkit:cc-version-researcher analyze: bkit:bkit-impact-analyst report: bkit:report-generator
allowed-tools:
imports:
next-skill: pdca plan pdca-phase: null task-template: "[CC-Version-Analysis] CC v{from} → v{to}"
CC CLI 버전 업그레이드 시 bkit plugin에 대한 영향을 체계적으로 조사, 분석하고 개선 기회를 도출하는 전문 워크플로우 스킬.
이 스킬은 CC CLI의 새 버전이 출시되었을 때 다음을 자동화합니다:
Agent Team 구성:
cc-version-researcher: CC 버전 변경사항 외부 조사bkit-impact-analyst: bkit 내부 아키텍처 영향 분석report-generator: 최종 보고서 생성NEW (v2.1.16 errata learning — added 2026-05-20): Do NOT advance from Phase 1 → Phase 2 without completing the Phase 1.5 Raw Source Verification Gate. The cc-version-researcher agent's quantitative claims (bullet count, issue counts, file counts) MUST be cross-checked against ≥2 raw sources (GitHub release tag URL + raw CHANGELOG.md URL) before being adopted into the report. The v2.1.145 cycle leaked an unverified bullet count of 21 (actual: 20) and an unverified agent count of 36 (actual: 34) because this gate did not exist. If raw and agent disagree, raw wins.
/cc-version-analysis # Auto-detect: installed vs latest
/cc-version-analysis 2.1.78 2.1.85 # Specific version range
/cc-version-analysis to 2.1.85 # From current installed to target
┌─────────────────────────────────────────────────────┐
│ CC Version Analysis │
├─────────────────────────────────────────────────────┤
│ │
│ Phase 0: Setup & Version Detection │
│ ├── Detect installed CC version (claude --version) │
│ ├── Determine target version (args or latest) │
│ ├── Create Task tracking structure │
│ └── Load previous analysis from memory │
│ │
│ Phase 1: Research (cc-version-researcher agent) │
│ ├── Official docs (code.claude.com) │
│ ├── GitHub (anthropics/claude-code) │
│ │ ├── Releases & changelog │
│ │ ├── Issues (open & recently closed) │
│ │ ├── PRs (merged in version range) │
│ │ └── Commits (significant changes) │
│ ├── npm registry (@anthropic-ai/claude-code) │
│ ├── Technical blogs & community │
│ └── Output: CC Change Report (structured) │
│ │
│ Phase 1.5: Raw Source Verification Gate (MANDATORY) │
│ ├── WebFetch https://github.com/anthropics/ │
│ │ claude-code/releases/tag/v{to} │
│ ├── WebFetch https://raw.githubusercontent.com/ │
│ │ anthropics/claude-code/main/CHANGELOG.md │
│ ├── Cross-check agent's bullet count vs raw count │
│ ├── If mismatch → raw wins, record errata │
│ ├── Spot-check ≥3 random Fixed bullets verbatim │
│ └── Block Phase 2 if any mismatch unresolved │
│ │
│ Phase 2: Analyze (bkit-impact-analyst agent) │
│ ├── Map CC changes → bkit components │
│ ├── Identify ENH opportunities │
│ ├── File impact matrix │
│ ├── Philosophy compliance check │
│ ├── Test impact assessment │
│ └── Output: bkit Impact Analysis (structured) │
│ │
│ Phase 3: Brainstorm (Plan Plus methodology) │
│ ├── Intent discovery (핵심 목표/리스크/기회) │
│ ├── Alternative exploration │
│ ├── YAGNI review (각 ENH 필요성 검증) │
│ ├── Priority assignment (P0~P3) │
│ └── Output: Prioritized ENH roadmap │
│ │
│ Phase 4: Report Generation │
│ ├── Merge all phase outputs │
│ ├── Generate from template │
│ │ (cc-version-analysis.template.md) │
│ ├── Save to docs/04-report/features/ │
│ ├── Update MEMORY.md (version history) │
│ └── Output: Final Impact Report (Korean) │
│ │
└─────────────────────────────────────────────────────┘
1. Detect installed CC version:
$ claude --version
2. Determine target version:
- If args provided: use specified versions
- If no args: search for latest available version
3. Create Task structure:
TaskCreate: "[CC-Version-Analysis] CC v{from} → v{to}"
├── Task: "Phase 1: CC 변경사항 조사"
├── Task: "Phase 2: bkit 영향 분석"
├── Task: "Phase 3: Plan Plus 브레인스토밍"
└── Task: "Phase 4: 보고서 작성"
4. Load previous analysis context:
- Read memory/cc_version_history_*.md
- Read last ENH number from MEMORY.md
- Read existing PDCA status from .bkit/state/pdca-status.json
Input: from_version, to_version Output: Structured CC Change Report
Launch the cc-version-researcher agent with:
Research CC CLI changes from v{from} to v{to}.
Sources: official docs, GitHub (issues/PRs/releases), npm, blogs.
Categorize by: Breaking/Feature/Fix/Performance/SystemPrompt/Hook/Config.
Rate impact: HIGH/MEDIUM/LOW.
Flag bkit-relevant changes.
Output structured markdown tables.
Parallel research tasks (when using Agent Team):
Why: cc-version-researcher's output may paraphrase, summarize, or miscount. The v2.1.145 cycle revealed that a single WebFetch (via the model-processed release tag page) under-counted by 1 bullet (reported 6 Added, actual 7). A second fetch against raw CHANGELOG.md is required to catch this.
Protocol (main session, not delegated):
WebFetch https://github.com/anthropics/claude-code/releases/tag/v{to_version}
WebFetch https://raw.githubusercontent.com/anthropics/claude-code/main/CHANGELOG.md
Output: §3.0 Verification table appended to Phase 1 output:
| Field | Agent reported | Raw verified | Source URL | Verdict |
|---|---|---|---|---|
| Added | N | M | raw CHANGELOG | match / errata |
| Fixed | N | M | raw CHANGELOG | match / errata |
| Improved | N | M | raw CHANGELOG | match / errata |
| Breaking | N | M | raw CHANGELOG | match / errata |
| Total bullets | N | M | sum | match / errata |
Trigger: the range's CHANGELOG carries ≤ 1 bullet, OR its bullets are non-specific ("Bug fixes and reliability improvements"). CC v2.1.226 was the first instance and will not be the last.
Why this exists: an opaque release makes CHANGELOG-based analysis worth exactly nothing, and the cycle either invents an answer or measures one. Cycle #35 measured, and the measurement carried the whole report — but it took 15+ manual tool calls to re-derive a procedure nobody had written down, and it produced a false positive along the way (ERRATA-35-1) before catching it.
Procedure (main session, not delegated):
node scripts/cc-binary-equivalence.js <from> <to> (ENH-421). It reports
file size, sha256, Mach-O segment sizes, and exact grep -a -o -F counts for
every hook-contract marker, in one pass per build.__TEXT /
__DATA_CONST / __DATA with a moving __BUN means a payload swap, not a
native rebuild — a distinction the file size alone hides.Method rules, each of which cost a cycle:
strings set diff is NOT evidence. Trailing-byte artifacts
alone produced 1,315 added / 1,226 removed on two builds that turned out to be
equivalent. Only exact counts on the raw file count.- is parsed as an option by ugrep and
silently returns 0, which reads as absence. Use grep -a -o -F -e '<needle>'.runInBackground was 0 in three builds while
run_in_background was 49.cmp -l over two ~300 MB binaries exceeds a two-minute budget,
and cmp -n / -i return wrong results on this artifact. Do not use them.Binary provenance (ENH-422) — record these in the report and in the cycle memory, for every build examined. They scope the claim honestly and make cross-platform gaps trackable rather than invisible:
| Field | Where from |
|---|---|
| architecture | file <binary> (e.g. Mach-O 64-bit x86_64) |
| file size | stat / the script's table |
| sha256 | the script's table |
GIT_SHA, BUILD_TIME | the build banner inside the bundle |
| platforms NOT examined | stated explicitly |
The last row is the one that matters. GIT_SHA moving while the bundle does not
means upstream commits exist; the honest claim is "those commits did not change
the shipped macOS x86_64 bundle", never "there were no commits".
Input: Phase 1 CC Change Report PLUS Phase 1.5 verification table Output: bkit Impact Analysis
Pre-flight check before launching the analyst agent: the analyst will measure bkit architecture stats (agents/skills/hooks counts) via Bash. If the analyst proposes a numeric correction to memory (e.g. "agents 34 → 36"), the main session MUST re-run the measurement command independently before accepting it. See "Numeric Correction Protocol" in bkit-impact-analyst.md.
Launch the bkit-impact-analyst agent with:
Analyze bkit impact from these CC changes: {phase1_output}
Map each change to bkit components (agents/skills/hooks/lib/scripts).
Identify ENH opportunities starting from ENH-{last+1}.
Check philosophy compliance (Automation First, No Guessing, Docs=Code).
Assess test impact per ENH.
Analysis scope:
Input: Phase 2 Impact Analysis Output: Prioritized ENH Roadmap
Apply Plan Plus brainstorming phases:
Ask and answer:
For each HIGH/MEDIUM ENH:
Each ENH must pass:
Final priority based on:
Input: All phase outputs Output: Final Korean report in docs/
cc-version-analysis.template.mddocs/04-report/features/cc-v{from}-v{to}-impact-analysis.report.mddocs/01-plan/features/cc-v{from}-v{to}-impact-analysis.plan.mdmemory/cc_version_history_v{from}_v{to}.mdAll work MUST be tracked via Task Management System:
[CC-Version-Analysis] CC v{from} → v{to} # Parent task
├── [Research] Phase 1: CC 변경사항 조사 # cc-version-researcher
│ ├── GitHub releases 조사
│ ├── GitHub issues 조사
│ ├── 공식 문서 변경 조사
│ └── 시스템 프롬프트 변경 분석
├── [Analyze] Phase 2: bkit 영향 분석 # bkit-impact-analyst
│ ├── 컴포넌트 매핑
│ ├── ENH 기회 식별
│ ├── 파일 영향 매트릭스
│ └── 철학 준수 검증
├── [Brainstorm] Phase 3: 브레인스토밍 # Plan Plus
│ ├── 의도 탐색
│ ├── 대안 탐색
│ └── YAGNI 검토
└── [Report] Phase 4: 보고서 작성 # report-generator
├── 템플릿 기반 보고서 생성
├── MEMORY.md 업데이트
└── 최종 검토
When invoked with CTO Team (/pdca team):
| Role | Agent | Model | Task |
|---|---|---|---|
| Lead | cto-lead | fable | Overall orchestration |
| Researcher | cc-version-researcher | opus | Phase 1: CC research |
| Analyst | bkit-impact-analyst | opus | Phase 2: bkit analysis |
| Reporter | report-generator | haiku | Phase 4: Report writing |
Parallel execution:
Before completing, verify:
releases/tag/v{to})When raw verification catches a discrepancy with agent output, record it here to prevent repeat-mistakes and to feed future skill improvements.
| Field | Agent reported | Raw verified | Root cause |
|---|---|---|---|
| Bullet count | 21 (Features 7 + Fixes 13 + Improved 1) | 20 (Added 7 + Fixed 12 + Improved 1) | Agent over-counted Fixed by 1; first WebFetch on model-processed release page under-reported Added by 1 (raw CHANGELOG was authoritative) |
| Agents directory count | 36 (proposed correction from 34) | 34 (ls -1 agents/ | wc -l) | Analyst proposed unverified numeric correction; main session adopted without re-measurement |
| F7-145 background_tasks/session_crons | "extension surface" (no clear source citation) | Confirmed in raw CHANGELOG Added #7 verbatim | Single-source WebFetch had originally omitted this bullet; second raw fetch recovered it |
Lessons applied to skill (this commit):
This skill builds on established analysis patterns:
docs/04-report/features/claude-code-v2172-impact-analysis.report.mddocs/04-report/features/claude-code-v2178-impact-analysis.report.mdmemory/cc_version_history_v2134_v2172.mdAlways read previous reports first to maintain consistency in: