agentleFS
TrecekTrecek/useful-claude-skills/.claude/skills/audit-cohesion/SKILL.md

audit-cohesion

Skill1 starsChanged 8 months agoMITView on GitHub

Audit codebase for internal cohesion - how well components fit together and maintain consistent patterns. Distinct from audit-arch (which checks rule violations); this checks integration fitness and convergence. Use when user says "audit cohesion", "check cohesion", "cohesion audit", or "alignment check".

1 other project uses a version of this, 1 of them edited.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

12 rules. About 0 are common, 9 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈9

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After major refactors to verify integration fitness

    line 22
  2. Distinctive:

    Before planning new features to understand current alignment state

    line 23
  3. Distinctive:

    Update an existing report — always generate new

    line 29
  4. Distinctive:

    Use subagents for parallel exploration (one per cohesion dimension)

    line 33
  5. Very specific:

    All output goes under temp/audit-cohesion/ (create if needed)

    line 34
  6. Very specific:

    The report must be plan-ready: Every finding must contain enough detail that a /make-plan invocation can act on it without re-investigating …

    line 43
  7. Distinctive:

    Question: Do parallel structures maintain consistent patterns, or have they diverged?

    line 94
  8. Distinctive:

    Question: Do configuration-driven components stay synchronized with the behavior they control?

    line 281
  9. Distinctive:

    After all subagents return:

    line 391
  10. Very specific:

    Ensure temp/audit-cohesion/ exists (mkdir -p).

    line 403
  11. Distinctive:

    If report exceeds 500 lines, split into parts at natural dimension boundaries:

    line 409
  12. Distinctive:

    Test fixtures and cached responses

    line 466

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Cohesion Audit Skill

Audit the codebase for internal cohesion: how well components integrate and maintain consistent patterns across boundaries.

Key Distinction: audit-arch checks whether architectural rules are followed (violations). audit-cohesion checks whether components fit together (alignment, consistency, completeness). A codebase can pass all architectural rules yet still have poor cohesion — parallel structures that diverge, registries with missing entries, or scattered features.

When to Use

  • User says "audit cohesion", "check cohesion", "cohesion audit", "alignment check"
  • After major refactors to verify integration fitness
  • Before planning new features to understand current alignment state

Critical Constraints

NEVER:

  • Modify any source code files
  • Update an existing report — always generate new
  • Duplicate findings that belong in audit-arch (rule violations)

ALWAYS:

  • Use subagents for parallel exploration (one per cohesion dimension)
  • All output goes under temp/audit-cohesion/ (create if needed)
  • Final report: temp/audit-cohesion/cohesion_audit_{YYYY-MM-DD_HHMMSS}.md
  • Subagents must NOT create their own files — they return findings in their response text only
  • Score each dimension (STRONG, ADEQUATE, WEAK, FRACTURED)

Output Quality Standard

The report must be plan-ready. Every finding must contain enough detail that a /make-plan invocation can act on it without re-investigating the codebase.

ENUMERATE, do not summarize. The following are NOT acceptable findings:

Bad (anemic)Good (actionable)
"16 fields missing from registry"Table listing each missing field name, its source file:line, and suggested lifecycle category
"Several source modules without tests"Table listing each untested module path and what it does
"Export depth inconsistent"Table listing each symbol that requires deep imports, its deep path, and where consumers import it from
"48 files use broad exception handlers"Table listing each file:line, the exception type caught, and what it catches

Minimum per dimension: Each dimension section MUST contain:

  1. A findings table (markdown table with columns appropriate to the dimension)
  2. Specific file:line references for every gap, violation, or inconsistency
  3. Enough context that someone unfamiliar could locate and fix each issue

If a dimension has no findings (scores STRONG), still provide the evidence: what was checked, how many items passed, and key file paths examined.


Subagent Output Requirements

Each subagent MUST structure its response as:

## Dimension: C{N} — {Name}
### Score: {STRONG|ADEQUATE|WEAK|FRACTURED}

### Methodology
{What was searched, how many items checked, key directories examined}

### Findings Table
| {columns appropriate to dimension} |
|---|
| {row per finding} |

### Evidence
{For each finding, the specific file:line, what was expected, what was found}

### Compliant Patterns
{Specific examples of things that ARE working well, with file:line}

Subagents must NOT return prose summaries. They must return structured data (tables, lists with file:line). If a subagent returns "X items are inconsistent" without listing each item, the finding is incomplete and must be expanded before inclusion in the report.


Cohesion Dimensions

C1: Structural Symmetry

Question: Do parallel structures maintain consistent patterns, or have they diverged?

Audit Strategy:

  1. Directory-level comparison — produce a side-by-side table:
Directory/FileModule A Has?Module B Has?Symmetric?Notes
handlers/YesYesYes—
config.pyYes (single file)Yes (directory/)NONaming: BaseConfig vs ConfigManager

List ALL directories and key files, not just divergent ones.

  1. Repository pattern comparison — for each repository, verify:
