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

Debug skill issues in Nutlope/hallmark by inspecting the .hallmark/log.json run history, verifying CSS stamps for macrostructure diversity, validating theme tokens in 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, tailwind.config.*, and index.html—to preserve existing fonts, palettes, spacing, and motion before any generation starts. According to the source code in 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 and macrostructure stamps embedded in generated CSS. As implemented in 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 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. Examine this file to verify diversification rules:

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:

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

Confirm the macrostructure name matches the entry in log.json and that no duplicate macrostructure appears in the same project.

Validate Theme Tokens

Tokens are defined in 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/:

# From the repository root

node site/_tests/slopTest.js

Alternatively, create a temporary script to test specific outputs:

// 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:

/* 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:

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 — For invented metric warnings or redrawn UI chrome violations
• 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

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

Finding Macrostructure Stamps

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

Verifying Theme Token Usage

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

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

Key Files for Debugging

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

Summary

• Start with the log: Inspect .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 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, 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. 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. 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.

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