semantic-codebase-intelligence

Semantic Codebase Intelligence

Produce a deep structural analysis: what depends on what, where boundaries are, what's unused, and where complexity concentrates.

MANDATORY TELEMETRY: FIRST action → invoke ai-starter-pack-signal with skill_name: "semantic-codebase-intelligence" only, save returned run_id. On ANY exit → invoke again with same run_id + outcome. On cancel → outcome: "partial". Non-blocking — skip silently on failure.

When to Use

• Before a major refactor, migration, or modularization
• Investigating tight coupling, circular dependencies, or accidental complexity
• Answering "what would break if I change this?"

Distinction from Codebase Onboarding

Onboarding creates human-readable documentation. This skill creates structural intelligence — quantified coupling, cohesion, and dependency metrics for engineering decisions.

---

Process

Step 1: Scope and Discover

1. Determine scope — entire repo, a module, or a dependency chain from a given file
2. Detect tech stack — scan build/dependency files to identify languages, frameworks, and module system
3. Identify entry points — main files, exported APIs, service endpoints, CLI commands

Step 2: Map Components

For each major component/module, record: name, single-sentence purpose, key source files (5-8 max), public surface (exports/APIs), inward dependencies (what it depends ON), and outward dependencies (what depends on IT).

Step 3: Trace Dependencies

1. Build a dependency graph — use actual imports/requires/references for component-to-component edges
2. Identify layers — group by architectural role (presentation, business logic, data access, infrastructure, shared)
3. Detect violations — dependencies crossing layer boundaries in the wrong direction
4. Find circular dependencies — A → B → C → A chains
5. Locate architectural boundaries — where clear separations exist (or should exist)

Step 4: Coupling and Cohesion

Metric	Assessment
Afferent coupling (Ca)	Components depending on this one — high = core/risky
Efferent coupling (Ce)	Dependencies this component has — high = fragile
Instability (I)	Ce / (Ca + Ce) — 0 = stable, 1 = unstable
Cohesion	Do the module's parts serve a single purpose? High/Medium/Low