architecture-introspector

Files (2)

• SKILL.md
• first_principles_framework.md · references/

SKILL.md (first lines)

# Architecture Introspector

Systematically analyze software architectures using first principles thinking, applying SpaceX's 5-step engineering methodology combined with software modularity principles to identify unnecessary complexity, validate architectural decisions, and recommend improvements.

## Purpose

This skill provides a rigorous, principle-based framework for evaluating software architectures. It challenges inherited assumptions, identifies unjustified complexity, and applies the "delete first, optimize later" philosophy to architecture. The goal is to achieve simple, justified architectures where every component earns its existence through actual need rather than hypothetical future requirements.

## When to Use This Skill

Use this skill when:

- **Analyzing existing architectures** - Understanding whether current architectural patterns are justified
- **Evaluating architectural decisions** - Questioning whether a proposed abstraction/layer/pattern is necessary
- **Identifying technical debt** - Finding components that add complexity without proportional value
- **Planning refactoring efforts** - Determining what to delete, simplify, or consolidate
- **Onboarding to codebases** - Understanding architectural rationale and identifying areas for improvement
- **Code review of architectural changes** - Ensuring new abstractions meet the 2+ consumer threshold
- **Modernization efforts** - Deciding what to keep, kill, or consolidate during rewrites

## Core Philosophy

### SpaceX's 5-Step Engineering Methodology

1. **Question Every Requirement** - Trace decisions to their origins, challenge assumptions
2. **Delete the Part or Process** - Remove first, optimize never (if it shouldn't exist)
3. **Simplify and Optimize** - Only after deletion is complete
4. **Accelerate Cycle Time** - Speed up validated, simplified processes
5. **Automate** - Last step only, after deletion and simplification

### Software Modularity Principle

**"Modularity without reuse is bureaucracy"**

Extract and modularize based on actual needs (2+ consumers for services/helpers, 3+ for utilities), not hypothetical futures. Premature abstraction creates overhead without benefit.

## How to Use This Skill

### Step 1: Load the Framework

Read the comprehensive framework from `references/first_principles_framework.md`:

```
Read references/first_principles_framework.md
```

This document contains:
- Detailed explanation of all 5 SpaceX principles applied to architecture
- The modularity principle and 2-3 rule
- Anti-patterns to identify
- Decision frameworks
- Output format templates

### Step 2: Define the Introspection Scope

Clarify what is being analyzed:

- **System-wide architecture** - Entire application's structure
- **Subsystem/module** - Specific domain or layer
- **Specific pattern** - Particular architectural decision (e.g., "Should we extract this service?")
- **Feature implementation** - How a feature is architecturally structured

Ask the user:
- What architectural area should be analyzed?
- What specific concerns or questions exist?
- Are there performance issues, maintenance pain points, or complexity complaints?
- Is this exploratory or focused on a specific decision?

### Step 3: Apply the 6-Phase Introspection Process

Follow the process defined in `references/first_principles_framework.md`:

#### Phase 1: Map Current State
- Inventory all components, layers, and abstractions
- Count consumers for each abstraction (critical for deletion phase)
- Trace data/control flow
- Document original decisions and their rationale (if discoverable)

#### Phase 2: Question Requirements
- For each architectural element, ask "Who required this and why?"
- Validate assumptions against current reality
- Identify cargo-culted patterns (e.g., "We use microservices because Netflix does")
- Separate hard constraints (business/technical necessities) from soft constraints (preferences)

#### Phase 3: Delete
**Most important phase - if not occasionally adding things back, not deleting enough**

Identify deletion candidates:
- Abstractions with <2 consumers → Inline them
- Layers adding no value → Remove them
- Duplicated logic → Consolidate
- Unused features → Delete
- Premature generalizations → Simplify to specific need

Apply the modularity principle rigorously:
- Services/helpers with 1 consumer → Move logic into that consumer
- Utilities used <3 times → Inline
- Frameworks for single use case → Replace with simple solution

#### Phase 4: Simplify
**Only for components that survived deletion**

- Reduce cognitive complexity
- Unify similar patterns into a single approach
- Improve naming and contracts
- Lower the learning curve

#### Phase 5: Accelerate
- Identify architectural bottlenecks (deployment dependencies, approval gates)
- Reduce coupling to enable parallel development
- Shorten feedback loops
- Enable incremental deployment

#### Phase 6: Automate
**Only after deletion and simplification**

- Automate validated, simplified patterns
- Create guardrails for architectural principles (e.g., linters enforcing 2+ consumer rule)
- Generate boilerplate for necessary patterns

From mahidalhan/claude-hacks, MIT.

More from mahidalhan/claude-hacks