Complexity

# Executable spec for the /complexity skill — refactor-hotspot finder (domain role).
# /complexity analyzes code complexity and surfaces a FOCUSED set of refactor hotspots ranked
# by cyclomatic complexity, rather than dumping every function. With no path it scopes to recent
# changes. Hexagon: domain; consumes doc + standards; produces stdout; shared-kernel with
# standards. (soc-qk4b)

Feature: Complexity finds focused refactor hotspots
  As the refactor-targeting analyzer
  I want the most complex functions surfaced and ranked
  So that refactoring effort goes where complexity is highest

  Scenario: a path is analyzed for complexity hotspots
    When /complexity runs on a path
    Then it reports functions ranked by cyclomatic complexity (highest first)

  Scenario: no path scopes to recent changes
    When /complexity runs without a path argument
    Then it scopes the analysis to recently changed source files

  Scenario: the output is a focused hotspot list, not a full dump
    When the analysis completes
    Then it surfaces a focused set of refactor targets, not every function in the tree


#!/usr/bin/env bash
set -euo pipefail
SKILL_DIR="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0; FAIL=0
check() { if bash -c "$2"; then echo "PASS: $1"; PASS=$((PASS + 1)); else echo "FAIL: $1"; FAIL=$((FAIL + 1)); fi; }

check "SKILL.md exists" "[ -f '$SKILL_DIR/SKILL.md' ]"
check "SKILL.md has YAML frontmatter" "head -1 '$SKILL_DIR/SKILL.md' | grep -q '^---$'"
check "name is complexity" "grep -q '^name: complexity' '$SKILL_DIR/SKILL.md'"
check "mentions radon" "grep -qi 'radon' '$SKILL_DIR/SKILL.md'"
check "mentions gocyclo" "grep -qi 'gocyclo' '$SKILL_DIR/SKILL.md'"
check "mentions cyclomatic" "grep -qi 'cyclomatic' '$SKILL_DIR/SKILL.md'"
check "mentions complexity grades" "grep -q 'Grade' '$SKILL_DIR/SKILL.md'"

echo ""; echo "Results: $PASS passed, $FAIL failed"
[ $FAIL -eq 0 ] && exit 0 || exit 1


---
name: complexity
description: Find focused refactor hotspots.
practices:
- code-complete
- refactoring
hexagonal_role: domain
consumes:
- doc
- standards
produces:
- stdout
context_rel:
- kind: shared-kernel
  with: standards
skill_api_version: 1
context:
  window: fork
  intent:
    mode: task
  sections:
    exclude:
    - HISTORY
  intel_scope: topic
metadata:
  tier: execution
  dependencies:
  - standards
  - doc
output_contract: 'stdout: complexity metrics report'
---
# Complexity Skill

**YOU MUST EXECUTE THIS WORKFLOW. Do not just describe it.**

Analyze code complexity to identify refactoring targets.

## Execution Steps

Given `/complexity [path]`:

### Step 1: Determine Target

**If path provided:** Use it directly.

**If no path:** Use current directory or recent changes:
```bash
git diff --name-only HEAD~5 2>/dev/null | grep -E '\.(py|go)$' | head -10
```

### Step 2: Detect Language

```bash
# Check for Python files
ls *.py **/*.py 2>/dev/null | head -1 && echo "Python detected"

# Check for Go files
ls *.go **/*.go 2>/dev/null | head -1 && echo "Go detected"
```

### Step 3: Run Complexity Analysis

**For Python (using radon):**
```bash
# Check if radon is installed
which radon || pip install radon

# Run cyclomatic complexity
radon cc <path> -a -s

# Run maintainability index
radon mi <path> -s
```

**For Go (using gocyclo):**
```bash
# Check if gocyclo is installed
which gocyclo || go install github.com/fzipp/gocyclo/cmd/gocyclo@latest

# Run complexity analysis
gocyclo -over 10 <path>
```

### Step 4: Interpret Results

**Cyclomatic Complexity Grades:**

| Grade | CC Score | Meaning |
|-------|----------|---------|
| A | 1-5 | Low risk, simple |
| B | 6-10 | Moderate, manageable |
| C | 11-20 | High risk, complex |
| D | 21-30 | Very high risk |
| F | 31+ | Untestable, refactor now |

### Step 5: Identify Refactor Targets

List functions/methods that need attention:
- CC > 10: Should refactor
- CC > 20: Must refactor
- CC > 30: Critical, immediate action

### Step 6: Write Complexity Report

**Write to:** `.agents/