signal-over-noise（信噪比）

Signal Over Noise

Maximize useful information per word. Remove everything that doesn't earn its space.

What This Is

Signal = information that moves the reader toward action or understanding. Noise = filler, explanations of obvious things, hedging language, unnecessary context.

High signal-to-noise ratio means readers get what they need faster. Every word counts.

When to Use

• Writing documentation, guides, skill descriptions
• Creating error messages and feedback
• Structuring arguments or explanations
• Naming things (variables, functions, branches)
• Any communication where clarity matters

How to Apply

1. Remove Filler Words

High noise:

• "basically"
• "essentially"
• "in order to"
• "comprehensive"
• "helpful"
• "I think that"
• "it could be argued that"

Before: "Basically, you should essentially use this pattern in order to get comprehensive error handling."

After: "Use this pattern for error handling."

2. Cut Explanations of Obvious Things

Don't explain what readers already know. Assume competence.

Before: "Rust is a programming language. In Rust, you write code. This code runs on computers. When you compile Rust code, it produces a binary executable file."

After: "Compile Rust code to a binary with cargo build --release."

3. Front-Load the Point

Put the actionable information first. Context follows.

Before: "There are several reasons why you might want to consider testing your code. First, testing helps catch bugs. Second, it makes refactoring safer. Most importantly, tests serve as documentation. You should write tests."

After: "Write tests to catch bugs, enable safe refactoring, and document behavior."

4. Use Active, Direct Language

High noise: "It is recommended that consideration be given to..."

Signal: "Consider..."

High noise: "The file was created by the user."

Signal: "Create the file."

5. One Idea Per Sentence

Long sentences hide the point. Break them.

Before: "When you're writing code that handles errors, which can happen in many places throughout your application, you should think about whether you want to handle them at the point where they occur or propagate them upward, and this decision affects how you structure your code."

After: "Handle errors where they occur or propagate them upward. This choice shapes your code structure. Decide early."

6. Name Things Precisely

Names are communication. Bad names add noise; good names clarify.

High noise: process_data(), handle_thing(), do_stuff()

Signal: validate_user_input(), retry_failed_request(), parse_json_config()

7. Omit Context Readers Already Have

Don't repeat what's obvious from surrounding text.

Before: "Here's an example of how to use the feature. In this example, we show you how to use it."

After: "Example:"

Trade-offs

When NOT to apply aggressively

• Teaching beginners: Some explanatory redundancy helps them build intuition
• Safety-critical systems: Explicit redundancy catches misunderstanding
• Legal/compliance docs: Specificity sometimes requires verbose phrasing
• User research notes: Capture raw data, organize later

The balance

Signal-over-noise isn't "be terse." It's "be useful." Sometimes that means:

• Repeating a key phrase for emphasis
• Providing context that prevents misreading
• Showing your work so readers can verify reasoning
• Acknowledging limitations explicitly

Remove noise, keep signal. Don't remove useful context.

Examples

Code Documentation

Before:

This function is useful for validating email addresses.
It takes a string as input, which represents the email address
that you want to check. The function will return true if the
email is valid, or false if it is not valid. You might want to
use this function when you need to validate emails.

After:

Validate email addresses. Returns true if valid, false otherwise.

Error Messages

Before:

An error has occurred in the system. The operation you attempted
could not be completed successfully. Please try again later or
contact support if the problem persists.

After:

Failed to fetch user data. Retry or contact support.

Skill Description

Before:

This skill helps you think about how to communicate more effectively
by using techniques that are designed to help you reduce unnecessary
information and focus on the important parts of what you're trying
to say so that your readers understand your message better and faster.

After:

Maximize useful information per word. Remove filler, obvious explanations, and hedging language. Every word should earn its space.

Testing

How to know if you've applied this principle:

1. Read it aloud. Does every sentence move you forward?
2. Ask "why?" for each phrase. If the answer is "readers already know this," cut it.
3. Count words. Did you reduce the word count by 20–40%? Good sign.
4. Test comprehension. Can a fresh reader understand it without re-reading?
5. Check names. Are function/variable names predictable and specific?

Application in Syncpack

This principle strengthens all your other skills:

• write-code: Function names, comments, commit messages all benefit
• document-code: Docs communicate faster when noise is removed
• add-feature: Feature descriptions and changelogs stay concise
• fix-bug: Error messages become actionable, not explanatory
• search-code: Clear naming makes code more discoverable

Apply signal-over-noise across the board. Your CLAUDE.md already mandates it—this skill formalizes how.