CLI Audit Tangle

Optimization: This skill uses on-demand loading. Heavy content lives in references/ and is loaded only when needed.

Language rule: Skill instructions are written in English. When generating user-facing output (reports, files, documentation), detect the project's primary language (from README, comments, docs, commit messages) and produce the output in that language. If the project is bilingual, ask the user which language to use before proceeding.

Audit Tangle — Code Topology Untangler

Detect structural spaghetti using call graph analysis, spectral graph theory, and network physics. Goes beyond line-level linters to find topological problems: god functions, circular dependencies, dead nodes, and suboptimal module cuts.

"Topoisomerase does not see the content of DNA — it sees its shape. A knot is a knot, whatever gene it carries."

Biological & physical mechanisms

Read references/analogies.md for extended analogies and mental models.

Three mathematical lenses

Read references/analysis-methods.md for detailed algorithms and interpretation.

Mitosis — Scale analysis to project size

S/M/L/XL semantics are canonical in ../shared/tiering.md — the table below specializes them to function-count thresholds and analysis depth.

Read references/analysis-methods.md for threshold calibration per tier.

Input

$ARGUMENTS is the target to analyze:

• File (src/core/mod.rs): analyze that file's functions and their call relationships
• Directory (src/): analyze all functions in scope
• Module name (auth, parser): focus on that module's internal + external calls
• CI/CD (.github/workflows/, .gitlab-ci.yml): analyze pipeline dependency graph
• Empty: analyze the entire project (code + CI if present)

Workflow

Step 0 — Detect language and tools

Check if tools are installed. If not, fall back to LSP-based analysis (grep for function definitions + call sites).

Step 1 — Build call graph

1. Extract all function/method definitions in scope
2. For each function, find all call sites (what it calls, what calls it)
3. Build adjacency matrix: M[i][j] = 1 if function i calls function j
4. Count: nodes (functions), edges (calls), density

Fallback if no call graph tool: Use grep/LSP to build the graph manually:

• Glob for function definitions
• For each function, grep for its name in all other files
• Build the adjacency list

Step 2 — Compute metrics per function

For each function node, compute:

Read references/analysis-methods.md for threshold calibration.

Step 3 — Topological analysis

3a — God function detection (Fire ants)

A god function = high in-degree + high out-degree + high betweenness centrality.

god_score = normalize(in_degree) × 0.3
          + normalize(out_degree) × 0.3
          + normalize(betweenness) × 0.4

Flag functions with god_score > 0.7.

3b — Cycle detection (Topoisomerase — cut sites)

