How to Use the Hallmark `audit` Verb to Analyze Existing Code

The hallmark audit command reads target files, scores them against an anti-pattern list, and returns a structured punch-list of findings without modifying any code.

The audit verb in Hallmark provides a read-only analysis workflow for evaluating code quality and design-system compliance. This guide explains how to invoke the verb, interpret its output, and leverage its integration with design.md rulesets based on the Hallmark skill implementation in Nutlope/hallmark.

Hallmark audit Verb Syntax and Invocation

Hallmark operates as a design-skill with a consistent CLI pattern: hallmark <verb> <target>. The audit verb is defined in skills/hallmark/SKILL.md within the verbs table, which explicitly describes its behavior as "Read the target, score it against the anti-pattern list, return a ranked punch list. Do not edit."

This non-destructive guarantee makes hallmark audit safe to run at any point in your workflow.

Basic Invocation Patterns

# Audit a single file

hallmark audit ./site/index.html

# Audit multiple files (space-separated)

hallmark audit ./src/pages/home.html ./src/pages/about.html

# Audit an entire project by passing the root directory

hallmark audit .

Understanding the Hallmark Audit Output Format

The concrete output specification lives in skills/hallmark/references/verbs/audit.md. Each finding follows a strict four-field structure:

Field	Description
Tell	The named anti-pattern from references/anti-patterns.md
Where	File path plus line range (e.g., ./file.html:12-18)
Severity	critical, major, or minor
Fix	One-line concrete correction

Findings are grouped by severity in descending order, and the report ends with a summary count line: N critical · M major · K minor.

Sample Audit Output

## Critical (2)

- **Tell:**   `invented-metrics`  
  **Where:**  ./site/index.html:12-18  
  **Fix:**    Replace "+47 % conversion" with a real metric or a placeholder "— % conversion".

- **Tell:**   `stamp-lies`  
  **Where:**  ./src/pages/about.html:1-1 (/* Hallmark · macrostructure: Bento Grid … */)  
  **Fix:**    Update the stamp to the actual macrostructure or remove it.

## Major (1)

- **Tell:**   `italic-headers`  
  **Where:**  ./src/components/Header.css:4-6  
  **Fix:**    Use `font-style: normal` on all heading selectors.

## Minor (3)

- **Tell:**   `mid-render-token-improvisation`  
  **Where:**  ./src/styles/tokens.css:22-22  
  **Fix:**    Move the inline colour into a token declaration.

2 critical · 1 major · 3 minor

Structural and Design-System Checks in Hallmark Audit

The hallmark audit verb performs two specialized validation layers beyond basic anti-pattern matching.

Structural Fingerprint Validation

The audit checks stamp-vs-page consistency — mismatches between AI-template pattern stamps declared in file headers and the actual macrostructure are flagged as critical findings. This catches divergence between documented structure and implementation.

Design.md Integration

When a design.md file exists in the project, hallmark audit enforces additional design-system compliance rules:

• Theme drift: Colors, typography, or spacing that deviate from the design system
• Macrostructure family violations: Component patterns that don't match approved families
• Missing stamps: Files lacking required Hallmark structural comments

These checks are defined in skills/hallmark/references/design-md.md and applied conditionally based on file presence.

Hallmark Audit Architecture and Data Flow

The audit verb functions as a thin orchestrator with four distinct phases:

1. Load target files — Reads all file paths supplied after the verb
2. Run anti-pattern matcher — Applies rules from references/anti-patterns.md to classify issues
3. Conditional design-system load — Parses design.md and structural stamp comments when available
4. Format results — Generates markdown output grouped by severity with summary counts

The audit shares pre-flight scanning logic with other Hallmark verbs (reading design.md, token files, and configuration), but terminates after analysis — no write operations occur.

Relationship to Slop Tests

The audit verb references slop-test definitions from references/slop-test.md solely for severity classification. The actual slop-test gate execution — which can block or trigger redesign flows — occurs in separate design and redesign verbs, not during audit.

Key Source Files for Hallmark Audit Behavior

File Path	Purpose
skills/hallmark/SKILL.md	Declares the audit verb contract and high-level behavior
skills/hallmark/references/verbs/audit.md	Complete output format specification and structural check rules
skills/hallmark/references/anti-patterns.md	Master list of named anti-patterns reported as Tell items
skills/hallmark/references/design-md.md	Design-system compliance rules applied when design.md exists
skills/hallmark/references/slop-test.md	Severity classification reference (not gate execution)
package.json	Confirms skill entry point as skills/hallmark/SKILL.md

Summary

• Hallmark audit is a read-only verb that analyzes code against anti-patterns and design-system rules without making edits
• Output follows a strict four-field format (Tell, Where, Severity, Fix) grouped by severity level
• Structural fingerprint and stamp consistency checks catch template drift at the critical level
• Design.md integration adds theme drift, macrostructure, and stamp validation when the file is present
• The verb shares pre-flight logic with other Hallmark operations but stops after analysis — it never writes files

Frequently Asked Questions

What is the difference between hallmark audit and other Hallmark verbs?

The audit verb is read-only and produces a punch-list without modifications. Design and redesign verbs can write files and trigger slop-test gates. According to skills/hallmark/SKILL.md, audit explicitly promises "Do not edit" where other verbs may transform code.

Can I run hallmark audit without a design.md file?

Yes. The audit verb functions fully on anti-pattern detection alone. When design.md is absent, it skips design-system compliance checks (theme drift, macrostructure family validation) but still reports structural stamp mismatches and all standard anti-patterns.

How does Hallmark determine severity levels for audit findings?

Severity classification draws from the slop-test definitions in references/slop-test.md. Critical issues include structural lies and invented metrics. Major violations cover style inconsistencies like italic headers. Minor findings capture token improvisations and similar refinements.

Does hallmark audit modify my files or add comments?

No. The verb contract in skills/hallmark/SKILL.md explicitly forbids edits. Audit is safe for CI pipelines, pre-commit hooks, or any workflow requiring guaranteed read-only analysis of existing code.

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