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

> Learn to use the Hallmark audit verb to analyze existing code. Discover anti-patterns and get a structured punch-list of findings without code modification.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-06

---

**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`](https://github.com/Nutlope/hallmark/blob/main/design.md) rulesets based on the Hallmark skill implementation in [Nutlope/hallmark](https://github.com/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`](https://github.com/Nutlope/hallmark/blob/main/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

```bash

# Audit a single file

hallmark audit ./site/index.html

```

```bash

# Audit multiple files (space-separated)

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

```

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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

```markdown

## 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md) to classify issues
3. **Conditional design-system load** — Parses [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Declares the `audit` verb contract and high-level behavior |
| [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) | Complete output format specification and structural check rules |
| [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) | Master list of named anti-patterns reported as **Tell** items |
| [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) | Design-system compliance rules applied when [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) exists |
| [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) | Severity classification reference (not gate execution) |
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Confirms skill entry point as [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file?

Yes. The audit verb functions fully on anti-pattern detection alone. When [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.