What Does the `hallmark audit` Command Do? A Complete Guide to Anti-Pattern Detection

The hallmark audit <target> command performs a read-only analysis of HTML/CSS files to detect AI-generated UI anti-patterns, structural violations, and "stamp lies," producing a severity-graded report that helps developers decide whether to run a redesign.

The hallmark audit command is one of three explicit verbs defined in the Hallmark design skill for identifying "slop" in web interfaces. According to the skills/hallmark/SKILL.md specification, this command evaluates source files against an anti-pattern catalogue and structural rules without ever modifying the original code.

How the hallmark audit Command Works

Target File Ingestion

When invoked with hallmark audit <target>, the tool loads the specified HTML, CSS, or directory contents. The command recursively walks directories specified as targets, auditing every file containing Hallmark-relevant markup to build a comprehensive analysis scope.

Anti-Pattern Detection Against the Catalogue

The audit scans for named "tells" defined in skills/hallmark/references/anti-patterns.md. These include visual signatures like the purple-gradient hero, 3-column feature grids, and mixed icon libraries. Each detected anti-pattern receives a severity classification of critical, major, or minor based on its correlation with AI-generated templates.

Structural Fingerprint Verification

Beyond surface patterns, the audit verifies macro-structure guidelines defined in the Hallmark specification. If a page uses a centered-hero-only template—a common AI-template shape—the tool flags this as a critical structural finding regardless of visual polish.

Stamp-vs-Page Validation

When source files contain a Hallmark stamp (/* Hallmark · macrostructure: … */), the audit performs validation checks to ensure the actual markup matches the claimed macrostructure. Mismatches between declared structure and implemented code are flagged as stamp lies, indicating the developer documentation has drifted from reality.

Genre-Aware Tolerance Rules

The audit respects genre declarations within stamps (such as genre: atmospheric). When specified, the tool applies tolerance rules from skills/hallmark/references/slop-test.md, allowing certain patterns like gradients in atmospheric contexts while maintaining strict rules for other genres. This implements the 58-gate slop-test logic specified in the reference documentation.

Design System Drift Detection

If the project root contains a design.md or DESIGN.md file, the audit performs additional checks against the locked design system. It validates token usage, font pairings, and macrostructure compliance, flagging any drift from the established design specifications as critical findings.

Understanding the Audit Report Format

The command outputs findings grouped by severity with structured metadata. Each entry includes the anti-pattern name, file location (e.g., index.html:23), severity level, explanation ("why"), and a one-line fix suggestion.

The report concludes with a quantitative summary line (3 critical · 5 major · 12 minor) and a final verdict such as "ships as slop" or an equivalent status indicating whether the code meets Hallmark quality standards.

Practical Usage Examples

Basic single-file audit:

hallmark audit index.html

Recursive directory audit:

hallmark audit src/

Sample output structure:

critical   The purple‑gradient hero — index.html:23
  why: gradient background on hero is a known AI tell
  → fix: use a single anchor hue, no gradient

major      Inter‑everywhere — styles.css:45
  why: same font used for display and body
  → fix: pair a distinctive display face with a refined body face

minor      Straight quotes — components/quotes.html:12
  why: typographic typo
  → fix: replace with curly quotes

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

Summary

• The hallmark audit command is a read-only safety check that never modifies source files, unlike the redesign or study verbs.
• It evaluates code against the anti-pattern catalogue in skills/hallmark/references/anti-patterns.md and the 58-gate slop-test rules in skills/hallmark/references/slop-test.md.
• The tool detects structural violations, stamp lies (documentation drift), and design system drift against design.md specifications.
• Findings are classified into three severity levels: critical, major, and minor.
• Output includes actionable fix suggestions and a final verdict determining if the code "ships as slop."

Frequently Asked Questions

Does hallmark audit modify my source files?

No. According to skills/hallmark/references/verbs/audit.md, the audit verb is explicitly designed as a read-only operation. It analyzes and reports findings without writing changes to disk, serving as a decision-making tool to determine whether you should proceed with hallmark redesign or other modification commands.

What is the difference between critical, major, and minor findings?

Critical findings indicate severe AI-template signatures or structural violations (like purple-gradient heroes or centered-hero-only layouts). Major findings represent significant design system drift or anti-patterns that degrade user experience. Minor findings are typographic or stylistic issues (like straight quotes instead of curly) that don't indicate AI generation but should be fixed for polish.

How does the audit handle different design genres?

When a Hallmark stamp declares a genre (e.g., genre: atmospheric), the audit applies genre-specific tolerance rules from skills/hallmark/references/slop-test.md. For example, gradients that would be flagged as critical AI-tells in a corporate genre might be permitted in atmospheric contexts, demonstrating the tool's contextual awareness of legitimate design variations.

What happens if my Hallmark stamp doesn't match my actual code?

The audit performs stamp validation by comparing the declared macrostructure in your stamp comment against the actual DOM structure. If mismatches are detected, the tool flags these as "stamp lies" in the report, helping maintain documentation accuracy and preventing drift between claimed architecture and implementation.

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