arch-lens

Analyze codebase architectural friction using Ousterhout's deep-module principle and generate RFC action files.

9|Updated Mar 13, 2026
One-click install
npx skills add https://github.com/psenger/ai-agent-skills --skill arch-lens
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: arch-lens
Source: https://github.com/psenger/ai-agent-skills/tree/main/skills/arch-lens
Command: npx skills add https://github.com/psenger/ai-agent-skills --skill arch-lens

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Explores codebase friction through Ousterhout's deep-module principle, enabling teams to identify shallow interfaces, hidden coupling, and testability seams for targeted RFC-driven improvements.

Core Features & Use Cases

  • Seven-step interactive architectural review workflow that navigates Explore, Candidates, Frame, and RFC creation.
  • Surfaces friction signals as actionable clusters with explicit dependency categories and testing impact.
  • Generates RFC action files (arch-rfcs-YYYY-MM-DD.md) and RFC-oriented design documentation for tracking in issue trackers.

Quick Start

Follow the seven-step arch-lens workflow by loading WORKFLOW.md, DETECTION-PATTERNS.md, INTERFACE-DESIGN.md and executing Steps 1–7.

Frequently Asked Questions about arch-lens

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

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

You can surface architectural friction by applying Ousterhout's deep-module principle to explore an entire repository or specific scope, which identifies shallow interfaces, hidden coupling, and testability seams for targeted improvements.

What is the best way to translate architectural code review findings into an RFC?

Translating architectural findings into an RFC involves a seven-step workflow that moves from exploration through candidate framing to RFC creation, generating dated RFC action files and structured design documentation for issue trackers.

How does Ousterhout's deep-module principle apply to software architecture reviews?

Ousterhout's deep-module principle applies to architecture reviews by evaluating module interfaces against their underlying implementation complexity. It helps surface shallow modules that lack abstraction, highlighting areas needing design improvements through targeted RFCs.

Can I scope an architectural review to specific directories instead of an entire repository?

Yes, architectural reviews can be scoped to user-specified boundaries instead of exploring an entire repository. This allows teams to target specific modules, surface localized hidden coupling, and generate focused RFC action files for those areas.

What does an RFC action file generated from an architectural review contain?

An RFC action file generated from an architectural review contains structured guidance for design, testing strategy, and documentation. It tracks identified friction signals, dependency categories, and testing impacts to drive safe architectural changes in issue trackers.

When should I use a structured workflow for codebase architecture refactoring?

A structured workflow for codebase architecture refactoring should be used when you need to safely navigate hidden coupling and testability seams. It provides a seven-step process that frames issues and produces RFCs to guide secure design changes.