semantic-clusters

Semantic Clusters Skill

Version: 1.0 Created: 2026-02-11 Purpose: Map software systems by behavioral capabilities using action-verb clusters, revealing what a system does rather than where its files live.

---

I. The Philosophy: Behavior Over Location

Every codebase has two architectures:

1. The filesystem architecture -- where files live. Directories, packages, modules. This is what ls shows you.
2. The behavioral architecture -- what the system does. Capabilities that cross-cut directories, features that span layers.

Most people only see architecture #1. They think in terms of frontend/, backend/, utils/. But understanding comes from architecture #2 -- the verbs.

A "chat" feature isn't in one directory. It's a component in the frontend, a handler in the backend, a state engine in a context, a streaming service, an SSE connection, and a set of tools. These parts live in 6 different directories. But they all serve one verb: CONVERSE.

Semantic clusters make the behavioral architecture visible. Each cluster is named with an action verb, and every significant component in the codebase maps to one (sometimes two) clusters. The result is a map of what the system can do -- not just where its files happen to be.

This distinction matters because:

• Refactoring within a cluster is safer than refactoring across clusters. Components in the same cluster share a purpose; changing them together makes sense.
• Gaps become visible. If you have PERSIST but no PROTECT, you're storing data without security boundaries.
• Coupling is explicit. Cross-cluster components are integration points where changes propagate. You can see them in the map instead of discovering them during a production incident.
• Onboarding improves. "Let me explain what this system can DO" is a better orientation than "let me show you the directory tree."

---

II. When to Use This Skill

• Exploring a new codebase: Before diving into files, map the behavioral capabilities to build your mental model.
• Explaining a system: Clusters make better explanations than directory trees because they answer "what does it do?" not "where are the files?"
• Planning a refactor: Clusters reveal which components serve the same capability. Refactoring within a cluster is safer than across clusters.
• Auditing feature coverage: Clusters expose gaps -- capabilities the system lacks or has only partially implemented.
• Identifying architectural confusion: If a component maps to 3+ clusters, it's probably doing too much. If a directory has components in 5 different clusters, it may need restructuring.
• Writing status documents: The behavioral architecture section of a STATUS.md uses clusters.
• Sprint planning: Assign work by cluster. "This sprint we're focused on OBSERVE and PRESENT."
• Code review: Ask "which clusters does this PR touch?" A PR that modifies 4+ clusters deserves extra scrutiny.
• Technical debt tracking: Rate each cluster's health independently. Focus debt reduction on unhealthy clusters.