skills.rest
riethmayer
riethmayerCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

improve-codebase-architecture

Identify shallow seams and propose refactoring candidates from ADRs and domain glossaries.

2|1|Updated Oct 8, 2009
Search Tags:#architecture#codebase#refactor#ADR#domain-language#deepening
One-click install
npx skills add https://github.com/riethmayer/dotfiles --skill improve-codebase-architecture-riethmayer
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-codebase-architecture
Source: https://github.com/riethmayer/dotfiles/tree/main/stow/agents/.agents/skills/improve-codebase-architecture
Command: npx skills add https://github.com/riethmayer/dotfiles --skill improve-codebase-architecture-riethmayer

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Surface shallow seams in a codebase and align architecture with domain language to increase testability, AI-navigability, and maintainability.

Core Features & Use Cases

  • Explore the project's glossary and ADRs to identify shallow interfaces and high-friction seams.
  • Propose concrete deepening opportunities, including involved files, dependencies, and rationale for each candidate.
  • Frame problem space and suggested interfaces to guide ADRs and refactors, improving locality and testability.

Quick Start

Read CONTEXT.md and UBIQUITOUS_LANGUAGE.md, locate shallow seams, and generate three deepening candidates with impact estimates.

Frequently Asked Questions about improve-codebase-architecture

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I identify shallow seams in a codebase for refactoring?▼

Shallow seams are identified by analyzing your project's ADRs and domain glossary to surface high-friction interfaces. The Skill generates concrete deepening candidates with involved files, dependencies, and rationale to increase locality and testability.

What is codebase deepening and how does it improve architecture?▼

Codebase deepening increases interface leverage by aligning architecture with domain language. It surfaces shallow seams and frames problem spaces with suggested interfaces, improving testability, AI-navigability, and maintainability.

How do I prepare ADR candidates for a codebase refactor?▼

Generate ADR candidates by reading CONTEXT.md and UBIQUITOUS_LANGUAGE.md to locate shallow seams. The Skill outputs three structured deepening opportunities with problem statements, dependency categories, proposed solutions, and impact estimates.

Do I need existing ADRs and domain glossaries to analyze codebase architecture?▼

Yes, existing ADRs and domain glossaries are required. The Skill applies to projects with these documents to surface candidates, dependencies, and framed problem spaces ready for architectural decision records and refactoring discussions.

What's the best way to align codebase interfaces with domain language?▼

Align interfaces by exploring the project's ubiquitous language to identify high-friction seams. The Skill proposes deepening opportunities that frame problem spaces and suggest interfaces, guiding refactors to improve locality and testability.

Why does my codebase refactor fail to improve testability and maintainability?▼

Refactors fail when shallow seams remain undiscovered. By surfacing high-friction interfaces and proposing deepening candidates with dependency categories and rationale, the Skill ensures architecture aligns with domain language for better testability.

Related Skills

Explore More Software Engineering Skills→
flaviogragnolatiflaviogragnolati

improve-codebase-architecture

Identifies shallow modules in codebases and proposes refactoring strategies to deepen them.

Community
Intermediate
timurgaleevtimurgaleev
5

improve-arch

Identify architectural frictions and propose deep module refactor candidates.

Community
Advanced
CloudyWingCloudyWing

context-map

Generate change impact analyses and dependency maps for codebase modifications.

Community
Intermediate
botPhUbotPhU

refactoring-expert

Detect code smells and apply refactoring techniques without changing external behavior.

Community
Basic