aidd-lint rule: step-bulk

jared commented

2026-07-23 11:30:58 +00:00

Owner

Problem

Workflow steps too bulky to read at a glance. Verbatim, plugins/os-sdlc/skills/mine-lints/SKILL.md:23-28 as of 5ea6bbf (fixed in c6a4177):

2. **Triage: mechanical vs. residue.** For each finding, judge whether it generalizes to a
   mechanically lintable pattern (state the inputs/algorithm/exact failure message) or stays
   reviewer residue (a real but non-lintable judgment call -- e.g. "same string parsed in two
   places" was correctly left unticketed last time). A finding may split into a lintable half
   and a residue half. Disclose any scoping choice made to avoid false positives (e.g.
   same-file-only call-chain matching).

Six lines of criteria embedded in one step. Gate logic in prose has no lexical signature but reliably makes steps long -- bulk is the deterministic proxy.

Detection

Inputs: a markdown file; config thresholds from .aidd-lint.yml (defaults: max_lines: 4, max_words: 60, max_paragraphs: 1, max_bullet_depth: 1). Thresholds are explicitly tunable config, not constants.
Algorithm:
1. Select /workflow|process|steps/i sections; parse each numbered list item.
2. Per item compute: prose line count, word count, paragraph count, max nested-bullet depth.
3. Any metric over threshold -> offense. Branch the message on whether the item links a references/-style .md.
Failure messages (verbatim contracts):
- no pointer: "<file>:<line>: step is <N> lines (max <T>) with no reference pointer. Move the detail to a references/*.md file and point to it."
- has pointer: "<file>:<line>: step is <N> lines (max <T>) despite pointing at <ref>. Trim the step to the instruction plus the pointer."

Correction

-2. **Triage: mechanical vs. residue.** For each finding, judge whether it generalizes to a
-   mechanically lintable pattern (state the inputs/algorithm/exact failure message) or stays
-   reviewer residue (a real but non-lintable judgment call -- e.g. "same string parsed in two
-   places" was correctly left unticketed last time). A finding may split into a lintable half
-   and a residue half. Disclose any scoping choice made to avoid false positives (e.g.
-   same-file-only call-chain matching).
+2. **Triage.** Split each finding into mechanical vs. reviewer residue, per
+   `references/reconcile-gate.md`.

Pass/fail examples

Must fail: the six-line step above (6 lines, no pointer); a five-line step that links references/x.md (has-pointer message).
Must pass: every step in plugins/os-sdlc/skills/implement/SKILL.md (1-3 lines each); a 2-line step with no pointer.

Provenance

mine-lints simplification 2026-07-23, commit c6a4177. Known gaming risk: splitting one fat step into several thin ones that are still gate logic -- the Tier-2 charter pass exists to catch that; ship together.

Implementation plan

Same markdown-lint infra as workflow-war-story; TDD with fixtures; config loading tested explicitly.

## Problem Workflow steps too bulky to read at a glance. Verbatim, `plugins/os-sdlc/skills/mine-lints/SKILL.md:23-28` as of 5ea6bbf (fixed in c6a4177): ``` 2. **Triage: mechanical vs. residue.** For each finding, judge whether it generalizes to a mechanically lintable pattern (state the inputs/algorithm/exact failure message) or stays reviewer residue (a real but non-lintable judgment call -- e.g. "same string parsed in two places" was correctly left unticketed last time). A finding may split into a lintable half and a residue half. Disclose any scoping choice made to avoid false positives (e.g. same-file-only call-chain matching). ``` Six lines of criteria embedded in one step. Gate logic in prose has no lexical signature but reliably makes steps long -- bulk is the deterministic proxy. ## Detection - **Inputs:** a markdown file; config thresholds from `.aidd-lint.yml` (defaults: `max_lines: 4`, `max_words: 60`, `max_paragraphs: 1`, `max_bullet_depth: 1`). Thresholds are explicitly tunable config, not constants. - **Algorithm:** 1. Select `/workflow|process|steps/i` sections; parse each numbered list item. 2. Per item compute: prose line count, word count, paragraph count, max nested-bullet depth. 3. Any metric over threshold -> offense. Branch the message on whether the item links a `references/`-style .md. - **Failure messages (verbatim contracts):** - no pointer: `"<file>:<line>: step is <N> lines (max <T>) with no reference pointer. Move the detail to a references/*.md file and point to it."` - has pointer: `"<file>:<line>: step is <N> lines (max <T>) despite pointing at <ref>. Trim the step to the instruction plus the pointer."` ## Correction ```diff -2. **Triage: mechanical vs. residue.** For each finding, judge whether it generalizes to a - mechanically lintable pattern (state the inputs/algorithm/exact failure message) or stays - reviewer residue (a real but non-lintable judgment call -- e.g. "same string parsed in two - places" was correctly left unticketed last time). A finding may split into a lintable half - and a residue half. Disclose any scoping choice made to avoid false positives (e.g. - same-file-only call-chain matching). +2. **Triage.** Split each finding into mechanical vs. reviewer residue, per + `references/reconcile-gate.md`. ``` ## Pass/fail examples - **Must fail:** the six-line step above (6 lines, no pointer); a five-line step that links `references/x.md` (has-pointer message). - **Must pass:** every step in `plugins/os-sdlc/skills/implement/SKILL.md` (1-3 lines each); a 2-line step with no pointer. ## Provenance mine-lints simplification 2026-07-23, commit c6a4177. Known gaming risk: splitting one fat step into several thin ones that are still gate logic -- the Tier-2 charter pass exists to catch that; ship together. ## Implementation plan Same markdown-lint infra as workflow-war-story; TDD with fixtures; config loading tested explicitly.

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:02 +00:00

jared commented

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

Author

Owner

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

jared added the

labels

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

jared commented

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

Author

Owner

This was generated by AI during triage.

Implemented on main: lib/aidd_lint/cops/step_bulk.rb, registered in registry.rb (StepBulk), tests at tests/cops/step_bulk_test.rb (14 runs, 35 assertions, 0 failures). Closing.

> *This was generated by AI during triage.* Implemented on main: `lib/aidd_lint/cops/step_bulk.rb`, registered in `registry.rb` (StepBulk), tests at `tests/cops/step_bulk_test.rb` (14 runs, 35 assertions, 0 failures). Closing.

jared closed this issue

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

Rows
Columns

aidd-lint rule: step-bulk #101

Problem

Detection

Correction

Pass/fail examples

Provenance

Implementation plan