aidd-lint rule: sentence-complexity

jared commented

2026-07-23 11:31:18 +00:00

Owner

Problem

Sentences too long/complex to parse or grep. Verbatim, plugins/os-sdlc/skills/mine-lints/SKILL.md:47-52 as of 5ea6bbf (trimmed in c6a4177):

4. **Ticket per novel rule.** One Forgejo ticket per rule: title
   `os-sdlc lint rule: <short-name>`, body following
   `plugins/os-sdlc/reference/lint-rule-ticket-template.md` exactly (verbatim offending
   snippet + file:line, Detection with the exact failure-message string, Correction
   before/after diff, pass/fail examples, Provenance, implementation plan).

One ~40-word sentence with a six-item parenthetical. Pre-AI readability tooling (Flesch-Kincaid, Gunning fog -- the SEO-era grade-level scores) is pure arithmetic over word/sentence/syllable counts and applies unchanged; retrieval and instruction-following degrade on long clause chains the same way human skimming does.

Detection

Inputs: a markdown file; config from .aidd-lint.yml (defaults: max_words_per_sentence: 30, max_grade_level: 12 advisory). Tunable.
Algorithm:
1. Strip code fences, inline code spans, tables, frontmatter, link URLs.
2. Split remaining prose into sentences on /[.!?]\s+(?=[A-Z"'(])/` (deterministic heuristic; abbreviation false-splits acceptable at this threshold).
3. Word count per sentence > max_words_per_sentence -> offense.
4. Per top-level section, compute Flesch-Kincaid grade (deterministic syllable heuristic); over max_grade_level -> advisory-severity offense.
Failure message (verbatim contract): "<file>:<line>: sentence is <N> words (max <T>). Split it -- one instruction per sentence."
Advisory message: "<file> section '<name>': reads at grade <G> (advisory max <T>). Consider shorter sentences and plainer words."

Correction

-4. **Ticket per novel rule.** One Forgejo ticket per rule: title `os-sdlc lint rule: <short-name>`, body following `plugins/os-sdlc/reference/lint-rule-ticket-template.md` exactly (verbatim offending snippet + file:line, Detection with the exact failure-message string, Correction before/after diff, pass/fail examples, Provenance, implementation plan).
+4. **Ticket per novel rule.** One Forgejo ticket per rule: title `os-sdlc lint rule: <short-name>`, body following `plugins/os-sdlc/reference/lint-rule-ticket-template.md` exactly, including its pre-filing consistency check.

Pass/fail examples

Must fail: the 40-word sentence above.
Must pass: every sentence in plugins/os-sdlc/skills/implement/SKILL.md; a 40-token line inside a code fence; a long literal path in inline code (stripped before counting).

Provenance

mine-lints simplification 2026-07-23; user-proposed sister rule to step-bulk. Part of the aidd-lint system (see mapping ticket).

Implementation plan

AUDIT DEFAULTS FIRST: check Ruby readability gems (e.g. odyssey) before hand-rolling FK scoring; the words-per-sentence check is trivial either way. TDD with fixtures.

## Problem Sentences too long/complex to parse or grep. Verbatim, `plugins/os-sdlc/skills/mine-lints/SKILL.md:47-52` as of 5ea6bbf (trimmed in c6a4177): ``` 4. **Ticket per novel rule.** One Forgejo ticket per rule: title `os-sdlc lint rule: <short-name>`, body following `plugins/os-sdlc/reference/lint-rule-ticket-template.md` exactly (verbatim offending snippet + file:line, Detection with the exact failure-message string, Correction before/after diff, pass/fail examples, Provenance, implementation plan). ``` One ~40-word sentence with a six-item parenthetical. Pre-AI readability tooling (Flesch-Kincaid, Gunning fog -- the SEO-era grade-level scores) is pure arithmetic over word/sentence/syllable counts and applies unchanged; retrieval and instruction-following degrade on long clause chains the same way human skimming does. ## Detection - **Inputs:** a markdown file; config from `.aidd-lint.yml` (defaults: `max_words_per_sentence: 30`, `max_grade_level: 12` advisory). Tunable. - **Algorithm:** 1. Strip code fences, inline code spans, tables, frontmatter, link URLs. 2. Split remaining prose into sentences on `/[.!?]\s+(?=[A-Z`"'(])/` (deterministic heuristic; abbreviation false-splits acceptable at this threshold). 3. Word count per sentence > `max_words_per_sentence` -> offense. 4. Per top-level section, compute Flesch-Kincaid grade (deterministic syllable heuristic); over `max_grade_level` -> advisory-severity offense. - **Failure message (verbatim contract):** `"<file>:<line>: sentence is <N> words (max <T>). Split it -- one instruction per sentence."` - Advisory message: `"<file> section '<name>': reads at grade <G> (advisory max <T>). Consider shorter sentences and plainer words."` ## Correction ```diff -4. **Ticket per novel rule.** One Forgejo ticket per rule: title `os-sdlc lint rule: <short-name>`, body following `plugins/os-sdlc/reference/lint-rule-ticket-template.md` exactly (verbatim offending snippet + file:line, Detection with the exact failure-message string, Correction before/after diff, pass/fail examples, Provenance, implementation plan). +4. **Ticket per novel rule.** One Forgejo ticket per rule: title `os-sdlc lint rule: <short-name>`, body following `plugins/os-sdlc/reference/lint-rule-ticket-template.md` exactly, including its pre-filing consistency check. ``` ## Pass/fail examples - **Must fail:** the 40-word sentence above. - **Must pass:** every sentence in `plugins/os-sdlc/skills/implement/SKILL.md`; a 40-token line inside a code fence; a long literal path in inline code (stripped before counting). ## Provenance mine-lints simplification 2026-07-23; user-proposed sister rule to step-bulk. Part of the aidd-lint system (see mapping ticket). ## Implementation plan AUDIT DEFAULTS FIRST: check Ruby readability gems (e.g. `odyssey`) before hand-rolling FK scoring; the words-per-sentence check is trivial either way. TDD with fixtures.

jared referenced this issue

2026-07-23 11:31:45 +00:00

aidd-lint: system map (umbrella) #109

jared referenced this issue

2026-07-23 12:09:09 +00:00

aidd-lint: system map (umbrella) #109

jared added the

review

label

2026-07-23 12:44:03 +00:00

jared commented

2026-07-23 12:44:03 +00:00

Author

Owner

Implemented on branch aidd-lint/tier-1 (plugins/os-aidd-lint, cop: sentence_complexity.rb). 55-test suite green; report-only corpus scan run. Awaiting human review — open items noted on #109.

jared commented

2026-07-23 12:44:22 +00:00

Author

Owner

Implemented on branch aidd-lint/tier-1 (plugins/os-aidd-lint, cop: sentence_complexity.rb). 55-test suite green; report-only corpus scan run. Awaiting human review — open items noted on #109.

jared referenced this issue

2026-07-23 12:44:29 +00:00

aidd-lint: system map (umbrella) #109

jared added the

labels

2026-08-01 16:39:22 +00:00

jared commented

2026-08-01 16:43:41 +00:00

Author

Owner

This was generated by AI during triage.

Implemented on main: lib/aidd_lint/cops/sentence_complexity.rb, registered in registry.rb (SentenceComplexity), tests at tests/cops/sentence_complexity_test.rb (13 runs, 33 assertions, 0 failures). Closing.

> *This was generated by AI during triage.* Implemented on main: `lib/aidd_lint/cops/sentence_complexity.rb`, registered in `registry.rb` (SentenceComplexity), tests at `tests/cops/sentence_complexity_test.rb` (13 runs, 33 assertions, 0 failures). Closing.

jared closed this issue

2026-08-01 16:43:42 +00:00

Rows
Columns

aidd-lint rule: sentence-complexity #105

Problem

Detection

Correction

Pass/fail examples

Provenance

Implementation plan