GLIC / UGLIC Check

Systematic quality review for code, skills, configs, and documents.

• Version: 1.1.0
• License: MIT
• Author: Evan Song · github.com/Songhonglei
• Repository: https://github.com/Songhonglei/build-better-skills
• Part of: build-better-skills suite — see Stages for the lifecycle map.

Modes

Dimensions

U is only active in UGLIC mode. GLIC mode skips U entirely.

Workflow

1. Determine Mode & Scope

Detect mode from the user's message — use intent matching, not bare substring matching:

• Message expresses intent to run UGLIC (e.g., "UGLIC check", "UGLIC this", "uglic verify", "do a uglic on X", "uglic mode") → UGLIC mode (5 dimensions: U + G + L + I + C)
• Message expresses intent to run GLIC, or asks for a multi-dimension review without specifying mode → GLIC mode (4 dimensions: G + L + I + C)
• ⚠️ Do not auto-route to UGLIC just because the word UGLIC appears anywhere in the message (e.g., "the UGLIC mode docs say X" is asking about UGLIC, not requesting a UGLIC check). Look for a verb/imperative form: do, run, check, verify, audit.

Then, ask or infer what to check:

• "this change" / "the diff" → git diff against base branch / last commit
• "check this skill" → entire skill directory
• "check this code" → specified file(s)
• "GLIC/UGLIC verify" → most recent changes (git diff or last touched files)
• No target specified → ask the user what to check

2. Read Target Content

Read all in-scope files before judging — but read intelligently for large targets.

• Small target (≤ 500 lines total, ≤ 5 files): read fully top-to-bottom.
• Large target (> 500 lines total, or > 10 files, or one file > 500 lines):
  1. Structural scan first — file list, frontmatter, headings, function/class signatures, first + last few lines of each long file
  2. Then deep-read sections that match likely-finding patterns: anti-pattern lists, cross-references, error-handling blocks, frontmatter, build-artifact suspects
  3. Avoid loading every reference upfront — load each references/*.md only when a dimension check needs it
• Do not skim. Skimming = silent miss = wrong report. If a section is too long to read in one go, summarize it before moving on (don't pretend you read it).

3. Execute Dimension Checks

For each active dimension, go through the checklist in references/dimensions.md. Adapt sub-checks to the target type (code / skill / config / document).

GLIC mode: Run G → L → I → C. UGLIC mode: Run U → G → L → I → C.

Key rule: Each finding must cite a specific location (file:line or section heading).

Checker-finding citation discipline (when consuming machine-readable findings from a checker like skill-release-audit JSON):

• Quote findings with code + location + classification reason intact — never re-summarize into a bare variable list and never drop the classification.
• ENV_OPTIONAL_OVERRIDE / ENV_RUNTIME_INJECTED / ENV_AMBIENT / ENV_TEST_ONLY findings must NOT be escalated to WARN/ERR unless you find an independent real failure path (document it when escalating).
• Never recommend adding env metadata just because code reads an env var — see the four-item evidence rule in dimensions.md (I-skill: Env metadata consumption).
• Report confirmed false-positives / non-user-config separately; do not count them into the WARN total.

4. Assign Severity

U-dimension severity rules:

• ERR: Agent cannot reliably execute the core task (ambiguous instructions, unjudgeable conditions, dead-end on failure) or human cannot complete the core task (missing prerequisites, no recovery path, misleading output).
• WARN: Agent execution has uncertainty but usually succeeds, or human needs extra trial-and-error or unnecessary steps.
• INFO: Minor wording improvements, interaction polish, nice-to-have clarity.

Severity escalation (all dimensions):

• A WARN that appears 3+ times within the same check / same target → escalate to ERR (WARNs that recur across multiple separate targets do NOT auto-escalate — they're just an industry-wide pattern worth flagging, not a target-specific failure)
• An issue that could cause silent failure → always ERR
• Missing documentation for a public-facing parameter → always ERR

5. Produce Report

Follow references/output-format.md for consistent structure:

1. Title: ## GLIC Check — [target description] (GLIC mode) or ## UGLIC Check — [target description] (UGLIC mode)
2. One subsection per active dimension
3. Each finding numbered (U1, U2, G1, G2, L1, I1, C1...)
4. Summary table at end with all findings
5. List ERR items that require fix

Assign new numbers per dimension (reset per check).

6. Offer to Fix

After report, explicitly ask: ERR items should be fixed first, then WARN items. Do not fix automatically — wait for user confirmation.

References

• dimensions.md — Detailed sub-check criteria for each dimension. Load before starting step 3. Adapt context-specific checklists (code vs skill vs config). The U dimension checklist is at the top.
• output-format.md — Report structure template with concrete formatting rules. Includes both GLIC and UGLIC variants. Consult when producing the report in step 5.
• examples.md — Five real-world GLIC and UGLIC check examples (small → mid → large → self-check → high-density). Load for reference when unsure about severity assignment, output style, or proportionality.

Optional helper

• scripts/grep_antipatterns.sh — Half-automatic pre-scan that surfaces likely findings before you run the full UGLIC checklist (vague directives in CJK/English, SKILL.md length budget, frontmatter field discipline, build-artifact residue, cross-section reference candidates). Run it first on large targets to anchor where to look. The script surfaces, you still judge severity + cite. Usage: bash scripts/grep_antipatterns.sh <target-dir-or-file>.

Principles

• Must cite location. Never say "somewhere in the file" — give file:line.
• Be specific, not vague. "Naming inconsistent" is not enough — show the two conflicting names.
• Don't nitpick. If a finding doesn't affect function, maintainability, security, or user experience, it's not worth a report line.
• Complexity counts. Complex or fragile workarounds are themselves WARN-worthy, even if they work correctly.
• Silent failure = ERR. Any condition that could fail without visible error is always ERR.

Part of build-better-skills

This skill belongs to the build-better-skills suite. For the full lifecycle map (Install → Audit → Release → Testing → Sediment), all sibling skills, and their current status, see the Stages table on the suite repo home — kept as the single source of truth (this file does not duplicate it).