Find all strongly connected components (Tarjan's algorithm). Each SCC with > 1 node = a circular dependency.

Quick symptom hints:

• ImportError: cannot import name X from partially initialized module Y → Python cycle (quasi-certain)
• CI job stuck "waiting" with free runners → needs deadlock
• Stack overflow at init → circular instantiation
• Build looping → hidden transitive dependency

Qualify each cycle found:

3c — Module boundary analysis (Fiedler vector)

If the project has module structure:

1. Build inter-module call graph (edges between modules)
2. Compute coupling (calls between modules) vs cohesion (calls within modules)
3. Flag modules where coupling > cohesion (they shouldn't be separate)
4. Flag modules where internal clusters suggest a split (Fiedler cut)

3d — Dead node detection (with competing hypotheses)

Functions with in-degree = 0 AND not an entry point (main, test, public API) = potentially dead code.

Mandatory: enumerate ≥3 competing hypotheses before flagging (inspired by scientific hypothesis-generation):

Only flag as dead if ALL 5 hypotheses are refuted. A finding without disproof is downgraded to "POTENTIALLY DEAD — confirm manually."

Read references/analysis-methods.md for detailed algorithms.

Step 3e — Detect anti-patterns

Read references/anti-patterns.md for the 8 named anti-patterns with detection heuristics. Flag each with severity and evidence.

Step 3f — CI/CD pipeline analysis (if applicable)

If .github/workflows/ or .gitlab-ci.yml exists:

1. Extract the needs/dependencies graph from all workflow files
2. Build adjacency list: job_A → [job_B, job_C]
3. Run cycle detection (Tarjan) on the job graph
4. Detect:
   • Deadlocks: circular needs chains
   • Bottleneck jobs: single job that blocks > 50% of downstream jobs
   • Redundant dependencies: needs that are already transitively satisfied
   • Workflow trigger cycles: workflow_run chains that loop

GitHub Actions detection:

grep -r "needs:" .github/workflows/ | grep -v "^#"
grep -r "workflow_run\|workflow_call" .github/workflows/

GitLab detection:

grep -A5 "needs:\|dependencies:" .gitlab-ci.yml | grep -v "^--$"

Step 4 — Classify refactoring recommendations

Read references/fix-patterns.md for concrete remediation patterns by language and domain.

Diagnostic checklist (quick self-check before reporting)

[ ] Graph built? (no eyeball diagnosis)
[ ] Cycles identified? (SCC located, not just "seems coupled")
[ ] Each cycle qualified? (hard / strong / god module)
[ ] Cut point identified? (interface / event / extraction)
[ ] Fix verifiable? (test, build, pipeline green)

Step 5 — Score and report

Output Format

# Tangle Audit — {project-name}

**Date:** {date}
**Scope:** {what was analyzed}
**Functions analyzed:** {N}
**Call edges:** {M}
**Graph density:** {density}%
**Tangle Score:** {X}/100 (lower = more tangled)

## Topology Summary

| Metric | Value | Status |
|--------|-------|--------|
| God functions (score > 0.7) | N | {OK / Warning / Critical} |
| Circular dependencies (SCCs) | N cycles | {OK / Warning / Critical} |
| Dead functions (in-degree = 0) | N | {Info} |
| Module coupling ratio | X:Y (coupling:cohesion) | {OK / Warning / Critical} |
| Max call chain depth | N | {OK / Warning / Critical} |

## God Functions (Fire ants)

| Function | In° | Out° | Betweenness | LOC | God Score | Action |
|----------|-----|------|-------------|-----|-----------|--------|
| `process_request()` | 23 | 15 | 0.82 | 340 | 0.91 | Type II: split |
| `validate()` | 12 | 8 | 0.71 | 180 | 0.74 | Type I: extract |

## Circular Dependencies (Topoisomerase cut sites)

| Cycle | Functions involved | Cut recommendation |
|-------|-------------------|-------------------|
| SCC-1 | `a() → b() → c() → a()` | Break at `c→a`: introduce trait |
| SCC-2 | `parse() ↔ validate()` | Merge or extract shared logic |

## Module Boundaries (Fiedler analysis)

| Module | Cohesion | Coupling | Ratio | Recommendation |
|--------|----------|----------|-------|---------------|
| `auth` | 45 calls | 12 calls | 3.8:1 | OK |
| `core` | 20 calls | 35 calls | 0.6:1 | Type II: split |

## Dead Functions (Apoptosis candidates)

| Function | File | Last modified | Confidence |
|----------|------|---------------|-----------|
| `old_handler()` | `src/api.rs:142` | 6 months ago | High |

## Anti-Patterns Detected

| # | Pattern | Severity | Evidence | Recommendation |
|---|---------|----------|----------|---------------|
| 1 | God Function | Critical | `process_request()`: god_score 0.91 | Type I: extract 3 sub-functions |
| 2 | Circular Dep | Critical | `parse ↔ validate` across modules | Introduce `Validator` trait |

## CI/CD Pipeline Topology (if applicable)

| Metric | Value | Status |
|--------|-------|--------|
| Workflow files | N | — |
| Total jobs | N | — |
| `needs` edges | N | — |
| Deadlocks (cycles) | N | {OK / Critical} |
| Bottleneck jobs (> 50% downstream) | N | {OK / Warning} |
| Max pipeline depth | N | {OK / Warning} |

| Issue | Jobs | Type | Recommendation |
|-------|------|------|---------------|
| Deadlock | `build-a ↔ test-b` | Cycle | Extract common `prepare` job |
| Bottleneck | `build` blocks 8/10 jobs | Hub | Parallelize with matrix strategy |

## Refactoring Roadmap

| # | Action | Type | Impact | Effort | Target |
|---|--------|------|--------|--------|--------|
| 1 | Split `process_request()` | Type II | High | Medium | `src/core.rs` |
| 2 | Break `parse↔validate` cycle | Decouple | High | Low | `src/parser.rs` |
| 3 | Remove `old_handler()` | Cleanup | Low | Low | `src/api.rs` |

Exported artefact — tangle-partition.json

In addition to the human-readable markdown report, always emit a machine-parseable partition file at .claude/tangle-partition.json in the project root. This artefact is the single point of contact between cli-audit-tangle and downstream skills — most importantly cli-forge-chef, which uses the Fiedler clusters to pre-assign commis to modules so that two commis never get tasks from the same cluster (file-exclusion by construction, not by runtime filter).

Schema:

{
  "version": 1,
  "generated_at": "2026-04-14T15:32:00Z",
  "scope": "src/",
  "tier": "M",
  "graph": {
    "nodes": 147,
    "edges": 312,
    "density": 0.014,
    "max_chain_depth": 6
  },
  "clusters": [
    {
      "id": "cluster-0",
      "label": "auth",
      "files": ["src/auth/mod.rs", "src/auth/jwt.rs", "src/auth/session.rs"],
      "functions": 28,
      "internal_edges": 45,
      "external_edges": 12,
      "cohesion_coupling_ratio": 3.75,
      "fiedler_sign": "negative",
      "boundary_functions": ["auth::verify_token"],
      "recommended_commis_hint": "one commis owns this cluster"
    },
    {
      "id": "cluster-1",
      "label": "api",
      "files": ["src/api/handlers.rs", "src/api/router.rs"],
      "functions": 34,
      "internal_edges": 61,
      "external_edges": 18,
      "cohesion_coupling_ratio": 3.39,
      "fiedler_sign": "positive",
      "boundary_functions": ["api::dispatch"],
      "recommended_commis_hint": "one commis owns this cluster"
    }
  ],
  "boundary_functions": [
    {
      "name": "auth::verify_token",
      "fiedler_value": 0.02,
      "reason": "near-zero Fiedler value — bridges auth and api clusters",
      "warning": "assigning a commis to this function pulls in both clusters — sequence instead of parallelize"
    }
  ],
  "god_functions": [
    {"name": "process_request", "god_score": 0.91, "action": "type_II_split"}
  ],
  "cycles": [
    {"id": "scc-1", "functions": ["parse", "validate"], "cut_point": "parse->validate", "fix": "introduce Validator trait"}
  ],
  "tangle_score": 67
}

Rules for the file:

• Always emit — even when the run is read-only or the report is skipped. The JSON is the cheap common denominator for other skills.
• Path is fixed — .claude/tangle-partition.json at project root. Do not invent per-run names. The chef reads the latest one.
• Clusters come from the Fiedler partition — recursive 2-way cuts until each cluster is below the tier threshold (see references/analysis-methods.md §"Module Boundary Analysis"). The fiedler_sign field lets downstream skills tell cluster membership from the sign change in the Fiedler vector without recomputing.
• Boundary functions are the functions whose Fiedler value is closer than 0.1 to zero (inclusive). They are the "frontier" nodes that belong to both sides — assigning them to a single commis pulls in both clusters, which is exactly the tangle the chef is trying to avoid.
• recommended_commis_hint — short free-form string the chef can read directly. Always one of: "one commis owns this cluster", "split across N commis — cluster too large", "sensitive zone — single commis, 3/3 quorum".
• Backward compatibility — bump version when the schema changes. Downstream skills read the version and refuse to consume an unknown major.

Scoring

tangle_score = 100
  - (god_function_count × 10)
  - (cycle_count × 15)
  - (modules_with_coupling_gt_cohesion × 10)
  - (max_chain_depth > 10 ? 10 : 0)
  - (dead_function_ratio > 0.1 ? 5 : 0)
  - (ci_deadlock_count × 15)
  - (ci_bottleneck_count × 5)
  clamped to [0, 100]

Rules for the Auditor

1. Topology over content. This skill sees the shape of the call graph, not the quality of the code inside functions. That's cli-audit-code's job.
2. Graph density matters. A 500-function project with 200 edges is sparse (good). With 5000 edges is dense (bad). Calibrate thresholds to project size.
3. Entry points are not god functions. main(), test functions, and public API endpoints naturally have high degree — exclude them from god function analysis.
4. Cycles between modules ≠ cycles within modules. Inter-module cycles are Type II (restructure). Intra-module cycles are often fine (mutual recursion).
5. Dead code needs confirmation. In-degree = 0 might mean: called via macro, reflection, FFI, or dynamic dispatch. Flag but don't assert.
6. Gotchas — read ../gotchas.md before producing output to avoid known mistakes.

Integration with other cli-* skills

Dynamic Handoffs

After your analysis, recommend these skills if conditions are met:

Rule: Recommend, don't auto-execute. Phrase as: "Consider running /cli-forge-pipeline — 2 CI deadlocks detected in the needs graph."

What this skill does NOT do

• Does not run code — static analysis only
• Does not fix code — it reports topology and recommends cuts
• Does not replace profilers — flamegraph finds hot paths at runtime, tangle finds structural knots at rest
• Does not check code quality — naming, DRY, style are cli-audit-code's domain