Module Deepening Audit and Refactor RFC
Find costly module boundaries, compare three distinct interface redesigns, and produce a scoped refactor RFC with rollback.
Before & after
Same prompt, same agent — the only difference is the skill.
I took a look at your codebase and here are some observations: Your storage layer seems to have a lot of small helper functions that are called from many places. This could indicate tight coupling. You might consider consolidating some of this logic. A few general suggestions: - Consider extracting shared logic into a service layer - Look into the repository pattern for data access - Some of your modules could benefit from clearer boundaries - Adding interfaces would improve testability Would you like me to look at any of these areas in more detail?
DEEPENING CANDIDATES 1. storage/ — 14 exported functions, 9 callers each pass the same 3 args. Blast radius: 31 files. 2. auth/session — 4 files, one 11-line function. Blast radius: 6 files. 3. billing/webhooks — branching on event type in 3 places. Blast radius: 12 files. CONFUSIONS NOTED Why does storage.put() take a bucket AND a prefix when every caller derives the prefix from the bucket? → Chose #1. Three sub-agents designed competing interfaces: A — REPOSITORY SkillRepo.save(skill). Hides bucket/prefix entirely. 31 files touched, all mechanical. B — EVENT-SOURCED Emit StoredObject, project separately. Buys audit history. 31 files + a projection worker. C — PLAIN FUNCTIONS store(skill) / fetch(id). Smallest surface, no abstraction to learn. 31 files, deletes 200 lines. RECOMMENDATION — C, with A's naming. B's audit trail solves a problem you don't have yet. C removes the bucket/prefix confusion outright rather than hiding it. MIGRATION CHECKLIST 1. Add store()/fetch() alongside existing exports 2. Migrate callers directory by directory (7 commits) 3. Delete old exports once callers are zero 4. Drop the prefix arg from the config type Filed as refactor RFC issue #512, labeled architecture, ready for the PRD-to-issues pipeline.
About this skill
Your service layer keeps growing, but callers still have to understand every step underneath it. This audit finds boundaries that export complexity, compares three materially different ways to hide it, and turns the strongest design into a refactor RFC with a migration and rollback plan.
What it does
- Traces public interfaces through implementations and real callers to find repeated orchestration, leaking internals, and misleading contracts.
- Ranks numbered candidates by caller burden, change coupling, evidence strength, and migration blast radius.
- Uses three independent design agents when available, with distinct assignments that change ownership or control flow. Provides separate proposals directly when delegation is unavailable.
- Compares designs using the same caller scenarios, failure cases, invariants, and migration constraints.
- Produces one module-scoped RFC with proposed signatures, affected callers, behavior checks, staged migration, and rollback triggers.
- Prepares a GitHub issue body and files it when requested and access is available.
What you get
A prioritized candidate list followed by competing interface designs and a recommended refactor RFC. Findings identify inspected code locations and distinguish verified callers from estimated or unknown impact.
Best for
Engineers and technical leads reviewing a service, package, or repository after a feature surge, or investigating why a supposedly simple API keeps forcing callers to coordinate its internals.
SKILL.md preview
---
name: module-deepening-audit-and-refactor-rfc
description: >-
Audit module interfaces against implementations and callers to find exported complexity, compare three structurally different redesigns, and produce a scoped refactor RFC with migration and rollback. Use when the user says "audit our architecture", "find shallow modules", "our service layer is all wrappers", "this API makes every caller do the same dance", "my modules keep changing together", "compare deeper interfaces", or "turn this refactor into an RFC".
---
# Module Deepening Audit and Refactor RFC
… (sign up to view the full skill)More development skills
View all Development skills →Performance Bottleneck Profiling: Node, Python, Go
Classifies a slowdown, gives exact profiler commands, reads the output, and proves the fix with same-conditions p95/p99 numbers.
Feature Scaffolding with Working Tests
Turn a short feature spec into code, runnable tests, and integration wiring that match your existing project.
Feature Flag Rollouts and Kill Switches
Design staged flag rollouts, verify rollback paths, and audit flag debt with explicit defaults, gates, and retirement plans.
Microcontroller Firmware and RTOS Engineering
Build and debug MCU firmware with bounded ISR/RTOS timing, safe DMA ownership, and measured power budgets.