content-repeated-directive

Detect the same directive stated more than once within a file

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

Why

Stating the same instruction more than once doesn't make a model follow it more reliably. Frontier-model prompting guidance (e.g. OpenAI's GPT-5.6 prompting guide) is explicit: state each instruction once — repeated directives are noise the model must parse around, and overlapping restatements of one policy ("ask first" here, "wait for approval" there) cost reasoning effort without changing behavior. Every repeat also spends instruction budget that a distinct rule could have used (see content-instruction-budget).

The rule detects two forms of repetition within a single file:

• Repeated directives — two imperative lines that are identical or nearly identical after normalization (markdown stripped, lowercased).
• Restated policies — two different lines that match the same phrase cluster. The built-in approval cluster covers approval-related language: "ask first/before", "wait for approval", "confirm before", "do not proceed without approval", and similar.

Directives are compared line by line, so bullet-style instructions are matched most reliably; a directive buried mid-paragraph is compared together with the rest of its wrapped line. Inline code is part of the comparison — Run `make test` and Run `make lint` are different directives. Three shapes are deliberately excluded: enumeration labels that only look like imperatives ("Run 2: Failed tests = […]" is example data, not an instruction), similar directives fewer than min-line-distance lines apart (neighboring bullets that share phrasing are intentional parallel structure), and colon-terminated captions directly above a code fence ("Add to customizations.vscode.extensions:" repeated across sections is a caption — the code below it is the real, differing content).

The two detection forms report differently: repeated/near-duplicate directives use the rule severity (warning by default), while cluster restatements always report at info — in long workflow files, matches like "requires confirmation" are often step-scoped ("this step requires confirmation" for two different steps) rather than one blanket policy stated twice, so they are review prompts, not defects. Headings never count as cluster matches: "### Require Explicit Approval" names a policy section, it doesn't restate the policy.

This differs from neighboring rules: content-instruction-drift compares whole sections across files; this rule compares individual directives within one file. content-contradiction flags directives that conflict; this rule flags directives that agree too much.

Examples

Bad (one directive stated twice, one policy stated two ways):

## Testing
- Run `make test` before every push.

## Releases
- Run `make test` before every push.
- Ask before force-pushing to a shared branch.

## Cleanup
- Wait for approval before deleting production data.

Good (each instruction and policy stated once):

## Testing
- Run `make test` before every push (this covers releases too).

## Approvals
- Ask before force-pushing to a shared branch or deleting
  production data.

How to fix

1. Keep the statement in the most load-bearing location (usually the dedicated section) and delete the other occurrences.
2. If the repeats were scoped differently ("ask before X", "ask before Y"), merge them into one policy statement listing the cases.
3. If two sections genuinely need the reminder, make one of them a short pointer to the other instead of a restatement.

Tune the rule in .skillsaw.yaml:

rules:
  content-repeated-directive:
    severity: warning
    similarity-threshold: 0.9    # (0-1]; higher = only near-verbatim repeats fire
    min-directive-words: 5       # ignore directives shorter than this
    min-line-distance: 4         # don't compare directives closer than this
    extra-clusters:              # project-specific restatement clusters
      deploy-source:
        - '\b(?:deploy|ship)\s+(?:only|exclusively)\b'

Suppress an intentional repeat (e.g. a safety-critical reminder you want in both places) with an inline directive:

<!-- skillsaw-disable-next-line content-repeated-directive -->
- Run `make test` before every push.

Configuration

rules:
  content-repeated-directive:
    enabled: auto  # true | false | auto
    severity: warning

Parameter	Description	Default
similarity-threshold	Similarity ratio (0-1] at or above which two directive lines in the same file are considered restatements; identical lines always fire	0.85
min-directive-words	Minimum number of words a directive line must contain to participate in similarity comparison (phrase clusters are not length-limited)	4
min-line-distance	Minimum number of lines between two directives before they are compared — neighboring similar bullets are usually intentional parallel structure, not repetition	4
extra-clusters	Additional phrase clusters keyed by cluster name, each a list of regex patterns that express the same policy; two different lines matching one cluster are flagged as restatements	{}

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