# How to Debug Skill Issues in Nutlope/hallmark: A Complete Troubleshooting Guide

> Troubleshoot Nutlope/hallmark skill issues effectively. Learn to inspect logs, verify CSS, validate tokens, and run slop-test gates for seamless debugging.

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

---

**Debug skill issues in Nutlope/hallmark by inspecting the [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) run history, verifying CSS stamps for macrostructure diversity, validating theme tokens in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), and manually running the 58+1 slop-test gates when generation fails.**

The Hallmark skill is a self-contained design engine residing entirely in `skills/hallmark` within the Nutlope/hallmark repository. When generation produces incorrect macrostructures, theme clashes, or slop-test failures, you need a systematic approach to trace issues through its transparent three-layer architecture. This guide provides the exact file paths, validation commands, and debugging workflows required to diagnose and resolve skill issues effectively.

## Understanding the Hallmark Skill Architecture

The skill operates through three distinct layers that generate and validate design output. Understanding these layers helps you isolate where a failure occurs.

### Pre-Flight Scanner

The pre-flight scanner reads your existing project files—including [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), `tailwind.config.*`, and [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html)—to preserve existing fonts, palettes, spacing, and motion before any generation starts. According to the source code in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) (lines 45-59), this layer creates a preservation profile that subsequent layers must respect. If your existing design system is being overwritten unexpectedly, start your debugging here.

### Diversification Engine

The diversification engine enforces macrostructure, theme, navigation, and footer diversity by consulting [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) and macrostructure stamps embedded in generated CSS. As implemented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) (lines 70-88), this layer prevents repetitive designs by ensuring the selected macrostructure differs from the last three entries and that themes vary across the three axes: paper-band, display-style, and accent-hue.

### Slop-Test Validator

After code emission, the skill runs 58+1 pre-emit self-critique gates to catch anti-patterns, missing tokens, mobile breakage, and invented metrics. These rules are defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) and loaded at Step 7 of the generation process. When the skill aborts or produces low-quality output, this validator has typically flagged a violation.

## Step-by-Step Debugging Workflow

When you need to debug skill issues in Nutlope/hallmark, follow this systematic verification process.

### Inspect the Run Log

Every successful run persists its design decisions to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). Examine this file to verify diversification rules:

```bash
cat .hallmark/log.json

```

Verify that the most recent entry's `macrostructure`, `theme`, `nav`, and `footer` values differ appropriately from previous runs. Specifically confirm that the macrostructure differs from the last three entries (Rule 1) and that the theme differs on at least one of the three axes (Rule 2).

### Check the CSS Stamp

Every generated stylesheet begins with a comment recording the design fingerprint. Verify the stamp matches your expectations:

```bash
grep -E 'Hallmark · macrostructure' -r site/css

```

Confirm the macrostructure name matches the entry in [`log.json`](https://github.com/Nutlope/hallmark/blob/main/log.json) and that no duplicate macrostructure appears in the same project.

### Validate Theme Tokens

Tokens are defined in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) under `[data-theme="…"]` blocks. Ensure the selected theme's token block exists (e.g., `[data-theme="cobalt"]`) and that no inline color or font declarations leak outside the token system, which would trigger Anti-pattern § Locked tokens.

### Run the Slop-Test Manually

When the skill aborts before completion, invoke the validator manually using the test harness in `site/_tests/`:

```bash

# From the repository root

node site/_tests/slopTest.js

```

Alternatively, create a temporary script to test specific outputs:

```javascript
// debug-slop.js
import { runSlopTest } from './site/_tests/slopTest.js';
import fs from 'fs';

const html = fs.readFileSync('site/_tests/example.html', 'utf8');
const css  = fs.readFileSync('site/_tests/example.css',  'utf8');

const result = runSlopTest({ html, css });
console.log(result);

```

If any gate fails, the output lists the gate number and description—exactly what the skill would emit as a failure block.

### Check for Pre-Flight Mismatches

If the skill altered an existing font-stack or palette, the pre-flight step should have warned you. Search for `/* Hallmark · pre‑emit critique */` comments in the output CSS, which list the six self-critique scores indicating preservation success.

### Verify Component Scope vs Page Scope

For component-oriented briefs, ensure the generated file follows the component stamp format:

