https://github.com/tbhb/vale-ears
A Vale style package for validating requirements written in EARS (Easy Approach to Requirements Syntax)
https://github.com/tbhb/vale-ears
ears linter prose-linter requirements requirements-engineering style-guide systems-engineering technical-writing vale vale-linter-style vale-style writing
Last synced: 4 days ago
JSON representation
A Vale style package for validating requirements written in EARS (Easy Approach to Requirements Syntax)
- Host: GitHub
- URL: https://github.com/tbhb/vale-ears
- Owner: tbhb
- License: mit
- Created: 2026-06-12T05:17:10.000Z (about 1 month ago)
- Default Branch: main
- Last Pushed: 2026-06-12T05:59:39.000Z (about 1 month ago)
- Last Synced: 2026-06-12T07:19:35.232Z (about 1 month ago)
- Topics: ears, linter, prose-linter, requirements, requirements-engineering, style-guide, systems-engineering, technical-writing, vale, vale-linter-style, vale-style, writing
- Language: Just
- Homepage:
- Size: 22.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# vale-ears
A [Vale](https://vale.sh/) package for validating requirements written in the [EARS (Easy Approach to Requirements Syntax)](https://alistairmavin.com/ears/) format.
EARS constraints natural language into a structured, standardized format to reduce ambiguity and improve consistency in requirements engineering.
## Rules
### `ears.Syntax`
Checks that any sentence containing the word `shall` conforms to one of the standard EARS patterns:
- **Ubiquitous:** the `` shall ``
- **Event-driven:** when ``, the `` shall ``
- **State-driven:** while ``, the `` shall ``
- **Unwanted behavior:** if ``, then the `` shall ``
- **Optional feature:** where ``, the `` shall ``
### `ears.Shall`
Ensures that requirements use the word `shall` rather than `must`, `will`, `should`, or `may` (which formal requirements commonly discourage).
### `ears.PassiveVoice` (and `ears.PassiveVoiceAdverb`)
Ensures requirements use the active voice. EARS dictates that the system (or user) must explicitly be the actor performing the action.
### `ears.WeakWords`
Flags words that introduce ambiguity into requirements (such as `approximately`, `usually`, `several`, `fast`, `robust`, `user-friendly`). Requirements should be precise and measurable.
## Examples
The following are valid EARS requirements:
The system shall log all errors.
When a user logs in, the system shall display the dashboard.
While the server is running, the application shall accept connections.
If the network drops, then the system shall retry the connection.
Where the system detects a camera, the application shall record video.
The following are examples of **violations** that `vale-ears` will flag:
- `ears.Syntax`: "The system shall, when it receives a message, log the error." (Does not match a standard EARS template)
- `ears.Shall`: "The system must log all errors." (Uses `must` instead of `shall`)
- `ears.PassiveVoice`: "All errors shall be logged by the system." (Written in passive voice)
- `ears.WeakWords`: "The system shall load the dashboard fast." (Uses ambiguous weak words like `fast`)
## Installation
Add the package to your `.vale.ini`:
```ini
Packages = https://github.com/tbhb/vale-ears/releases/latest/download/ears.zip
[*.md]
BasedOnStyles = ears
```
Then run:
```bash
vale sync
```
## Contributing
See the `Justfile` for development commands.