fix-ui-files

name	fix-ui-files
description	Diagnose and pinpoint structural errors in GTK Builder .ui files (mismatched closing tags, unclosed elements). Use when a .ui file fails to load with a Gtk-WARNING about template precompilation or tag mismatches.

Fix UI Files

Use this skill when a GTK Builder .ui file fails to load. Typical symptoms:

• Runtime warning: Failed to precompile template for class X: Error on line N char M: Element "A" was closed, but the currently open element is "B"
• A blank window where a composite template widget should appear.
• GLib-CRITICAL: g_bytes_get_size: assertion 'bytes != NULL' failed (downstream of the parse failure).

Diagnostic script

Run scripts/validate_ui.py (relative to this skill's directory) on a .ui file or a directory:

python3 .agents/skills/fix-ui-files/scripts/validate_ui.py src/widgets/window.ui
# or, to scan everything:
python3 .agents/skills/fix-ui-files/scripts/validate_ui.py src/

The script walks the file's element stack tag-by-tag and pinpoints:

1. The line where the wrong closing tag was found.
2. The line where the still-open tag was opened (i.e. what should have been closed).
3. Context snippets (surrounding lines) around both.
4. A suggested fix.

Common causes

The most frequent class of error is editing the widget tree (wrapping or unwrapping a layer) and forgetting to update closing tags:

• Adding a wrapper (e.g. inserting a GtkBox between an overlay and its child) without adding the matching </object> and </child>.
• Removing a wrapper (e.g. deleting the GtkBox that stacked a banner above a split view) but leaving its closing tags in place. The extra </object> / </child> cascade into mismatches for every outer scope beyond them.
• Renaming an element in the opening tag but forgetting the closing tag.

Verification

Re-run the script after editing to confirm the file is clean:

python3 .agents/skills/fix-ui-files/scripts/validate_ui.py src/

Then run cargo build (which compiles composite templates for #[template(file = "...")]-wired Rust structs) and launch the application. A parse failure surfaces as a Gtk-WARNING at startup, not as a Rust compile error.

When NOT to use

• Failed to find object 'X' in template — a TemplateChild<> field references an id that does not exist in the .ui file. Not a structural XML problem; grep for the id in the .ui file.
• CSS issues, GObject property typos, missing <requires> — these do not surface as XML parse failures and need a running application to detect.