How do I install the Architecture Review skill?

Run npx skillmds@latest add dcramer/architecture-review in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Architecture Review safe to use?

This skill has not completed SkillMD's automated safety review yet. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Architecture Review?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Architecture Review free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Architecture Review?

dcramer (@dcramer) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Architecture Review by dcramer — Agent Skill

Name: Architecture Review
Author: dcramer

File contents

/architecture-review

Staff-level codebase health review. Focus on macro-level structural issues that compound over time, not style preferences.

Five Review Dimensions

1. Module Complexity

Size: Flag files >500 lines; investigate >800 as monoliths
Responsibilities: >3 distinct concerns (validation, I/O, orchestration) signals splitting
Fan-out: Files importing 10+ modules may coordinate excessively

For oversized modules, propose specific splits with new file names.

2. Silent Failure Patterns

Swallowed exceptions returning defaults without logging
Empty returns ([], None) where callers can't distinguish "no results" from "failed"
Missing error callbacks on async operations
Silent fallbacks hiding upstream problems

Explain what information gets lost and how to surface it.

3. Type Safety Gaps

cast() or # type: ignore without runtime validation
Optional returns where None means both "not found" and "error"
Overly broad exception handling (except Exception)
Missing Pydantic validation at boundaries

Suggest type-safe alternatives.

4. Test Coverage Analysis

Untested critical paths (core logic, error handling)
Edge case gaps (empty inputs, boundaries)
Integration gaps where only unit tests exist
Bug fixes lacking corresponding tests

Prioritize by risk: untested hot paths > edge cases > utilities.

5. LLM-Friendliness

Docstring coverage on public functions
Clear naming without needing implementation context
Actionable error messages explaining problems and fixes
Configuration that's easy to misconfigure

Analysis Method

Map architecture: Read entry points, understand module structure
```
cat specs/subsystems.md
```

Find giants: Locate largest files

find src -name "*.py" -exec wc -l {} + | sort -rn | head -20

Trace error paths: Follow operation failures, identify where error info disappears
Audit type assertions: Search for cast(), # type: ignore, broad exceptions
```
rg "cast\(|type: ignore|except Exception" src/
```
Map test coverage: Compare test files against source
```
ls tests/ && ls src/ash/
```
Check subsystem boundaries: Verify import rules from specs/subsystems.md

Output Format

Executive Summary: 3-5 bullets on most impactful findings

Priority Issues: For each finding:

Problem: What's wrong and why it matters
Evidence: Specific files, line numbers, patterns
Recommendation: Concrete fix

What's Working Well: Architectural strengths to preserve

Severity Levels

critical: Causing active reliability problems
high: Compounding as codebase grows
medium: Worth fixing but not urgent
low: Nice-to-have

Exclusions

Do NOT report: style preferences, minor naming issues, single-line fixes, already-addressed issues.

---name: architecture-reviewdescription: Use when reviewing codebase health, finding structural issues, or auditing architecture quality before major changes---# /architecture-reviewStaff-level codebase health review. Focus on macro-level structural issues that compound over time, not style preferences.## Five Review Dimensions### 1. Module Complexity- **Size**: Flag files >500 lines; investigate >800 as monoliths- **Responsibilities**: >3 distinct concerns (validation, I/O, orchestration) signals splitting- **Fan-out**: Files importing 10+ modules may coordinate excessivelyFor oversized modules, propose specific splits with new file names.### 2. Silent Failure Patterns- Swallowed exceptions returning defaults without logging- Empty returns (`[]`, `None`) where callers can't distinguish "no results" from "failed"- Missing error callbacks on async operations- Silent fallbacks hiding upstream problemsExplain what information gets lost and how to surface it.### 3. Type Safety Gaps- `cast()` or `# type: ignore` without runtime validation- `Optional` returns where `None` means both "not found" and "error"- Overly broad exception handling (`except Exception`)- Missing Pydantic validation at boundariesSuggest type-safe alternatives.### 4. Test Coverage Analysis- Untested critical paths (core logic, error handling)- Edge case gaps (empty inputs, boundaries)- Integration gaps where only unit tests exist- Bug fixes lacking corresponding testsPrioritize by risk: untested hot paths > edge cases > utilities.### 5. LLM-Friendliness- Docstring coverage on public functions- Clear naming without needing implementation context- Actionable error messages explaining problems and fixes- Configuration that's easy to misconfigure## Analysis Method1. **Map architecture**: Read entry points, understand module structure ```bash cat specs/subsystems.md ```2. **Find giants**: Locate largest files ```bash find src -name "*.py" -exec wc -l {} + | sort -rn | head -20 ```3. **Trace error paths**: Follow operation failures, identify where error info disappears4. **Audit type assertions**: Search for `cast()`, `# type: ignore`, broad exceptions ```bash rg "cast\(|type: ignore|except Exception" src/ ```5. **Map test coverage**: Compare test files against source ```bash ls tests/ && ls src/ash/ ```6. **Check subsystem boundaries**: Verify import rules from `specs/subsystems.md`## Output Format**Executive Summary**: 3-5 bullets on most impactful findings**Priority Issues**: For each finding:- Problem: What's wrong and why it matters- Evidence: Specific files, line numbers, patterns- Recommendation: Concrete fix**What's Working Well**: Architectural strengths to preserve## Severity Levels- **critical**: Causing active reliability problems- **high**: Compounding as codebase grows- **medium**: Worth fixing but not urgent- **low**: Nice-to-have## ExclusionsDo NOT report: style preferences, minor naming issues, single-line fixes, already-addressed issues.

Frequently asked questions

Architecture Review