clawlint-interpreting-results

Interpreting clawlint diagnostics

clawlint emits a canonical JSON envelope:

{
  "schema_version": 1,
  "diagnostics": [
    {
      /* one per finding */
    }
  ]
}

Diagnostic shape

{
  "rule_id": "agent-file-size",
  "category": "agent-file-health",
  "severity": "warn",
  "feasibility": "deterministic",
  "scope": { "file": { "path": "CLAUDE.md" } },
  "origin": "project",
  "message": "CLAUDE.md is 4123 tokens (threshold 3000)",
  "metadata": { "tokens": 4123, "threshold": 3000 },
  "needs_judgment": false
}

Fields

• rule_id — stable, never renamed. Cite this when filing bugs or suppressing.
• category — one of agent-file-health, best-practices-adherence, skills-hooks-gaps, context-management.
• severity — error (broken/contradictory), warn (real problem), info (style / nudge).
• feasibility — deterministic (rule is mechanical) or heuristic (rule guesses; may need --llm-assist to adjudicate).
• scope — where the finding lives:
  • { "file": { "path": "…" } } — a single file
  • { "project": { "root": "…" } } — whole project
  • "global" — ~/.claude/ or ~/CLAUDE.md
  • { "session": { "id": "…", "path": "…" } } — transcript (Phase 3)
• origin — project or global. Lets you filter CLI output via --scope and TUI via a/p/g.
• metadata — rule-specific structured data. Thresholds, counts, matched substrings, etc. Useful for jq filters.
• needs_judgment — set by judgment-heavy rules. Only meaningful under --llm-assist; the LLM either confirms or suppresses the diagnostic.

LLM-related metadata

When --llm-assist runs:

• metadata.llm_reasoning — the LLM's one-sentence confirmation. The diagnostic was kept because the LLM agreed the finding is real.
• metadata.llm_model — which model adjudicated (cache key).
• metadata.llm_note — escalation fell open. Missing ANTHROPIC_API_KEY, network error, or malformed response. The diagnostic is passed through unjudged.

Triage playbook

1. Errors first. These usually mean the config doesn't parse or contradicts itself (e.g., tool-permissions-redundant-deny).
2. Warnings that touch context budget. agent-file-size, output-style-token-heavy, agent-file-no-headings — these silently cost tokens on every turn.
3. Warnings that touch discoverability. skill-description-vague, skill-missing-when-not-to-use, overlapping-skill-triggers — Claude can't pick the right skill if the metadata is mushy.
4. Info accumulations. A single info finding is usually safe to ignore. Ten of them in one file is a pattern and worth a pass.

False-positive smell test

A clawlint finding is probably a false positive when:

• The rule is feasibility: heuristic and the region it flagged has a clear, stated reason for deviating from the heuristic (cite the reason in a suppression comment).
• The rule says "stale path" but the path is interpolated at runtime (${VAR}/config) — a known limitation until we add interpolation awareness.
• The rule says "unused skill" but the skill is intentionally dormant (e.g., scaffolded but not yet wired). Suppress with a note.

A finding is almost certainly real when:

• Severity is error.
• Rule is feasibility: deterministic and you can reproduce the signal by reading the file yourself.
• The metadata counts line up with what you see (e.g., tokens: 4123 and you can confirm the file is large).

Reading at the CLI

# just errors
clawlint check --format json | jq '.diagnostics[] | select(.severity == "error")'

# one category
clawlint check --format json | jq '.diagnostics[] | select(.category == "agent-file-health")'

# grouped counts
clawlint check --format json | jq '.diagnostics | group_by(.rule_id) | map({rule: .[0].rule_id, n: length})'

When in doubt

clawlint explain <rule-id> → the canonical per-rule doc. If the rule's behaviour surprised you, the catalog rationale will usually clarify.