Understand a violation

A check found violations and you want to know what each one means and how to fix it. This guide shows how to read chisel’s output, ask for fix guidance on a single rule, and consume the JSON shape that agents and CI use.

Read the human output

By default both CLIs print violations grouped by category, one block per violation. Each block names the file, line, rule ID, and a short message.

Python

chisel check ./your-backend

TypeScript

chisel-js check ./your-frontend

The rule ID is the key you’ll use everywhere else. It has the form category:rule-name, e.g. structural:isinstance-banned or component-enforcement:raw-button.

Ask for fix guidance on one rule

explain prints the rule’s description and the fix an agent should apply. Accepts a single rule ID or a category prefix (which expands to every rule in that category).

Python

chisel explain structural:isinstance-banned
chisel explain structural            # every rule in the category
chisel explain --json

TypeScript

chisel-js explain component-enforcement:raw-button
chisel-js explain component-enforcement
chisel-js explain --json

This is the command an agent runs in its fix loop, the same guidance a human reads, in context.

List every rule

rules lists all rules the installed version enforces, grouped by category.

Python

chisel rules            # human-readable
chisel rules --json     # machine-readable

TypeScript

chisel-js rules
chisel-js rules --json

See the full rendered list with fix guidance per rule: Python rules · TypeScript rules.

Consume the JSON output

check --json is designed for agents and CI. Two things make it pleasant to consume:

1. Deduplicated messages. Repeated messages across many files are stored once in a top-level messages array. Each violation references its message by message_ref (Python) / messageRef (TypeScript).
2. Skill cross-reference. Each message carries skill_name / skillName: the bundled skill that teaches the pattern being violated. An agent can read that skill next if it needs more context.

Why dedup?

A single bad pattern (e.g. console.log left in 30 files) should produce one message on the agent’s radar, not 30. The agent reads the fix guidance once, applies it broadly, and re-checks.

The shape differs only in casing between the two CLIs:

Python (snake_case)

{
  "violations": [
    { "file": "...", "line": 12, "rule_id": "...", "message_ref": "..." }
  ],
  "messages": [
    { "ref": "...", "rule_id": "...", "text": "...", "skill_name": "building-python-backend" }
  ]
}

TypeScript (camelCase)

{
  "violations": [
    { "file": "...", "line": 12, "ruleId": "...", "messageRef": "..." }
  ],
  "messages": [
    { "ref": "...", "ruleId": "...", "text": "...", "skillName": "building-sveltekit-frontend" }
  ]
}

See the Commands reference for the full shape.

What’s next

• Turn off a rule for a file: when a rule genuinely shouldn’t apply to a file.
• Give your AI agent the rules: install the skills whose skill_name shows up in the JSON.