upgrade-assessment

What this skill does

# Upgrade Assessment

Evaluate platform upgrade readiness for Claude model transitions, Claude Code version bumps, and OrchestKit plugin updates. Produces a structured JSON assessment report with a 0-10 readiness score across 6 dimensions.

## When to Use

- Before upgrading the Claude model (e.g., Sonnet 4 to Opus 4.8)
- Before upgrading Claude Code to a new major/minor version
- Before upgrading OrchestKit to a new major version
- When evaluating whether a team environment is ready for a platform change
- As part of release planning for model or platform migrations

## Quick Start

```bash
/ork:upgrade-assessment           # Interactive assessment
/ork:upgrade-assessment --json    # Machine-readable output
```

---

## 6-Phase Workflow

### Phase 0: Scope Definition

**Tool:** `AskUserQuestion`

Determine the assessment scope before scanning. Ask the user:

> What type of upgrade are you assessing?
> 1. **Full platform** - Model + CC version + OrchestKit (comprehensive)
> 2. **Model only** - Switching Claude model (e.g., Sonnet 4.5 to Opus 4.8)
> 3. **CC version only** - Claude Code version bump (e.g., 2.1.32 to 2.1.33)
> 4. **OrchestKit only** - Plugin version upgrade (e.g., 5.x to 6.x)

Record the scope and target versions. If the user does not specify target versions, research the latest available in Phase 2.

---

### Phase 1: Detection

**Tools:** `Bash`, `Read`, `Grep`, `Glob`

Run precondition checks and environment detection. Load details: `Read("${CLAUDE_SKILL_DIR}/rules/detection-checks.md")` for verification scripts and expected output format.

---

### Phase 2: Research

**Tools:** `WebSearch`, `WebFetch`

Research the target versions for new capabilities and breaking changes:

1. **Model changes:** Search for target model capabilities, breaking changes, new tool support
2. **CC version changes:** Search for changelog, new hook types, skill format changes, deprecated fields
3. **OrchestKit changes:** Read CHANGELOG.md, identify new/removed/renamed skills, hook migration needs

**Research queries:**
```
"Claude {target_model} capabilities release notes"
"Claude Code {target_version} changelog breaking changes"
"Claude {target_model} vs {current_model} differences"
```

---

### Phase 3: Codebase Scan

**Tools:** `Grep`, `Glob`, `Read`

Scan the codebase for patterns affected by the upgrade. Load details: `Read("${CLAUDE_SKILL_DIR}/rules/codebase-scan-patterns.md")` for grep patterns and severity classification.

---

### Phase 4: Scoring

Rate readiness 0-10 across 6 dimensions using the scoring rubric from `platform-upgrade-knowledge`. Load details: `Read("${CLAUDE_SKILL_DIR}/references/scoring-rubric.md")` for per-dimension thresholds, weights, and score interpretation.

---

### Phase 5: Recommendations

Generate prioritized action items based on Phase 3 findings and Phase 4 scores. Load details: `Read("${CLAUDE_SKILL_DIR}/references/recommendation-format.md")` for priority assignment algorithm, effort estimation, and recommendation structure.

---

## Output Format

The assessment produces a structured JSON report. Load details: `Read("${CLAUDE_SKILL_DIR}/references/output-format.md")` for the full schema and example.

---

## Execution Notes

### For Model-Only Upgrades
Focus on Phases 1, 2, and 3. Key areas:
- Agent `model:` fields
- Context window / output token assumptions
- Capability-dependent skill content (e.g., vision, audio)

### For CC Version Upgrades
Focus on hook compatibility and skill format:
- Hook type registry changes
- Skill frontmatter field additions/removals
- Permission rule format changes
- New built-in tools or removed tools

### For OrchestKit Upgrades
Focus on plugin structure:
- Manifest schema changes
- Build system changes
- Skill/agent rename or removal
- Hook source reorganization

---

## Rules Quick Reference

Load on demand with `Read("${CLAUDE_SKILL_DIR}/rules/<file>")`:

| Rule | Impact | What It Covers |
|------|--------|----------------|
| `detection-checks.md` | HIGH | Precondition checks, environment detection scripts |
| `codebase-scan-patterns.md` | HIGH | Grep patterns, severity classification |
| `knowledge-evaluation.md` | HIGH | 6-dimension scoring rubric, severity classification |
| `knowledge-compatibility.md` | HIGH | Version compatibility matrix, breaking change detection |

## Related Skills

- `platform-upgrade-knowledge` - Scoring rubric details and compatibility matrix
- `ork:doctor` - Post-upgrade health validation
- `ork:explore` - Codebase exploration for impact analysis
- `ork:verify` - Verification of changes after migration
- `ork:devops-deployment` - CI/CD pipeline updates

## References

Load on demand with `Read("${CLAUDE_SKILL_DIR}/references/<file>")`:

| File | Content |
|------|---------|
| `scoring-rubric.md` | Detailed dimension scoring thresholds |
| `recommendation-format.md` | Priority assignment and effort estimation |
| `output-format.md` | JSON report schema and example |

- See `platform-upgrade-knowledge/references/scoring-rubric.md` for additional scoring details
- See `platform-upgrade-knowledge/references/compatibility-matrix.md` for version compatibility tracking