How the `hallmark audit` Command Scores Code Against AI Anti-Patterns

The hallmark audit command inspects HTML, CSS, and JavaScript files against a canonical catalogue of AI-generated UI anti-patterns, producing a severity-weighted report that identifies "tells" and recommends concrete fixes.

The hallmark audit verb in Nutlope/hallmark is a read-only diagnostic tool designed to detect whether frontend code exhibits the visual signatures of AI-generated design. It performs static analysis against a curated rule set and outputs structured findings grouped by severity. This guide explains exactly how the scoring mechanism works, from rule loading through final verdict generation.

---

Loading the Anti-Pattern Rule Set

Every audit begins by loading the canonical anti-pattern catalogue from [skills/hallmark/references/anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). Each entry in this file defines a named pattern with three severity tiers:

• Critical — Definite slop indicators that the report flags as "ships as slop." Examples include purple-gradient heroes and full-viewport centered heroes.
• Major — Strong AI-generated visual signatures. Examples include bounce/ease-elastic animations, centered-everything layouts, and italic headers.
• Minor — Subtle taste issues that accumulate. Examples include straight quotes instead of curly quotes and z-index: 9999 values.

The severity classification directly weights the final audit score. A single critical finding triggers an automatic "ships as slop" verdict regardless of other results.

---

Scanning Target Files for Pattern Matches

The audit accepts any file or directory path as its target:

# Audit an entire directory

hallmark audit ./src/pages

# Audit a single file

hallmark audit ./src/components/hero.css

For each file encountered, the verb applies pattern matching across HTML, CSS, and JavaScript content. The matching logic checks for exact pattern definitions from the anti-patterns catalogue—no fuzzy inference, only documented tells.

---

Generating Structured Findings

Every detected match produces a finding record with four mandatory fields, as specified in [skills/hallmark/references/verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md):

Field	Description
Tell	The anti-pattern name from the catalogue
Where	File path and line range (e.g., src/pages/index.html:45-47)
Severity	critical, major, or minor
Fix	One-line actionable recommendation from the "Fix" paragraph

Here is a representative audit output showing all three severity levels:

[critical] The purple-gradient hero — src/pages/home.html:52-54
  why it reads as AI-generated
  → pick a single anchor hue; no gradient hero

[major] Inter-everywhere — src/styles/global.css:8-10
  why it reads as AI-generated
  → pair a distinctive display face with a refined body face

[minor] Straight quotes — src/components/quote.html:23
  why it reads as AI-generated
  → use curly quotes

Summary — 1 critical · 1 major · 1 minor
Verdict — ships as slop

---

Structural Fingerprint Checks

Beyond style tells, the hallmark audit command evaluates architectural consistency through three additional checks defined in lines 14-24 of audit.md:

Stamp-vs-Page Verification

The audit validates that /* Hallmark · macrostructure: <name> … */ comments match the actual page shape. Mismatched structural declarations generate findings even when visual anti-patterns are absent.

Genre-Aware Scoring

The same visual element receives different severity weights depending on declared genre. A radial-gradient background is critical for editorial pages but allowed for atmospheric layouts. This prevents false positives when unconventional aesthetics are intentional.

design.md Drift Detection

If a project contains a design.md file, the audit cross-references:

• Theme consistency against declared design tokens
• Macrostructure family violations
• Missing or mismatched stamp declarations

These checks catch deviations from self-documented design systems.

---

Grouping and Final Scoring

All findings are aggregated by severity before output. The final report format is strictly prescribed in audit.md:

Summary — N critical · M major · K minor
Verdict — [ships as slop | needs work | clean]

The verdict logic follows the hierarchy:

• Any critical finding → "ships as slop"
• Only major and/or minor findings → "needs work"
• No findings → "clean"

---

Summary

• The hallmark audit command loads anti-patterns from anti-patterns.md with severity tiers of critical, major, and minor.
• Pattern matching scans user-supplied files for exact matches against the catalogue, generating structured findings with tell names, locations, severities, and fixes.
• Structural checks validate Hallmark stamp comments, apply genre-specific overrides, and detect design.md drift.
• Final scoring groups findings by severity and produces a verdict: "ships as slop," "needs work," or "clean."
• The command never modifies files — it is purely diagnostic.

---

Frequently Asked Questions

What file types does hallmark audit analyze?

The command processes HTML, CSS, and JavaScript files. It performs static text analysis against pattern definitions, so any file containing code in these languages is valid input, including templated files like .jsx or .vue if they include recognizable CSS or HTML structures.

Where are the anti-pattern definitions stored?

All rules live in [skills/hallmark/references/anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md). This file contains the complete catalogue with severity classifications, descriptions explaining why each pattern reads as AI-generated, and the one-line fix recommendations that appear in audit output.

Can hallmark audit fix the issues it finds?

No. According to the verb definition in [skills/hallmark/references/verbs/audit.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md), the audit command is strictly read-only. For automated remediation, you would use the hallmark redesign verb instead.

How does genre affect the audit score?

Genre declarations modify severity weights for specific patterns. For example, a radial-gradient hero background is classified as critical for editorial genre pages but permitted without penalty for atmospheric pages. This contextual scoring prevents penalizing intentional aesthetic choices that match declared genre conventions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}