Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
fix(skill): guide coherent repairs after visual acceptance fails
tt-a1ieeac3d0798ec
diff --git a/archify.zip b/archify.zipindex f7f4054b..6446861d 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex bf6a46fd..ab549f8e 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -39,7 +39,7 @@ Use this bounded path for ordinary generation. Do not read the optional Viewer RA passing receipt proves that the included `validate`, `deliver`, strict `check`, and deterministic real-browser `browser-check` gates passed. Do not read its full sidecar or rerun individual commands afterward; use a standalone command only for an explicitly separate execution or focused failure diagnosis.-5. A non-zero exit is never success. Use its compact stdout or `evidence.summaryReceipt`; read the full receipt only if the summary is truncated and lacks enough evidence for a coherent repair. After a validation failure, edit the connected neighborhood named by the evidence in one coherent change. When several affected routes share nodes, reposition those nodes and their neighbors together before adjusting individual lines; reserve isolated side or label controls for an isolated remaining defect. Keep unrelated geometry intact. Do not run validate, layout, render, or finalize first; edit the existing JSON in place. Geometry never authorizes deleting or merging a source-backed component, relationship, reference, view, card, boundary, or semantic label; reroute, reposition, or add readable canvas space instead. After the edit, rerun the complete `finalize` command from step 4 once, retaining `--quality showcase` and `--repo-root <repo-root>` for repository-backed candidates. After editing, omit any earlier `--candidate-sha256`: it binds the previous candidate. Use `--layout-json` before the edit only when compact evidence lacks needed geometry. A receipt with only 4 artifact checks is basic validation: require all 9 checks with 0 composition errors and 0 warnings. Fix `meta.quality_profile` before geometry. For workflow v2, use the stable compiler receipt; solver internals are not authoring controls. Use standalone `validate` only for focused diagnosis, with `--repo-root <repo-root>` for a repository. A passing validation returns `candidateFrozen: true`; do not edit, revalidate, or reread it. Run its `nextAction.arguments`, replacing only `<output.html>`. Retry later environment or evidence failures against the frozen candidate. If measured evidence requires a source edit, treat it as a new candidate and rerun the complete `finalize` command without the old hash. If one issue survives two focused repairs, inspect measured geometry or the relevant contract; after one evidence-based retry, stop truthfully. A lower error count never justifies changing meaning.+5. A non-zero exit is never success. Use its compact stdout or `evidence.summaryReceipt`; read the full receipt only if the summary is truncated and lacks enough evidence for a coherent repair. After a validation failure, edit the connected neighborhood named by the evidence in one coherent change. When several affected routes share nodes, read [Architecture layout repair](references/architecture-layout-repair.md) for Architecture, then reposition those nodes and their neighbors together. Choose endpoint sides for the main rail and return corridors as part of that same repair; reserve detailed waypoints or label overrides for an isolated remaining defect. Keep unrelated geometry intact. Do not run validate, layout, render, or finalize first; edit the existing JSON in place. Geometry never authorizes deleting or merging a source-backed component, relationship, reference, view, card, boundary, or semantic label; reroute, reposition, or add readable canvas space instead. After the edit, rerun the complete `finalize` command from step 4 once, retaining `--quality showcase` and `--repo-root <repo-root>` for repository-backed candidates. After editing, omit any earlier `--candidate-sha256`: it binds the previous candidate. Use `--layout-json` before the edit only when compact evidence lacks needed geometry. A receipt with only 4 artifact checks is basic validation: require all 9 checks with 0 composition errors and 0 warnings. Fix `meta.quality_profile` before geometry. For workflow v2, use the stable compiler receipt; solver internals are not authoring controls. Use standalone `validate` only for focused diagnosis, with `--repo-root <repo-root>` for a repository. A passing validation returns `candidateFrozen: true`; do not edit, revalidate, or reread it. Run its `nextAction.arguments`, replacing only `<output.html>`. Retry later environment or evidence failures against the frozen candidate. If measured evidence requires a source edit, treat it as a new candidate and rerun the complete `finalize` command without the old hash. If one issue survives two focused repairs, inspect measured geometry or the relevant contract; after one evidence-based retry, stop truthfully. A lower error count never justifies changing meaning.## Update awareness@@ -76,7 +76,7 @@ Use the `finalize` command above for the first candidate and after a repair.`finalize` stops at the first non-passing gate. Its compact stdout and `<output-stem>.finalize-summary.json` are the normal evidence; `<output-stem>.finalize.json` is full audit detail, not ordinary repair context. A passing `finalize` receipt reports `visualReview: "not-requested"` and creates no screenshots; report the subsequent perceptual review separately.-For every newly authored or repositioned Architecture, run `visual-check` and inspect its desktop captures before handoff. Check that the main interaction and each secondary chain read in order, branches stay near their owner, and labels visibly belong to their lines. A low crossing count does not establish this. For other artifacts, escalate to perceptual review when the summary includes `visualReviewRecommendation`, the user requests an aesthetic review, a template/renderer/viewer change needs visual regression evidence, a novel layout or browser diagnostic leaves low confidence, or the run is a sampled audit. Run `visual-check` on the finalized artifact, open its HTML contact sheet in a browser or inspect the viewport PNGs with a capable image reader, and trace the affected routes at the common desktop viewport. Each arrow must remain distinct and each relationship traceable through crossings and bends. Repair unreadable placement or routes while preserving semantic coverage, then finalize the new candidate. The recommendation's counts trigger inspection; they are not content budgets or proof of a defect. If perceptual review is unavailable, report that quality remains unverified rather than treating automated success as visual approval.+For every newly authored or repositioned Architecture, run `visual-check` and inspect its desktop captures before handoff. Check that the main interaction and each secondary chain read in order, branches stay near their owner, and labels visibly belong to their lines. A low crossing count does not establish this. For other artifacts, escalate to perceptual review when the summary includes `visualReviewRecommendation`, the user requests an aesthetic review, a template/renderer/viewer change needs visual regression evidence, a novel layout or browser diagnostic leaves low confidence, or the run is a sampled audit. Run `visual-check` on the finalized artifact, open its HTML contact sheet in a browser or inspect the viewport PNGs with a capable image reader, and trace the affected routes at the common desktop viewport. Each arrow must remain distinct and each relationship traceable through crossings and bends. When several routes remain tangled, follow [Architecture layout repair](references/architecture-layout-repair.md) before editing, even if all automated gates passed. Repair unreadable placement or routes while preserving semantic coverage, then finalize the new candidate. The recommendation's counts trigger inspection; they are not content budgets or proof of a defect. If perceptual review is unavailable, report that quality remains unverified rather than treating automated success as visual approval.For recovery, the required order stays `deliver` → strict provenance `check` → `browser-check`. Run `visual-check` only against a strict-provenance artifact. Read `references/delivery-contract.md` for standalone syntax, any failed gate, stale provenance, recovery metadata, repeated delivery to one path, export evidence, or post-delivery opening.diff --git a/archify/bin/finalize.mjs b/archify/bin/finalize.mjsindex 8db3f333..3c8aa453 100644--- a/archify/bin/finalize.mjs+++ b/archify/bin/finalize.mjs@@ -519,7 +519,7 @@ export function compactFinalizeReceipt(receipt) {detours: routeReview.detours.slice(0, 8),truncated: routeReview.crossings.length > 8 || routeReview.detours.length > 8,},- repair: 'Trace these relationships at the desktop viewport. If several routes tangle around the same nodes, reposition that connected neighborhood together, preserving all semantics and unrelated geometry; rerun finalize once. Use a local side or label control only for an isolated remaining defect.',+ repair: 'Trace these relationships at the desktop viewport. If several routes tangle around the same nodes, reposition that connected neighborhood together, preserving all semantics and unrelated geometry; rerun finalize once. Choose endpoint sides for the main rail and return corridors together with placement; reserve detailed waypoints or label overrides for an isolated remaining defect.',} : {}),};}diff --git a/archify/references/architecture-layout-repair.md b/archify/references/architecture-layout-repair.mdnew file mode 100644index 00000000..78e57656--- /dev/null+++ b/archify/references/architecture-layout-repair.md@@ -0,0 +1,12 @@+# Architecture layout repair++Use this after actual visual review finds several tangled routes. A successful machine receipt does not settle composition. Work on the existing candidate, retaining all required components, relationships, labels, evidence, boundaries, and node sizes.++## One coherent repair++1. Trace the affected relationships and their endpoints in the JSON. Identify the reader’s main interaction, shared state used by multiple actors, and any real feedback loop. Use `validate architecture <candidate.json> --layout-json --repo-root <root>` once if the compact receipt and screenshot do not reveal the needed route or label geometry; omit `--repo-root` only for a design without repository evidence. Do not guess repeated waypoint coordinates.+2. Place main-path neighbors in reading order. Put shared state between its readers/writers, on an adjacent row if necessary, so one writer does not need a line across the whole execution area. Arrange a feedback loop around an open rectangle with short branches inside or beside it; preserve every edge and its actual direction. Do not force the whole graph into one rail or sort nodes by implementation category.+3. Assign simple endpoint sides with that placement: facing ports for the main rail, a distinct side for the return direction of a bidirectional pair, and side/top/bottom ports for branches. This is one coordinated layout change, not one correction per edge. Only use detailed `via` or label coordinates for a remaining measured defect. Keep external actors outside the resolved boundary rectangle, including its padding; not listing a node in `wraps` does not visually exclude it. Keep an internal relationship and its label inside the shared boundary unless crossing it conveys a real fact; do not imply an external hop merely to avoid another route.+4. Compact unused gaps while preserving measured label space and the previous text size. Keep the main interaction and all required nodes readable in the default desktop view; do not trade crossings for a large blank canvas, tiny text, or a chain that doubles back without a semantic reason.++Run the complete `finalize` once after the edit, then `visual-check` on the successful artifact and inspect its desktop captures. Trace the main path, each secondary chain, and every affected arrow and label. A bounded second repair may address a remaining specific defect. If it still fails visual acceptance, retain the candidate and report the concrete gap; do not count it as a successful repair or continue blind coordinate changes.