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 /autoskillit:make-plan invocation can act on it without re-investigating the codebase.

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

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:

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

2. Repository pattern comparison — for each repository, verify:

3. Node implementation comparison — for each node pattern:

4. Prompt template comparison:

C2: Interface Completeness

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

Audit Strategy:

1. Adapter field coverage — for each graph state field, verify adapter mapping:

2. Factory method coverage — for each table model, verify factory access:

3. Contract test inventory — for each interface, verify contract exists:

4. Type boundary audit — find every place SQLModel instances cross boundaries:

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:

Audit at minimum: checkpointing, work package execution, plan compilation, canvas sync, test framework detection.

2. SDK utility audit — for each SDK module, count its importers by package:

3. Import fan-in — list every module with 10+ importers:

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:

2. Method verb audit — for each verb used in repository/node methods:

3. File naming audit — find files that break the dominant pattern:

4. Enum audit:

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:

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

2. Orphan detection — test files whose source no longer exists:

3. Classification audit — tests in wrong directories:

4. Stale fixture detection:

C6: Registration Completeness

Question: Are all registries internally consistent and complete?

Audit Strategy:

1. Field registry gap analysis — compare state schema fields vs registry:

List EVERY missing field.

2. Phase registry audit:

3. Role registry vs prompt template audit:

4. DevToolRegistry audit:

C7: Prompt-Agent Alignment

Question: Do prompt templates match the agents and nodes that consume them?

Audit Strategy:

1. Template-consumer mapping — for EVERY template file, find its consumer:

2. Dead template detection:

3. Shared partial audit:

4. Inline prompt detection — nodes that bypass the template system:

C8: Export Surface Coherence

Question: Are __init__.py exports consistent, complete, and intentional?

Audit Strategy:

1. Symbol accessibility audit — for key public symbols, check import depth:

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

2. __all__ consistency:

3. Import pattern census — how do consumers actually import:

4. Stale re-export detection:

C9: Error Handling Uniformity

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

Audit Strategy:

1. Exception class inventory:

Flag duplicates (same name in different agents).

2. Error state field comparison:

3. Broad exception handler census — list EVERY except Exception or except BaseException:

4. Logger initialization audit:

Audit Workflow

Step 0: Initialize Code Index

mcp__code-index__set_project_path(path="{PROJECT_ROOT}")

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, one dimension each or grouped by relatedness):

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. (relative to the current working directory)

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 (Alembic migrations, PowerSync DDL)
• Third-party vendored code
• Test fixtures and cached LLM 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.