Xray

xray: see through an implementation plan as a visual HTML page

Turn a long markdown plan into one self-contained HTML page a reviewer can approve from: code-flow diagram, UI wireframes when UI changes, file tree with NEW/MODIFIED badges plus annotated key files, data model with per-field change flags, API/DTO tables, cloud resource cards, step timeline with reuse-before-add, and a Review tab with hard-to-reverse decisions, gaps, and an answerable question form. Output goes next to the plan and opens in the browser.

Invocation

/xray <path/to/plan.md>

• No argument → ask for the plan path. Stop.
• File missing → say so. Stop.
• Plan is trivial (one file, one sentence describes the diff) → say an xray adds nothing and stop.
• Output: same directory, same basename, .html. Overwrite if present.

Process

1. Read the plan in full. Title ≤70 chars from its H1; write a 1 to 3 sentence summary yourself.
2. Extract buckets. Drop a tab that has nothing (see slots.md, "Dropping a tab").

   Tab	What goes in
   Flow	Main runtime path or architecture shift the change makes
   UI	Wireframes of screens/states the plan changes. Only when rendered UI changes.
   Files	Every path mentioned + 3 to 8 annotated key files
   Data	Tables, models, schemas, migrations, fields, per-field changes
   APIs	Endpoints with auth + request/response DTOs and example JSON; internal DTOs
   Cloud	AWS or other cloud resources created or modified
   Steps	Ordered tasks: what each reuses, what it adds, how it is verified
   Review	Hard-to-reverse decisions, gaps, open questions as a form. Always.

3. Verify against the codebase. Batch into one or two shell commands.
   • Each file path: ls. Exists + plan modifies → mod. Missing + plan creates → new. Exists + plan creates → ship. Missing + plan says modify → miss.
   • Each miss: find . -name <basename> -not -path '*/node_modules/*'. Exactly one hit → record it as the real path. Zero or several → leave as miss.
   • Drift mode. If half or more of the files the plan creates are ship, the plan has already landed. Say so in the summary, use the shipped chip, badge key files by what shipped versus what was planned, and lead the Review questions with what to do with the document. Gaps then mean drift: files the code has that the plan omits, signatures that changed, tasks left unfinished.
   • Each existing type/table/route/helper the plan claims exists: one grep -r. Not found → unv.
   • For each step, grep for helpers or modules that already do what the step adds. Found → list under Reuses; missed by the plan → a gap.
   • Do not edit the plan.
4. Read key files. Pick 3 to 8 load-bearing files: existing files the plan changes, plus new files whose shape matters. Read only the region that changes (sed -n 'a,bp'), ≤150 lines per file. If the plan touches UI, also read the current shell/component so wireframes match real density and labels.
5. Fill the template. Read slots.md in this skill's directory. Copy template.html, replace every slot per that contract, write to the output path. Then grep -c '<!--' the output: only TAB: markers may remain.
6. Visual check. One pass:

   CH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
   for t in flow ui files review; do "$CH" --headless=new --disable-gpu --hide-scrollbars --window-size=1280,1400 --virtual-time-budget=8000 --screenshot=/tmp/vp-$t.png "file://<output>#$t" 2>/dev/null; done
   

   Look at each image. Fix overlap, empty tabs, unrendered mermaid, unreadable wireframes, missing nav. At most one fix-and-rescreenshot round. If Chrome is absent, skip and say so in the report.
7. Open: open <output.html>.
8. Report in 2 to 4 lines: output path, tabs rendered, count of gaps and miss/unv badges, and the one or two decisions the reviewer most needs to make. Ask them to answer the Review tab questions and paste the copied markdown back.

Budgets

Mermaid rules

Diagram errors fail silently. Keep syntax minimal:

• Quote every label: A["Create order handler"]. No parentheses, brackets, pipes, semicolons inside labels.
• Node ids: letters and digits only. subgraph ids too.
• erDiagram entity names UPPER_SNAKE; relationships only A ||--o{ B : label.
• No %% comments, click, or style lines.
• Prefer two-dimensional layouts (before/after subgraphs, layers, owners) over one long chain unless the thing really is a sequence.

Common mistakes