arch-scan

Files (2)

• SKILL.md
• deep-modules.md · references/

SKILL.md (first lines)

# Arch Scan

Turn architectural decay from a vague feeling into a ranked list of candidates. This is a survey, not a rescue.

1. Resolve scope before scanning. If the user named a module, subsystem, or pain point, use it. Otherwise read recent commit history (`git log --oneline`) and let recurring hot spots pull attention first; deepening pays off most where change keeps happening.
2. Read the resolved durable spec root (project convention, then `.agents/spec`, `.trellis/spec`, then `docs/spec`) before proposing anything. Settled decisions are context, not items to re-litigate.
3. Explore the scoped area for friction signals, using the vocabulary in [references/deep-modules.md](references/deep-modules.md):
   - understanding one concept requires bouncing between many small modules;
   - interfaces nearly as complex as their implementations (shallow modules);
   - extractions made purely for testability while the real bugs hide in how they are called (no locality);
   - tightly coupled logic leaking across seams.
4. Apply the deletion test to every suspect: deleting it should concentrate complexity in the survivors, not scatter it back across callers.
5. Write a self-contained Markdown report with Mermaid diagrams to the operating system's temporary directory, never into the workspace. For each candidate include: the files involved, the problem, a plain-language solution, benefits in terms of leverage and locality, a before/after diagram, and a recommendation strength (`strong`, `worth exploring`, or `speculative`). End with the single top recommendation and why.
6. If a candidate contradicts an existing durable spec, only surface it when the friction justifies reopening that decision, and mark the conflict explicitly.

Do not modify code, create repository files, or invoke another Skill. Report the absolute report path, the candidate count, and the top pick. Suggest `grill-me` on the chosen candidate as the next explicit action; the deepening work itself belongs to `to-spec` and `slice-spec`.

From JobsHwang/skills, MIT.

More from JobsHwang/skills