Baseline¶

When adopting skillsaw on an existing project, you may have many pre-existing violations. The baseline feature lets you snapshot current violations so that skillsaw lint only reports new ones — existing violations are accepted and won't cause failures.

Creating a Baseline¶

Generate a .skillsaw-baseline.json from the current violations:

skillsaw baseline

By default, the baseline captures warnings and errors. A configured fail-on: info also includes INFO findings, so the baseline accepts the findings that fail that threshold. If you set the threshold only on the lint command line, opt in when creating or refreshing the baseline:

skillsaw baseline --include-info
skillsaw lint --fail-on info

The baseline file should be committed to your repository so that all contributors share the same accepted set of violations.

Before creating a baseline, take a moment to triage large scans by rule. If many findings share a common repository convention (like a generated data folder or custom terminology), configuring the rule in .skillsaw.yaml is usually better than baselining — it handles future files automatically and keeps your baseline clean.

How It Works¶

Once a .skillsaw-baseline.json file exists (next to .skillsaw.yaml or in the repo root), skillsaw lint automatically loads it and subtracts matching violations from the output. Only new violations are reported. Fatal infrastructure violations such as repository-path-error are not written to the baseline and can never be suppressed by one. The same goes for advisory deprecated-rule notices: baselining one would permanently hide the warning that a rule is going away, so they are never written and never suppressed — remove the deprecated rule from your config to clear the notice instead.

Violations are matched by a content hash — a fingerprint built from the rule ID, file path, and the content of the source line (not the line number). This means the baseline survives line drift: if you add lines above a baselined violation, the fingerprint still matches because the content hasn't changed.

If you reformat or rewrite a line, the fingerprint changes and the violation resurfaces for a fresh look — which is the correct behavior.

Ratchet Rules¶

Some rules measure a numeric value (token count, instruction count, actionability score) rather than flagging a specific line. These rules use ratchet behavior: the baseline records the value at the time it was created and only suppresses violations that are equal to or better than the baseline. If the value gets worse, the violation is reported.

For example, if context-budget records 5,000 tokens at baseline time:

Shrink the file to 4,800 tokens → suppressed (improvement)
Grow the file to 5,200 tokens → reported (regression)
Get under the limit entirely → violation disappears, baseline entry becomes stale

Rules with ratchet behavior:

Rule	Metric	Baseline acts as
`context-budget`	token count	ceiling (can't increase)
`content-instruction-budget`	instruction count	ceiling (can't increase)
`content-actionability-score`	actionability score	floor (can't decrease)
`agentskill-unreferenced-files`	unreferenced files in a collapsed directory	ceiling (can't increase)

Every other finding, including that rule's per-file ones, uses fingerprint matching — the violation is suppressed as long as the source line content hasn't changed. A directory finding and the per-file findings it stands in for cover each other: a baseline that lists the files keeps suppressing the directory, and one that lists the directory keeps suppressing the files while they stay under its count.

Ignoring the Baseline¶

Run lint without baseline filtering:

skillsaw lint --no-baseline

Stale Entries¶

When you fix a baselined violation, its baseline entry becomes stale. Skillsaw reports stale entries so you know the baseline can be refreshed:

Baseline: 3 stale entries (violations resolved since baseline was set)
  Run `skillsaw baseline` to update.

Run skillsaw baseline again to regenerate the file without the resolved violations.

Baseline and Fix¶

The skillsaw fix command ignores the baseline. The baseline only affects lint reporting and exit codes — if you explicitly ask to fix, baselined findings are eligible too.

Workflow Example¶

A typical adoption workflow:

# 1. Set up skillsaw
skillsaw init

# 2. See what violations exist
skillsaw lint

# 3. Accept them as the baseline
skillsaw baseline

# 4. Lint now passes — only new violations will fail
skillsaw lint  # exit 0

# 5. Over time, fix violations and re-baseline
skillsaw baseline  # updates the file with fewer entries

Baseline File Format¶

The .skillsaw-baseline.json file is a JSON document:

{
  "version": "1",
  "generated_by": "skillsaw 0.10.1",
  "generated_at": "2025-05-27T12:00:00+00:00",
  "violations": [
    {
      "fingerprint": "a1b2c3d4e5f6g7h8",
      "rule_id": "content-weak-language",
      "file_path": "CLAUDE.md",
      "line": 42,
      "message": "Weak language: 'try to'",
      "severity": "warning"
    }
  ]
}

The fingerprint field is the content hash used for matching. The line field is stored for human readability but is not part of the match key — violations are matched by content, not position.