Architecture Deepening Audit
Find shallow modules, surface confusions, and spawn sub-agents that each design a radically different deeper interface. Files the result as a refactor RFC issue.
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
name: architecture-deepening-audit description: Find shallow modules, surface confusions, and spawn sub-agents that each design a radically different deeper interface. Files the result as a refactor RFC issue. Use when working on architecture deepening audit.
Architecture Deepening Audit
Explores the codebase like a senior engineer, notes confusions, and presents numbered deepening candidates. Then spawns 3 or more sub-agents in parallel to design competing interfaces for the chosen module. Recommends the strongest, proposes hybrids, and files the result as a refactor RFC GitHub issue ready to feed into the PRD to issues pipeline. Use monthly or after a feature surge.
What you get
- Numbered deepening candidates
- Competing interface designs
- Recommendation with rationale
- GitHub RFC issue
- Blast-radius estimate per candidate
- Migration checklist
Customize your output
- Language: agnostic
- Sub-agent count: 3, 5, 7
- Repo scope: whole repo, single package, single dir
- Excluded paths: comma list
- Issue labels: comma list
- Risk tolerance: conservative, aggressive
Example output
Three interfaces for a bloated storage layer (repository pattern, event-sourced, plain functions) plus a hybrid recommendation, filed as issue 512.
Best for
Teams doing periodic architecture reviews with AI help.
Note: Requires human taste at the recommendation step. High confidence.
SKILL.md preview
---
name: architecture-deepening-audit
description: Use monthly or after a feature surge to find shallow modules, surface confusions, and spawn agents that each design a deeper interface.
version: 1.0.0
category: Engineering
author: AgentVolt
license: proprietary
tags:
- engineering
- p4
---
# Architecture Deepening Audit
Explores a codebase like a senior engineer on day one, hunting for shallow modules whose interface barely hides any complexity, then runs a competitive redesign for the worst offender.
## When to use
… (sign up to view the full skill)