skills.rest
ckallum
ckallumCOMMUNITY
Explore all skills by this author →
WebsiteGitHub

improve-architecture

Audit codebases to surface shallow modules and ADR-ready deepening opportunities.

Updated Feb 8, 2026
Search Tags:#architecture#codebase#adr#refactor#seams#deepening#domain-vocabulary
One-click install
npx skills add https://github.com/ckallum/calsuite --skill improve-architecture-ckallum
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: improve-architecture
Source: https://github.com/ckallum/calsuite/tree/main/skills/improve-architecture
Command: npx skills add https://github.com/ckallum/calsuite --skill improve-architecture-ckallum

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Identifies architectural friction in a codebase and surfaces opportunities to deepen modules, improving testability and AI navigability over time.

Core Features & Use Cases

  • Surface shallow modules and seams that increase cognitive load and change-cost.
  • Propose ADR-ready deepening opportunities aligned to the project's CONTEXT.md domain glossary.
  • Support scoped audits (path-level) or full-repo health checks, with traceable notes and ADRs.

Quick Start

Run /improve-architecture to scan your repository and surface deepening opportunities.

Frequently Asked Questions about improve-architecture

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

FAQPage Schema
How do I identify architectural friction and shallow modules in my codebase?▼

You can perform a full-repo health check or a scoped path-level audit to surface architectural friction, identifying shallow modules and seams that increase cognitive load and change-cost.

What are seams in software architecture and how do they affect codebase health?▼

Seams are structural points in a codebase that allow module isolation. Surfacing shallow seams through an architectural audit highlights areas where deepening modules can reduce cognitive load and change-cost.

How do I generate ADR-ready notes for a codebase refactoring effort?▼

Generate ADR-ready notes by auditing your codebase for deepening opportunities aligned to your domain vocabulary, outputting traceable observations and Architecture Decision Records candidates for refactor planning.

Do I need a CONTEXT.md and LANGUAGE.md file to audit my repository architecture?▼

Yes, auditing your repository architecture requires a CONTEXT.md file and docs/adr/ directory, and uses the domain vocabulary defined in LANGUAGE.md to align deepening opportunities with your project context.

Can I scope an architectural audit to a specific directory path instead of the full repository?▼

Yes, you can scope architectural audits to specific directory paths rather than running a full-repo health check, allowing targeted identification of shallow modules and seams within bounded codebase areas.

When should I surface deepening opportunities in my software architecture?▼

Surface deepening opportunities when architectural friction, such as shallow modules and seams, increases cognitive load and change-cost, degrading testability and navigability across your codebase over time.

Related Skills

Explore More Software Engineering Skills→
kos3nzkos3nz

improve-codebase-architecture

Analyze domain language and ADRs to identify codebase deepening opportunities.

Community
Advanced
alexandrbasisalexandrbasis
12

improve-codebase-architecture

Identify shallow modules and propose deep-module refactor opportunities during architecture reviews.

Community
Advanced
flaviogragnolatiflaviogragnolati

improve-codebase-architecture

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

Community
Intermediate
josavicentevwjosavicentevw
1

code-analysis

Analyze multi-language codebases for quality issues and generate remediation reports.

Community
Advanced