husamql3/arch-review-skill/arch-review

Arch Review

Create a standalone HTML file that explains architectural changes from before to after. The artifact should help a reviewer understand what moved, why it moved, and where the new seams are.

Workflow

1. Establish the comparison base.

• If the user names a branch, commit, PR, diff, or file set, use that.
• Otherwise inspect git state and choose the safest obvious base: merge-base with the main branch, the previous commit, or unstaged changes.
• Completion criterion: every changed file in scope has a clear before/after source.

1. Inventory the architecture.

• Identify modules, packages, entry points, exported types, public functions, adapters, boundaries, and cross-module dependencies.
• Prefer static analysis tools already present in the repo; otherwise use rg, language-aware parsers, import graphs, and targeted file reads.
• Completion criterion: every changed module and every direct dependency crossing its boundary is accounted for.

1. Find the seams.

• Mark seams where policy meets IO, domain meets framework, sync meets async, external service adapters begin, or ownership boundaries change.
• For each seam, record the old shape, new shape, and who calls whom.
• Completion criterion: every new or removed boundary has an explanation tied to concrete files and symbols.

1. Capture signatures.

• List changed public function, class, method, component, hook, API route, command, event, or schema signatures.
• Include before and after forms when they differ.
• Completion criterion: every caller-visible contract change is represented.

1. Produce the HTML walkthrough.

• Save a single self-contained .html file unless the user asks otherwise.
• Include sections for summary, before architecture, after architecture, dependency changes, seams, signature changes, migration impact, risks, and open questions.
• Use Mermaid diagrams for module/dependency flows and sequence diagrams when call flow changed.
• Completion criterion: the file opens locally and the diagrams render from the included Mermaid CDN script.

1. Verify the artifact.

• Open or render the HTML when browser tooling is available.
• Check that diagrams are non-empty, labels fit, and changed files/symbols are traceable.
• Completion criterion: report the saved file path and any verification gaps.

HTML Requirements

• Use a readable technical-report layout, not a landing page.
• Include a table of contents.
• Use file paths and symbol names as anchors where useful.
• Prefer Mermaid for dependency graphs:
• flowchart LR for module dependencies.
• sequenceDiagram for runtime flows.
• classDiagram only when types/classes are central to the change.
• Keep Mermaid labels short; put details in nearby tables.
• Include a small legend for edge meanings such as calls, imports, emits, persists, or adapts.
• Do not claim intent that cannot be inferred from code or user context. Mark it as an inference or open question.

Question Discipline

Ask the user one question at a time only when code inspection cannot answer it. Provide a recommended answer with each question. Do not implement additional architecture changes unless the user explicitly asks.

Output Contract

The final response must include:

• The path to the generated HTML file.
• The comparison base used.
• A brief note on verification performed.
• Any open architectural questions left unresolved.