RepositoryExtends Base?Has Interface?Has Factory Method?Method Pattern
  1. Node/handler implementation comparison — for each parallel pattern:
PatternModule A ImplementationModule B ImplementationConsistent?
  1. Template/config comparison:
Config TypeModule A PathModule B PathShared ComponentsDivergence

C2: Interface Completeness

Question: Are adapter, factory, and contract chains complete with no missing links?

Audit Strategy:

  1. Adapter field coverage — for each domain model field, verify adapter mapping:
FieldIn Adapter?External RepresentationBidirectional?
  1. Factory method coverage — for each entity model, verify factory access:
ModelHas Repository?Has Factory Method?Factory Method Name
  1. Contract test inventory — for each interface, verify contract exists:
InterfaceContract Test FileTests CountFull Surface Covered?
  1. Type boundary audit — find every place internal model instances cross boundaries:
Location (file:line)Model TypeDestinationViolation?

C3: Feature Locality

Question: Is related functionality co-located, or scattered across unrelated packages?

Audit Strategy:

  1. Feature file map — for each major feature, enumerate ALL participating files:
FeatureFile PathRole in FeaturePackage
Cachingsrc/module_a/cache.pyModule A cachingcore
Cachingsrc/module_b/cache/manager.pyModule B cachingcore
Cachinglib/shared/cache_base.pyBase abstractionshared

Audit the major cross-cutting features in the project.

  1. Shared utility audit — for each shared module, count its importers by package:
Shared ModuleTotal ImportersModule A OnlyModule B OnlySharedVerdict
lib/shared/scope.py8080Misplaced — module B only
  1. Import fan-in — list every module with 10+ importers:
ModuleImporter CountIs Shared Infrastructure?

C4: Naming Convention Consistency

Question: Are naming patterns consistent across the codebase?

Audit Strategy:

  1. Class suffix inventory — group all classes by their suffix pattern:
SuffixCountExamplesExceptions
*Repository27PlanRepository, PhaseRepository—
*Manager2CacheManager, StateManagerMixed naming strategy
  1. Method verb audit — for each verb used in repository/handler methods:
VerbCountFilesSynonym Conflicts
get_21832 filesNone
fetch_??Conflicts with get_?
  1. File naming audit — find files that break the dominant pattern:
FilePattern ExpectedPattern FoundLocation
  1. Enum audit:
Enum ClassValue StyleLocationConsistent?

C5: Test-Source Alignment

Question: Does the test structure mirror the source structure, with no orphans or gaps?

Audit Strategy:

  1. Source-to-test mapping — for EVERY source module, find its test:
Source ModuleTest FileExists?Test Count
src/module_a/handler.pytests/module_a/test_handler.pyYes12
lib/shared/utils.py—NO0

List ALL gaps — every source file without a corresponding test file.

  1. Orphan detection — test files whose source no longer exists:
Test FileExpected SourceSource Exists?
  1. Classification audit — tests in wrong directories:
Test FileCurrent DirExpected DirReason
  1. Stale fixture detection:
Fixture FileReferenced ByStill Valid?

C6: Registry & Catalog Completeness

Question: Are all registries, catalogs, or lookup tables internally consistent and complete?

Audit Strategy:

Identify all registry patterns in the project (plugin registries, command catalogs, event handler tables, route maps, enum registries, feature flags, etc.), then for each:

  1. Registry gap analysis — compare registered entries vs. implementations:
RegistryEntryImplementation Exists?Implementation LocationGap
CommandRegistryexportYescommands/export.py:12—
CommandRegistryimportNO—Missing implementation

List EVERY missing entry.

  1. Reverse gap analysis — implementations that should be registered but aren't:
ImplementationExpected RegistryRegistered?Location
  1. Registry consistency audit — registries with inconsistent entry formats:
RegistryEntryFormat ExpectedFormat FoundConsistent?
  1. Cross-registry consistency — where multiple registries must stay synchronized:
Primary Registry EntrySecondary RegistryAppears in Secondary?Gap

C7: Configuration-Driven Behavior Alignment

Question: Do configuration-driven components stay synchronized with the behavior they control?

Audit Strategy:

Identify all places where configuration (schemas, settings, flags, manifests) drives runtime behavior, then verify alignment:

  1. Config-to-handler mapping — for each config key/value that dispatches behavior:
Config Key/ValueHandler/BehaviorHandler Exists?Handler LocationGap
  1. Schema-to-model mapping — for each schema field, verify the consuming model:
Schema FieldConsumer ModelField Mapped?Type Match?Gap
  1. Dead configuration detection — config entries with no active consumer:
Config EntryAny Consumer Found?Last Modified
  1. Undocumented behavior detection — behavior not covered by any config schema:
Behavior (file:line)Config PathwayDocumented in Schema?

C8: Export Surface Coherence

Question: Are __init__.py exports (or equivalent) consistent, complete, and intentional?

