cli/framework/rules/core/ideal-instruction/rule.md at main · reporails/cli · GitHub
//blob/show" data-turbo-transient="true" />
Skip to content
Search/
Sign in<br>Sign upAppearance settings
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
Uh oh!
There was an error while loading. Please reload this page.
reporails
cli
Public
Uh oh!
There was an error while loading. Please reload this page.
Notifications<br>You must be signed in to change notification settings
Fork
Star<br>74
FilesExpand file tree
main
/rule.md
Copy path
Blame<br>More file actions
Blame<br>More file actions
Latest commit
History<br>History<br>History
60 lines (46 loc) · 2.71 KB
main
/rule.md
Copy path
Top
File metadata and controls<br>Preview
Code
Blame
60 lines (46 loc) · 2.71 KB
Raw<br>Copy raw file<br>Download raw file
OutlineEdit and raw actions
id<br>CORE:C:0053
slug<br>ideal-instruction
title<br>The Ideal Instruction
category<br>coherence
type<br>mechanical
execution<br>server
severity<br>medium
match
fix<br>Strengthen the weak instructions. For each weak finding, apply the<br>named-construct pattern (`backtick`-wrap a specific tool / file /<br>command), the imperative-modality pattern (replace "consider" /<br>"try" / "should" with direct verbs), and the elaboration pattern<br>(target 15-50 distinct tokens per instruction). See `ails explain<br>CORE:C:0053` for the full ideal-instruction shape.
The Ideal Instruction
An instruction competes for attention against everything else in context. The strongest instructions dominate; weak instructions are effectively invisible.
Five properties determine instruction strength (they multiply): specificity (name exact constructs), modality (use direct commands), elaboration (15-50 distinct terms), position (place critical instructions last), and topic relevance (instruction matches the task). The gap between a well-written and poorly-written instruction is enormous.
Antipatterns
Hedged language : "You might want to consider using ruff for formatting." Hedged modality weakens the instruction — direct commands ("Use ruff for formatting") are stronger.
Generic terms instead of named constructs : "Use a linter for code quality" instead of "Use ruff check for linting." Specificity requires naming the exact tool, file, or command.
Constraint-first ordering : "Don't use black. Use ruff instead." Leading with the prohibition activates the wrong concept first. Directive-first ordering is more effective.
Terse instructions without elaboration : "Format code." Too few distinct tokens — the instruction lacks the detail needed to compete for attention in context.
Pass / Fail
Pass
Use `ruff check --fix` for all linting in `src/` and `tests/`. The project<br>enforces consistent style through pre-commit hooks. *Do NOT run `black`<br>or apply manual formatting.*
Fail
You should probably consider formatting your code consistently.
Fix
Elaborate with distinct relevant terms — the single largest improvement factor
Use exact names — unittest.mock, not "mocking libraries"
Order: directive first, reasoning, constraint last
Place critical instructions last in the file
Use direct commands, not hedged language
One instruction per topic (eliminates same-topic competition)
Keep surrounding same-topic prose brief (reduces attention dilution)
Limitations
This is a composite diagnostic summarizing the overall strength of instructions in a file. Individual factors are reported by their own rules (specificity-gap, modality-weakness, etc.).
You can’t perform that action at this time.