drawio-reconstruction

Files (12)

• .gitignore
• LICENSE
• README.md
• README.zh-CN.md
• SKILL.md
• openai.yaml · agents/
• requirements.txt
• batch_manifest.py · scripts/
• batch_verify.py · scripts/
• check_drawio.py · scripts/
• crop_assist.py · scripts/
• export_drawio.py · scripts/

SKILL.md (first lines)

# Draw.io Reconstruction

Use this skill for high-quality reconstruction of diagram images into `.drawio` files.

## Helper Script Location

Resolve `SKILL_DIR` to the absolute directory containing this `SKILL.md` before running any bundled helper. Use the resolved skill location provided by the runtime; never assume the skill is installed under `~/.codex`, `~/.agents`, or any other fixed directory.

All commands below use `$SKILL_DIR` to mean that resolved absolute directory.

## Fidelity Contract

The primary goal is visual fidelity to the reference image. Editability is secondary.

Do not treat semantic equivalence as success. A generic icon, generic curve, generic font size, approximate panel, or approximate background is a defect when the reference has a specific visual style.

Script checks only prove technical validity. A diagram is not complete merely because `.drawio` opens, exports, or passes `check_drawio.py` / `batch_verify.py`. Completion requires visual comparison against the reference at full size.

Work only in the target directory or target files named by the user. Do not repair, overwrite, or improve neighboring diagrams because they look related. If the requested target is ambiguous, inspect and report the ambiguity before editing.

Never silently rewrite the user's content. If the user asks for larger fonts or a more professional PPT style, first distinguish:

- **Layout-only refinement**: increase font size, resize boxes, improve spacing, align elements, adjust line breaks without changing words.
- **Content compression**: shorten sentences, remove details, rewrite labels. Ask permission before doing this.

## Batch Folder Workflow

Use this workflow when the user provides a directory of images or asks for batch reconstruction.

### Batch Intent And Scheduling

Before opening images for detailed visual analysis, decide whether the request is a batch reconstruction task:

- Treat the request as batch reconstruction when it names a folder, multiple image files, a glob/pattern, or any target that resolves to **2 or more image entries**.
- Create and review the manifest before detailed per-image work begins.
- When sub-agent tooling is available and useful, use a bounded worker pool no larger than the available concurrency and the number of pending images. Give each active worker exactly one image and an exclusive write set for that image's `.drawio`, exported `.png`, audit file, and private asset/crop directory. Reuse a free slot for the next image instead of trying to start every worker at once.
- When sub-agent tooling is unavailable, disabled, capacity-limited, or unnecessary for a small batch, process entries serially in manifest order. Preserve the same inventory, reconstruction, export, check, and visual-audit requirements.
- Tell the user about scheduling limitations only when they materially affect timing or delivery. Do not block a valid batch solely because parallel execution is unavailable.
- The coordinating agent may inspect thumbnails or file metadata to confirm scope, naming, orientation, and shared style constraints before choosing the schedule.

1. Identify the input directory, output directory, naming convention, and overwrite policy.
2. Create a batch manifest:

   ```bash
   python "$SKILL_DIR/scripts/batch_manifest.py" path/to/images --output-dir path/to/output --write
   ```

3. Review the manifest before editing. Process only entries in the manifest unless the user expands scope.
4. For each image, define the expected `<stem>.drawio`, `<stem>.png`, and lightweight `<stem>.audit.md` outputs in the target output directory.
5. Choose a bounded parallel schedule or a serial schedule:
   - Assign exclusive output files for each active entry.
   - Tell workers they are not alone in the codebase and must not revert or edit other workers' outputs.
   - Require every entry to follow the same full workflow as a standalone single-image task. Batch mode is only a scheduling strategy; it does not reduce fidelity, inventory, reconstruction, export, check, or visual-audit requirements.
   - Apply this quality gate to every entry: produce `.drawio`, `.png`, and `<stem>.audit.md`; create the complete visible-element inventory; classify non-text visuals; use crops/SVG/native elements according to the normal medium rules; run required checks/exports; visually compare the exported preview against the reference; mark unresolved visual defects instead of claiming completion.
   - Keep final batch verification, visual inspection, audit review, and the user-facing completion report with the coordinating agent.
6. After reconstruction, run batch verification:

   ```bash
   python "$SKILL_DIR/scripts/batch_verify.py" path/to/output/drawio_batch_manifest.json
   ```

7. Open every exported preview and compare it with the reference. Do not trust worker completion or script success alone.
8. Report completed entries, skipped entries, failures, and any images that need review.

Default batch outputs:

- `drawio_batch_manifest.json`
- `<image-stem>.drawio`
- `<image-stem>.png`
- `<image-stem>.audit.md`

Do not overwrite existing outputs unless the user explicitly asks. If an output exists, either skip it or create a clearly named revision such as `<stem>-v2.drawio`.

## Mandatory Reference Inventory

Before reconstructing each image, create a visible-element inventory. For complex or batch work, write it to `<stem>.audit.md`; for a very small single image, maintain it in working notes and still perform the same checks.

The inventory must cover every visible region and element:

- canvas size, background, grid, texture, gradients, shadows, page boundary
- title, subtitle, section headers, footer, page number
- panels, cards, containers, dividers, badges, numbered markers
- every text block and label
- every icon, artwork, screenshot, logo, chart, thumbnail, or decorative visual
- every arrow, curve, connector, loop, bracket, dashed path, and arrowhead
- all spacing relationships that define the layout

Each inventory item must include:

- `id`
- approximate region or bbox
- content / visual description
- selected medium: native / SVG / crop / generated-cleanup
- style notes: color, stroke, font, size, shadow, curve geometry, padding
- status: pending / done / needs-fix / accepted

Do not begin final delivery until all visible inventory items are accepted or explicitly reported as unresolved.

## Reconstruction Strategy

Use the best medium for visual fidelity. Do not globally default all non-text visuals to screenshots, and do not globally redraw all visuals as SVG. The deciding question is: which method best matches the reference after export?

Prefer **Draw.io native elements** for:

- editable text, headings, labels, chips, callouts
- boxes, panels, dividers, simple tables, simple charts, badges
- structural arrows/connectors when native geometry can match the reference
- repeated layout structure that should remain easy to edit

Use **PNG crop / screenshot by default** for:

- complex icons, detailed symbols, decorative illustrations, and mixed-object visuals
- style-specific icon families where a generic SVG would not match the reference
- visual metaphors and scene-like artwork: icebergs, people, environments, dashboards, monitors, lab scenes, rooms, landscapes, workflow scenes
- real UI screenshots, phone/dashboard strips, app thumbnails, evidence screenshots, dense mini-diagrams
- people, cartoon characters, expressive faces, hands, body poses, or human-computer scenes
- anything where exact visual fidelity matters more than editability
- any non-text visual that would take many paths, gradients, masks, or manual approximations to redraw
- any visual element where an SVG/native attempt would simplify, omit, or visibly distort important details

From zms618/no-heartburn-academic-skills, MIT.

More from zms618/no-heartburn-academic-skills