content-repeated-directive

Detect the same directive stated more than once within a file

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

Why

Stating the same instruction multiple times doesn't improve model adherence. Modern prompting guides (such as OpenAI's GPT-5.6 prompting guide) recommend stating each instruction once clearly. Repetitive directives add unnecessary tokens and can create conflicting nuances without improving behavior. Every repeat also uses instruction budget that could be used for other rules (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 (such as the built-in approval cluster: "ask first/before", "wait for approval", "confirm before", or "do not proceed without approval").

Directives are compared line by line across sections within a file. Both forms report at info: deciding whether two similar instructions are redundant or intentionally distinct is a developer choice, so the rule surfaces the opportunity without failing a build. You can raise severity to warning or error in .skillsaw.yaml for stricter enforcement; phrase cluster restatements stay at info.

Intentional parallel structures (such as neighboring list items, parameterized code examples, or section captions directly above code blocks) are excluded from comparison.

This differs from neighboring rules: content-instruction-drift compares whole sections across files, whereas this rule compares individual directives within one file.

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            # default is info; raise it to fail a build
    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
    similarity-max-directives: 1500  # cap on directives entering pairwise comparison
    extra-clusters:              # project-specific restatement clusters
      deploy-source:
        - '\b(?:deploy|ship)\s+(?:only|exclusively)\b'

similarity-max-directives caps the number of directives evaluated per file (default 1500). Raise this setting if you maintain exceptionally large instruction files.

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: info

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
similarity-max-directives	Maximum number of directives per file entering pairwise similarity comparison; directives beyond the cap are still checked for exact repeats (a linear scan) but skip the quadratic near-duplicate stage	1500
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.