architecture-introspector

Analyze software architectures with a 6-phase first-principles introspection process.

34|6|Updated Oct 25, 2025
One-click install
npx skills add https://github.com/mahidalhan/claude-hacks --skill architecture-introspector
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architecture-introspector
Source: https://github.com/mahidalhan/claude-hacks/tree/main/skills/architecture-introspector/skills/architecture-introspector
Command: npx skills add https://github.com/mahidalhan/claude-hacks --skill architecture-introspector

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Systematically analyze software architectures using first-principles thinking to identify unjustified complexity and guide principled deconstruction.

Core Features & Use Cases

  • Provides a rigorous framework (SpaceX 5-step methodology) to map current state, question requirements, delete unnecessary abstractions, simplify remaining design, accelerate delivery, and automate guardrails.
  • Helps identify technical debt, validate architectural decisions, and plan refactoring or modernization with a 2+ consumer or compelling reason criterion.
  • Supports onboarding to complex codebases and informed code reviews by challenging assumptions and exposing cargo-cult patterns.

Quick Start

Load the first-principles framework from references/first_principles_framework.md and start a 6-phase architecture introspection on the target system.

Frequently Asked Questions about architecture-introspector

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

FAQPage Schema
How do I analyze software architecture using first principles to identify unjustified complexity?

First-principles architecture analysis maps the current state, questions requirements, and deletes unnecessary abstractions to identify unjustified complexity. A 6-phase introspection process systematically deconstructs systems and exposes cargo-cult patterns for simplification.

What is the best way to review a complex codebase for refactoring and modernization?

Architecture reviews for refactoring and modernization apply a 2+ consumer or compelling reason criterion to validate decisions. The process generates an Architecture Introspection Report containing deletion candidates, simplification plans, and acceleration opportunities for complex codebases.

When do I need first-principles thinking for architecture reviews?

First-principles thinking is needed for architecture reviews when multiple stakeholders rely on architectural decisions or during onboarding to complex codebases. It challenges assumptions and validates technical debt systematically rather than accepting existing abstractions as necessary.

How to plan system-wide architecture refactoring and simplify remaining design?

System-wide architecture refactoring follows a 5-step methodology to map the current state, delete unnecessary abstractions, and simplify remaining design. The introspection process delivers an implementation plan with acceleration opportunities and automation candidates to guide principled deconstruction.

Can I use first-principles introspection to evaluate technical debt and cargo-cult patterns?

First-principles introspection evaluates technical debt and cargo-cult patterns by challenging assumptions and questioning requirements during code reviews. The 6-phase process identifies deletion candidates and exposes unjustified complexity that multiple stakeholders rely on for architectural decisions.