```css
/* Hallmark · component: <type> · genre: <genre> · theme: <theme>
 * states: default · hover · focus · active · disabled · loading · error · success
 * contrast: pass (46–50)
 */

```

If a full-page stamp appears instead, the skill mis-detected the scope. Force component scope explicitly:

```bash
hallmark redesign ./components/Button.tsx --mood playful

```

### Re-Run with Explicit Flags

Many failures resolve when you bypass ambiguous inference:

- `hallmark audit <target>` — Reads and scores a target without writing files, perfect for reproducing errors without side-effects
- `hallmark redesign <target> --mood <name>` — Forces a redesign with a known mood, bypassing inference ambiguity

### Review Reference Files

The skill's behavior is driven by markdown reference files in `skills/hallmark/references/`. If a gate triggers unexpectedly, consult the corresponding reference:

- [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md) — For invented metric warnings or redrawn UI chrome violations
- [`references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md) — For the complete list of 58+1 validation gates

## Practical Debugging Examples

Use these specific commands to diagnose common issues.

### Reading the Last Five Builds

```bash
jq '.[0:5]' .hallmark/log.json | less

```

### Finding Macrostructure Stamps

```bash
grep -n 'Hallmark · macrostructure' -r site/css | head

```

### Verifying Theme Token Usage

Replace `<theme>` with your expected theme name (e.g., `cobalt`):

```bash
grep -n '\[data-theme="<theme>"\]' site/css/tokens.css

```

## Key Files for Debugging

| File | Role | Location |
|------|------|----------|
| [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) | Core rule-set orchestrating pre-flight, verbs, and diversification | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) |
| [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) | Defines 20+ themes, token variables, and per-theme overrides | [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) |
| [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) | Detailed list of 58+1 pre-emit validation gates | [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) |
| [`log.json`](https://github.com/Nutlope/hallmark/blob/main/log.json) | Persistent log of every successful run (macrostructure, theme, nav, footer) | [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) (generated) |
| [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) | Catalog of disallowed patterns | [`skills/hallmark/references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) |
| `_tests/` | Minimal test harnesses for manual validation | `site/_tests/` |

## Summary

- **Start with the log**: Inspect [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to verify diversification rules and run history
- **Verify stamps**: Check CSS comments for macrostructure and theme fingerprints to ensure correct diversity enforcement
- **Validate tokens**: Confirm theme tokens exist in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and no inline styles leak outside the token system
- **Run manual tests**: Use the `site/_tests/` harness to execute slop-test gates independently when generation aborts
- **Use explicit flags**: Run `hallmark audit` for read-only debugging or `hallmark redesign --mood` to bypass ambiguous inference
- **Consult references**: Check `skills/hallmark/references/` to understand why specific gates or anti-patterns trigger

## Frequently Asked Questions

### What is the slop-test in Nutlope/hallmark?

The slop-test is a 58+1 gate validator that runs after code generation to catch anti-patterns, missing tokens, mobile breakage, and invented metrics. Defined in [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md), it acts as a pre-emit self-critique that aborts generation if the output violates design quality rules. You can run it manually using the harness in `site/_tests/` to debug specific HTML/CSS outputs without triggering a full skill run.

### How do I fix theme token leaks in Hallmark output?

Theme token leaks occur when inline colors or fonts appear outside the `[data-theme="…"]` blocks in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css). To fix this, verify that all generated CSS uses CSS variables defined in the token system. Search for hardcoded hex codes or font families in the generated output and replace them with token references. The slop-test gate for "Locked tokens" specifically checks for this anti-pattern.

### Why does the skill keep selecting the same macrostructure?

The diversification engine enforces Rule 1: the selected macrostructure must differ from the last three entries in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json). If the skill repeats macrostructures, check that the log file is being written correctly and that the CSS stamps in your generated files match the log entries. If running in component mode, ensure you are not forcing a specific macrostructure via flags that overrides the diversity engine.

### How can I debug Hallmark without changing my files?

Use the `hallmark audit <target>` command, which operates in read-only mode. This command runs the pre-flight scanner and slop-test validator against your target without writing any files, allowing you to reproduce "what went wrong" without side-effects. For deeper debugging, manually invoke the slop-test harness from `site/_tests/` against saved HTML/CSS samples to isolate specific gate failures.