architecture-review_skill

Overview

This skill performs a staff-level architecture and health review of a TypeScript codebase, focusing on structural issues that compound over time. It finds monolithic modules, silent-failure patterns, type-safety gaps, test coverage holes, and LLM-friendliness problems. The goal is to produce prioritized, actionable recommendations with concrete file-splitting and validation plans.

How this skill works

I map entry points and directory responsibilities, locate oversized modules by line count and fan-out, trace error paths to find swallowed failures, and audit TypeScript casts and unsafe matches. I compare source files to test files to expose coverage gaps and sample public APIs for JSDoc and naming clarity. For each major finding I provide evidence, severity, and a concrete remediation plan (new filenames, responsibilities, and validation strategy).

When to use it

• Before major refactors or platform rewrites
• When adding new features that touch core orchestration
• After recurring production incidents with unclear root causes
• During quarterly technical debt triage and roadmap planning
• When preparing the codebase for AI-assisted development or tooling

Best practices

• Prioritize macro-level fixes: split responsibilities and reduce fan-out before micro-optimizations
• Replace silent fallbacks with explicit error channels and observability (logs, error types, metrics)
• Avoid unchecked as casts; add runtime validation or type predicates where input boundaries are unclear
• Target tests to cover hot paths and edge cases first; add integration tests for cross-module flows
• Document exported APIs with concise JSDoc and clear, actionable error messages for better LLM and human consumption

Example use cases

• Audit a large service file (>800 lines) and propose a 3-file split: orchestrator.ts, validation.ts, persistence.ts
• Locate and replace swallowed errors in async flows with Error types and logs/metrics
• Find unsafe regex and .match() usages and replace with guarded parsers and type predicates
• Map test coverage to critical business paths and recommend unit+integration tests for uncovered flows
• Improve exported function JSDoc and error messages to make the codebase LLM-friendly and reduce onboarding friction