content-weak-language¶

Detect hedging, vague, and non-actionable language in instruction files


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

Why¶

Models treat hedged instructions as optional. Phrases like "try to", "if possible", "maybe consider", or "it would be good to" introduce ambiguity about whether an instruction is mandatory, and the model resolves that ambiguity by skipping the instruction whenever it conflicts with anything else in context. Direct, assertive language measurably improves instruction-following: Bsharat et al. found direct phrasing ("Your task is", "You MUST") yielded a 57.7% quality improvement over hedged equivalents.

Examples¶

Bad:

Try to run the tests before committing, if possible.
Consider using the project's logging helpers where appropriate.

Good:

Run the tests before committing.
Use the project's logging helpers.

When not to flag¶

Genuinely conditional guidance is fine when the condition is concrete — "If the build fails, check the lockfile first" is actionable, not hedged. The rule targets hedges that leave the decision to the model, not conditions the model can evaluate.

How to fix¶

Rewrite the instruction as an imperative: state what to do, not what to attempt. If you cannot state it unconditionally, spell out the concrete condition instead of hedging. A coding agent can rewrite flagged lines automatically.

Configuration¶

rules:
  content-weak-language:
    enabled: auto  # true | false | auto
    severity: warning

Research Basis¶

Detects hedging and vague language ("try to", "maybe consider", "if possible") in instruction files.

LLMs respond to direct, assertive instructions. Hedging language introduces ambiguity about whether the instruction is mandatory or optional, and the model may treat it as the latter. Bsharat et al. tested 26 prompting principles and found that direct language ("Your task is", "You MUST") yielded 57.7% quality improvement over hedged equivalents.

Anthropic's own prompting guide says: "Claude performs best with clear, direct instructions." OpenAI's guide echoes this: "The more specific and detailed your instructions, the more likely you'll receive the output you want."

References:

Bsharat et al., Principled Instructions Are All You Need for Questioning LLaMA-1/2, GPT-3.5/4 (arXiv:2312.16171, Dec 2023) — Principles #1 and #6
Anthropic Prompting Best Practices — "Be clear and direct"
OpenAI Prompt Engineering Guide — "Write clear instructions"

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