Audit Strategy:

  1. Symbol accessibility audit — for key public symbols, check import depth:
SymbolShallow Import Available?Deep Import Required?Consumer Count
ConfigYesNo45
AppStateNofrom lib.schema.state.app_state import ...23

List EVERY symbol that requires deep imports but has 5+ consumers.

  1. __all__ consistency:
PackageHas __all__?__all__ CountActual Public SymbolsDelta
  1. Import pattern census — how do consumers actually import:
SymbolImport Variants FoundCount EachDominant Pattern
  1. Stale re-export detection:
Re-exportSource LocationTarget LocationTarget Exists?

C9: Error Handling Uniformity

Question: Are error patterns (exceptions, logging, error states) consistent across the codebase?

Audit Strategy:

  1. Exception class inventory:
Exception ClassBase ClassDefined InUsed In (files)Duplicate Elsewhere?

Flag duplicates (same name in different modules).

  1. Error state field comparison:
Error FieldIn Module A State?In Module B State?Same Semantics?
  1. Broad exception handler census — list EVERY except Exception or except BaseException:
File:LineException CaughtHandler ActionJustified?
  1. Logger initialization audit:
FileLogger PatternConsistent?

Audit Workflow

Step 1: Launch Parallel Subagents

Spawn subagents for each cohesion dimension. Each subagent MUST be instructed:

"You are conducting a thorough cohesion audit. Your output must be EXHAUSTIVE — enumerate every item, do not summarize. Return structured tables, not prose. Every finding needs a file:line reference. If you find 16 missing fields, list all 16 with their source locations. If you find 48 files with broad exception handlers, list all 48. Completeness is more important than brevity. This is a research task — DO NOT modify any code."

Grouping (spawn 5 subagents, dimensions grouped by relatedness):

SubagentDimensionsFocus
1C1, C4Structural symmetry + naming consistency (side-by-side comparison tables)
2C2, C8Interface completeness + export surface (adapter/factory chain verification)
3C3, C9Feature locality + error handling (file mapping + exception census)
4C5Test-source alignment (enumerate EVERY source module and its test status)
5C6, C7Registry completeness + config-driven behavior alignment (gap tables)

Step 2: Consolidate Findings

After all subagents return:

  1. Verify completeness — if a subagent returned summaries instead of enumerations, note it as an audit gap
  2. Collect findings per dimension into structured tables
  3. Assign dimension scores based on the enumerated data
  4. Compute overall cohesion score:
    • STRONG = 4, ADEQUATE = 3, WEAK = 2, FRACTURED = 1
    • Average across dimensions, weighted: C2 gets 2x weight (interface completeness is foundational)
  5. Identify cross-dimension patterns — same subsystem appearing as a gap in multiple dimensions

Step 3: Write Report

Ensure temp/audit-cohesion/ exists (mkdir -p).

Write to temp/audit-cohesion/cohesion_audit_{YYYY-MM-DD_HHMMSS}.md.

The report WILL be long. This is expected and correct — thoroughness over brevity.

If report exceeds 500 lines, split into parts at natural dimension boundaries:

  • _scorecard.md — scorecard, cross-dimension patterns, recommended focus areas
  • _c1_c4.md — dimensions C1 through C4 with full tables
  • _c5_c9.md — dimensions C5 through C9 with full tables

Each part must reference the other parts by filename.

Step 4: Output Summary to Terminal

Display:

  • Overall cohesion score (numeric + label)
  • Per-dimension score table
  • Top 5 most impactful findings (with file:line)
  • Report file path(s)

Report Structure

Each dimension section in the report MUST follow this structure:

## C{N}: {Dimension Name}

### Score: {STRONG|ADEQUATE|WEAK|FRACTURED}

### Methodology
- Directories examined: {list}
- Items checked: {count}
- Tools used: {grep patterns, glob patterns}

### Findings

#### {Finding Category 1}

| {Column Headers Appropriate to Finding} |
|---|
| {One row per item — EVERY item, not a sample} |

#### {Finding Category 2}
{... same pattern ...}

### Compliant Patterns
- {file:line} — {what's working well and why}

### Remediation Checklist
- [ ] {Specific action item with file path}
- [ ] {Next action item}

Exclusions

Do NOT flag:

  • Generated files (migrations, schema DDL)
  • Third-party vendored code
  • Test fixtures and cached responses
  • Temporary/debug files in temp/
  • Configuration template files in config/

Score Guidelines

STRONG: Components fit together cleanly. Patterns are consistent, interfaces are complete. No action needed.

ADEQUATE: Minor gaps or inconsistencies that don't impede development. Low-priority cleanup opportunities.

WEAK: Noticeable friction when working across components. Developers need tribal knowledge to navigate inconsistencies. Should be addressed in next refactor cycle.

FRACTURED: Components don't fit together. Patterns are inconsistent, interfaces have gaps. Active impediment to development. Requires dedicated remediation effort.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.