Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture.
git clone https://github.com/rohitg00/pro-workflow.git--- name: improve-architecture description: Audit an area of the codebase and propose the smallest structural moves that improve it - untangle boundaries, kill duplication, fix seams, break cycles. Produces a prioritized plan and decision records, not a rewrite. Use when a codebase feels tangled, hard to change, or is becoming a ball of mud, or when asked to improve or refactor architecture. user-invocable: true --- # improve-architecture Invest in the shape of the system a little at a time rather than paying for a rewrite later. This skill diagnoses and proposes; it does not rewrite on its own. ## Method 1. **Map first.** Get the current shape before judging it - entry points, modules, data flow, who calls whom. Reuse `module-map` for the one-screen view; do not skip to opinions. 2. **Find the strain.** Look for the load-bearing problems, not style nits: - God modules that everything imports and nothing can change safely. - Leaky boundaries - a module reaching into another's internals instead of its surface. - Duplicated logic that drifts (the same rule implemented three ways). - Wrong seams - the code is split where it does not bend and fused where it does. - Cyclic dependencies. - A shape that fights the domain (see `domain-modeling` - boundaries in code should track boundaries in the language). 3. **Propose the smallest move.** For each problem, the least change that relieves it: extract a boundary, collapse a duplicate, invert a dependency, move a seam. Prefer a sequence of safe steps over one big cut. 4. **Rank by leverage.** Order the moves by pain relieved over effort. Say which are safe now and which need a test net first (pair with `tdd`). 5. **Record the big calls.** For a structural change a future reader would question, write a decision record in `docs/decisions/NNNN-slug.md`: context, choice, alternatives rejected, why. ## Guardrails - Diagnose, do not rewrite. The deliverable is a plan the user approves before any code moves. - No churn for taste. A move must relieve a named strain; "cleaner" is not a reason. - Three similar lines beat a premature abstraction - do not trade duplication for indirection unless the duplication actually drifts. - Keep behavior fixed. Structural moves are refactors; land them behind green tests. ## Output A prioritized list: each item is the problem, the smallest move, the risk, and whether it needs a test net first. Plus decision records for the big moves. No code changes until the user picks what to do.
[{"step":"Identify the Target Area","action":"Specify the exact directory, module, or layer in your codebase you want audited (e.g., `src/services/auth/`, `packages/core/`). Use the prompt template with `[AREA_OF_CODEBASE]` and `[PROJECT_NAME]` placeholders.","tip":"Focus on areas with high churn, frequent bugs, or where new features are hard to add. Avoid auditing stable, rarely-changed code."},{"step":"Run the Audit","action":"Paste the prompt into your AI tool (Claude/ChatGPT) and provide the `[AREA_OF_CODEBASE]` and `[PROJECT_NAME]`. If your codebase is large, limit the scope to a specific module or layer.","tip":"For better results, share the codebase structure (e.g., a tree output of the directory) or key files. This helps the AI understand the context faster."},{"step":"Review and Prioritize","action":"Evaluate the AI's proposed plan. Look for changes that: (1) reduce duplication, (2) break cycles, (3) improve boundaries, or (4) make future changes easier. Prioritize based on impact vs. effort.","tip":"Use the AI's decision records to understand trade-offs. If a change seems risky, ask the AI for alternatives or smaller steps."},{"step":"Implement Incrementally","action":"Start with Phase 1 changes. Use the AI's prioritized plan as a guide. Track progress in your issue tracker (e.g., GitHub Projects, Jira).","tip":"Create a `DECISION.md` file in the audited area to document changes and reasoning for future maintainers. This builds institutional knowledge."},{"step":"Validate and Iterate","action":"After implementing a phase, measure the impact (e.g., reduced bugs, faster feature development). Use this data to adjust the plan for subsequent phases.","tip":"Share the results with your team in a retro. Discuss what worked and what didn’t to refine the approach for future audits."}]
No install command available. Check the GitHub repository for manual installation instructions.
git clone https://github.com/rohitg00/pro-workflow/tree/main/skills/improve-architectureCopy the install command above and run it in your terminal.
Launch Claude Code, Cursor, or your preferred AI coding agent.
Use the prompt template or examples below to test the skill.
Adapt the skill to your specific use case and workflow.
Audit the [AREA_OF_CODEBASE] in the [PROJECT_NAME] repository. Focus on structural issues like tangled boundaries, duplication, poor seams, or dependency cycles. Identify the smallest, highest-impact moves that improve the architecture without requiring a full rewrite. Provide a prioritized plan with decision records explaining trade-offs for each change. Focus on changes that make the codebase easier to extend and maintain in the next 3-6 months.
### Architecture Audit Report: `src/payment-gateway/` **Current State (v2.4.1):** The `payment-gateway` module handles 7 payment providers with 4 shared utilities (`logger.js`, `config-loader.js`, `error-handler.js`, `metrics.js`). These utilities are imported in 18 files, creating a dense dependency graph with 3 cycles: 1. `payment-processor.js` ↔ `error-handler.js` (via shared `ValidationError`) 2. `stripe-adapter.js` ↔ `metrics.js` ↔ `logger.js` 3. `paypal-adapter.js` ↔ `config-loader.js` ↔ `logger.js` **Top 3 Structural Issues:** 1. **Tangled Error Handling:** 4 files duplicate error handling logic for `ValidationError`, `NetworkError`, and `RateLimitError`. The `error-handler.js` utility is imported in 12 files, making changes risky. 2. **Shared Config Pollution:** `config-loader.js` loads all provider configs into a single object, causing 100+ config keys in one file. Changes to provider-specific settings require touching this file. 3. **Circular Dependencies:** The cycles above prevent safe module reordering and make testing harder. The `metrics.js` ↔ `logger.js` cycle is particularly problematic because it mixes observability with business logic. **Prioritized Improvement Plan:** **Phase 1 (Low Risk, High Impact) - Week 1-2:** - **Extract Provider-Specific Error Handlers:** Create `errors/` directory with provider-specific files (`stripe-errors.js`, `paypal-errors.js`). Move `ValidationError` to a shared `types/` directory. Update imports in 8 files. *Decision:* Avoid refactoring `error-handler.js` entirely to reduce scope. Trade-off: Slight duplication of error types but clearer boundaries. - **Split Config Loader:** Move provider-specific configs to `config/providers/` (e.g., `stripe.config.js`, `paypal.config.js`). Update `config-loader.js` to dynamically import configs. *Decision:* Keep a top-level `config.js` for global settings but deprecate the monolithic file. Trade-off: Slightly more files but better isolation. **Phase 2 (Medium Risk, Medium Impact) - Week 3-4:** - **Break `metrics.js` ↔ `logger.js` Cycle:** Move metrics-specific logging to `metrics-logger.js` and remove direct `logger.js` dependency. Update 6 files to use the new module. *Decision:* Accept temporary duplication of logging logic in `metrics-logger.js` for cleaner separation. Trade-off: 20 lines of duplicated code but no more circular dependencies. - **Introduce Adapter Interfaces:** Create `adapters/` directory with interfaces for each provider (e.g., `stripe-adapter.interface.js`). Update `payment-processor.js` to depend on interfaces, not concrete adapters. *Decision:* Use TypeScript interfaces for compile-time safety. Trade-off: Adds abstraction but enables easier mocking for tests. **Phase 3 (High Risk, Long-Term Impact) - Week 5+:** - **Replace `error-handler.js` with Provider-Specific Handlers:** Gradually migrate error handling to provider-specific files. Deprecate `error-handler.js` entirely. *Decision:* Requires coordination with other teams using the utility. Trade-off: More files but better maintainability. **Decision Records:** 1. **Provider-Specific Error Handlers:** Chosen over refactoring `error-handler.js` because it reduces risk and scope. The duplication is acceptable given the clarity gained. 2. **Dynamic Config Loading:** Selected to avoid breaking changes to existing deployments. The top-level `config.js` remains for backward compatibility. 3. **Adapter Interfaces:** Implemented to enable future provider swaps without touching `payment-processor.js`. The interface approach was preferred over dependency injection for simplicity. **Next Steps:** 1. Create a tracking issue for Phase 1 changes with subtasks for each provider. 2. Add a `DECISION.md` file in `src/payment-gateway/` to document these choices for future maintainers. 3. Schedule a retro after Phase 1 to review the impact on deployment frequency and bug rates.
skills-collection
Take a free 3-minute scan and get personalized AI skill recommendations.
Take free scan