content-banned-references¶

Detect banned or deprecated model names, APIs, and custom patterns


Severity	warning (auto)
Autofix	-
Since	v0.7.0
Category	Content Intelligence

Why¶

Deprecated model names, retired API endpoints, and outdated references can cause models to fail or use obsolete interfaces. Keeping references up to date ensures instructions work smoothly and efficiently.

When a line maps a name from skillsaw's built-in deprecation list to a replacement (such as in a migration table, arrow syntax, or key/value pair), skillsaw recognizes that the older name is being retired rather than recommended. The replacement itself is still checked to ensure it points to a current, supported model. Patterns you configure under banned are always reported: they express your own policy, not a deprecation.

Examples¶

Bad:

Use the `text-davinci-003` model for completions.
Call the `/v1/complete` endpoint.

Good:

Use `claude-sonnet-4-6` for completions.
Call the `/v1/messages` endpoint.

Also good — a migration guide naming what it retires:

| Retired id | Replacement |
| --- | --- |
| `claude-2.1` | `claude-sonnet-4-6` |

How to fix¶

Replace deprecated model names with their current equivalents and update retired API endpoints. Custom banned patterns configured via the banned list should be replaced per the message in the violation. A coding agent can update flagged references automatically.

Tuning¶

Add project-specific bans or disable the built-in checks:

rules:
  content-banned-references:
    banned:
      - pattern: "\\blegacy-api\\b"
        message: "Use v2-api instead"
    skip-builtins: false
    report-migrations: false   # true also reports the retired side of a mapping

Configuration¶

rules:
  content-banned-references:
    enabled: auto  # true | false | auto
    severity: warning

Parameter	Description	Default
`banned`	Additional banned patterns as list of {pattern, message} dicts	`[]`
`skip-builtins`	Disable built-in deprecated model/API checks	`false`
`regex-timeout`	Per-pattern wall-clock budget (seconds) for custom banned patterns; guards against catastrophic-backtracking regexes (clamped to 10s max)	`2.0`
`report-migrations`	Report a banned name even on a line that maps it to a current replacement (a table row, arrow, or key/value entry)	`false`

Research Basis¶

Detects deprecated model names, retired APIs, and custom banned patterns.

LLMs trained on older data generate deprecated API calls 70–90% of the time when given outdated context (Wang et al., ICSE 2025). An instruction file that says "use claude-2 for summarization" or "call /v1/complete" becomes that outdated context — the model will generate code targeting APIs that no longer exist.

The rule ships with built-in patterns for deprecated Anthropic and OpenAI models and supports user-defined patterns via the banned config key.

References:

Wang et al., LLMs Meet Library Evolution: Evaluating Deprecated API Usage in LLM-based Code (ICSE 2025) — 70–90% deprecated API usage rates with outdated context
OpenAI Deprecations — Ongoing model and API churn
Fern: Documentation Maintenance Guide — "AI agents treat documentation as ground truth and cannot detect errors through experience"

Run skillsaw explain content-banned-references to see this documentation and the rule's effective configuration in your terminal.