Architecture Review
This is a systematic approach to fixing messy codebases without making things worse. It walks you through mapping your current structure, identifying concrete problems like circular dependencies and god modules, then refactoring incrementally with tests validating each step. The references cover dependency graphs, migration patterns, and structural templates for different project types. What I appreciate here is the anti-rationalization guide, basically a list of excuses developers make to avoid cleaning up architecture debt. It's TypeScript/JavaScript focused but the patterns translate. Use this when your codebase has grown organically and new features are getting harder to ship because nobody knows where anything goes anymore.
- skills.sh installs
- 412
- GitHub stars
- 9
- last updated
- Aug 21, 2026
Install
$ npx -y skills add srstomp/pokayokay --skill architecture-review --agent claude-codeInstalls into .claude/skills of the current project.
Files
Architecture Review
Analyze, audit, and improve project structure.
Key Principles
- Measure before changing — Map structure and identify concrete issues before proposing changes
- Clear boundaries — Layers (UI, logic, data) separated with consistent dependency direction
- Colocation — Related code together; easy to find, change, and delete features
- Incremental migration — Refactor in phases, validate each step with tests
Quick Assessment
- No circular dependencies
- Consistent directory naming and grouping (by feature or by type)
- Single responsibility per file/module, reasonable file sizes (<500 lines)
- External dependencies isolated, shared code properly extracted
- New developers can navigate and find code for any feature easily
Quick Start Checklist
- Map current structure: directory tree, dependency graph, module boundaries
- Identify issues: circular deps, god modules, leaky abstractions, deep nesting
- Classify severity: critical (blocks dev), high (maintenance burden), medium/low (friction)
- Propose target structure with migration plan
- Execute incrementally, validating with tests after each move
References
Sponsors
Agent CaffeineSponsoredClose your lid, come back to finished work
SnugSponsoredThe clipboard manager for the AI eraPromote your product hereReach 125k+ visitors monthly
WaxSponsoredBlock anything with supervision, without erasing your iPhonePromote your product hereReach 125k+ visitors monthly
knobsSponsoredSee your site on any phone, any day, in any languageDetails
- Repository
- github.com/srstomp/pokayokay
- Categories
- Git & Pull Requests, Code Review & Quality, Productivity & Planning
- First seen
- Jun 3, 2026
Recommended
More Git & Pull Requests
cfo-reviewalirezarezvani/claude-skills/cs:cfo-review <plan> — Numerate-skeptic interrogation of any plan that touches money. Unit economics, runway, dilution, capital allocation. Use when a plan com411skills.sh installscto-reviewalirezarezvani/claude-skills/cs:cto-review <plan> — Architecture and scaling interrogation. Tech debt, scaling cliffs, team scaling, build-vs-buy. Use when committing to an architecture, p410skills.sh installs
ciso-reviewalirezarezvani/claude-skills/cs:ciso-review <plan> — Risk-paranoid interrogation of any plan that touches data, compliance, or production access. Use when launching features that handle cu397skills.sh installs
review-docstldraw/tldrawReview and improve tldraw SDK documentation against the voice and docs guides, scoring each article and iterating until it passes. Use when asked to review docs397skills.sh installs