# Untangle Codebase Dependencies and Refactoring Decisions

Scattered logic and hidden dependencies make routine changes harder to review and verify. This skill guides agents through structural analysis, grouped redesign decisions, and behavior checks.

## Install

```bash
npx skillstore add caldoai/untangle-codebase
```

## Metadata

- Status: approved
- Slug: caldoai-untangle-codebase
- Skillstore revision: r1
- Version status: missing
- Tree hash: 595992cacab8fbed504076fdcbcc5b95c61a17000ff93aa5341cd8bc83793a49
- Author: caldoai
- GitHub username: caldoai
- Repository: https://github.com/caldoai/skills/tree/f3cf47774975a7d9fca45730babf4ff7ad765ada/skills/untangle-codebase
- Ref: c993c6abcbffafea2683d7748b53b3dfaf438415
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands
- Quality score: 64
- Public page: https://skillstore.pages.dev/skills/caldoai-untangle-codebase
- Manifest: https://skillstore.pages.dev/api/skills/caldoai-untangle-codebase/manifest

## Capabilities

- Guides agents to identify hidden dependencies, unnecessary coupling, surplus code, and special cases.
- Organizes proposed structural fixes above the problems they address in a decision log.
- Asks users whether to include optional comment cleanup and test cleanup.
- Directs agents to implement redesigns and remove special cases that become unnecessary.
- Requests repeated subagent reviews and final checks that intended behavior remains unchanged.
- Recommends dependency graphs and Git history as evidence for architectural decisions.

## Use Cases

- Understand an Unfamiliar Repository: Document hidden dependencies and misplaced responsibilities before proposing changes to an inherited codebase.
- Consolidate Repeated Behavior: Group duplicated workflow logic and special cases under shared redesign decisions while preserving intended behavior.
- Review Architectural Boundaries: Use dependency relationships and change history to assess module ownership and prioritize coordinated structural improvements.

## Prompt Templates

### Start With a Problem Inventory

```
Use untangle-codebase to inspect this repository. Complete the options discussion and problem inventory, then pause before implementation.
```

### Focus on One Area

```
Use untangle-codebase on [area]. Keep comments and tests unchanged. Group structural fixes in a decision log and preserve behavior.
```

### Evaluate Shared Redesigns

```
Use untangle-codebase to analyze [workflow]. Compare dependency relationships and Git history, then propose shared fixes for related problems before implementation.
```

### Run a Controlled Refactoring Cycle

```
Use untangle-codebase within [scope]. Preserve existing user changes and source files during analysis. Implement approved decisions in reviewable batches with regression checks.
```

## Limitations

- Provides written workflow instructions, not bundled refactoring tools, graph generators, or test runners.
- Requires repository access and host support for tools and subagents to carry out the full workflow.
- Does not guarantee exhaustive issue detection or behavior preservation; results depend on agent judgment and test coverage.
- The skeleton-generation tip does not require a separate copy, so users should explicitly prohibit overwriting source files.

## Best Practices

- Agree on scope and optional cleanup choices before allowing implementation.
- Preserve user changes, and create any analysis skeletons separately without overwriting repository source.
- Review the decision log and run relevant regression checks after each structural change.

## Anti Patterns

- Treating every special case as removable without checking the requirement it protects.
- Removing comments or tests without the optional cleanup choice and a clear behavioral justification.
- Allowing repeated whole-repository redesign without checkpoints, scope limits, or behavior verification.

## Security Audit

- Audited at: 2026-11-06T15:33:11.636\+00:00
- Summary: All 29 static findings are false positives caused by Markdown backticks around examples, identifiers, and code fences. No evidence found of credential theft, data exfiltration, or prompt injection. One semantic risk concerns stripping function bodies without specifying a separate analysis copy, which could damage working source.

## Stats

- Views: 0
- Downloads: 0
- Favorites: 0
- Popularity score: 0