architecture-pass

Scans one codebase subsystem with a deletion test to produce an architecture report.

Updated Mar 20, 2026
One-click install
npx skills add https://github.com/McGheeLab/McGheeLabWebsite --skill architecture-pass-mcgheelab
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: architecture-pass
Source: https://github.com/McGheeLab/McGheeLabWebsite/tree/main/.claude/skills/architecture-pass
Command: npx skills add https://github.com/McGheeLab/McGheeLabWebsite --skill architecture-pass-mcgheelab

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? Subsystems accumulate cruft over time: pass-through modules, stale names, and responsibilities that drift from their original purpose. This Skill runs a scheduled, low-frequency architectural review over one subsystem at a time and produces a report of deletion candidates, fold candidates, and interface drift — without touching any code. ## Core Features & Use Cases - Deletion test per module: For each module, asks whether deleting it would drop complexity, leave it unchanged, or spread it everywhere, classifying modules as deletion candidates, fold candidates, or load-bearing. - Interface drift detection: Flags modules whose current responsibility no longer matches their name or original purpose, proposing rename, split, or boundary fixes. - Structured report output: Writes an inventory table, verdicts, and 1–3 recommended follow-up cleanup plans to CodeLog/Architecture/architecture-pass-V{n}.md. - Use Case: Before a major refactor of the Tasks subsystem, run a quick pass to identify which of its modules are thin pass-throughs that can be folded into callers, then queue the cleanup as separate planned changes. ## Quick Start Run an architecture pass on the Tasks subsystem with a quick scope and write the report to the CodeLog.

Frequently Asked Questions about architecture-pass

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

FAQPage Schema
How do I run an architecture review on a codebase subsystem?

Pick one subsystem, inventory its modules with file paths, public surfaces, call-site counts, and line counts, then apply the deletion test to each module. Write the verdicts and follow-up recommendations into a report file without changing any code.

What is the deletion test for software modules?

The deletion test asks what happens to overall complexity if a module is removed. If complexity drops, the module is a deletion candidate; if it stays the same, it is a fold candidate; if complexity spreads everywhere, the module is load-bearing and should be kept.

When should I run an architecture pass?

Run it roughly every ten version bumps, before a major refactor, or when a subsystem feels heavy. Do not run it inside a bug fix, as part of every pull request, or across the whole repository at once.

Does an architecture pass modify or refactor code automatically?

No. The pass only produces a report with deletion candidates, fold candidates, and interface drift findings. Actual cleanup happens in separate follow-up plans, each with its own version bump and changelog entry.

What are the limitations of a deletion-test architecture review?

It does not cover style concerns like CSS naming, does not propose rewrites or cross-subsystem abstractions, and excludes Firestore rules and Cloud Functions unless explicitly requested. Unclear call sites are marked unknown rather than guessed.