Write seed lint-lesson files for negotiation-prone cops #519

New issue

Open

opened 2026-08-26 21:33:59 +00:00 by jared · 2 comments

jared commented

2026-08-26 21:33:59 +00:00

Owner

Context

The lint-lessons relay (built 2026-08-26) maps cop name → .sdlc/lint-lessons/.md, but no lesson files exist yet. Without content the mechanism is inert. Motivating case: Metrics/ParameterLists tripped and the agent requested an exemption because nothing explained the POODR meaning (long parameter list = class doing too much; extract a concrete collaborator, pass it, query via duck type).

Tasks

Mine candidates offline from the #507 violations DB: ViolationsQuery keys minus existing lesson files
Write Metrics/ParameterLists lesson first (POODR extraction guidance)
Lessons for the os-aidd length cops (SkillFileLength/ClaudeMdFileLength successor) and Sdlc/StepBulk
Each lesson ~200-400 tokens: the smell, why the threshold is a clue, fix hierarchy, ONE before/after example, legitimate-exemption criteria

Acceptance criteria

Lessons render through LessonRelay in a real gate failure
Each lesson passes the linter's own token budget (no recursive bloat)

Origin

Trigger: lint-lessons design session 2026-08-26; parameter-lists exemption-request incident recounted by the user
Improvised this session: none
Chain: agents mis-fix or negotiate away offenses ← offense messages carry thresholds without design meaning ← DESIGN (feedback-lint-cop-messages-need-prescription; lesson-relay implementation this session)
Root candidate: this ticket

## Context The lint-lessons relay (built 2026-08-26) maps cop name → .sdlc/lint-lessons/<kebab-name>.md, but no lesson files exist yet. Without content the mechanism is inert. Motivating case: Metrics/ParameterLists tripped and the agent requested an exemption because nothing explained the POODR meaning (long parameter list = class doing too much; extract a concrete collaborator, pass it, query via duck type). ## Tasks - [ ] Mine candidates offline from the #507 violations DB: ViolationsQuery keys minus existing lesson files - [ ] Write Metrics/ParameterLists lesson first (POODR extraction guidance) - [ ] Lessons for the os-aidd length cops (SkillFileLength/ClaudeMdFileLength successor) and Sdlc/StepBulk - [ ] Each lesson ~200-400 tokens: the smell, why the threshold is a clue, fix hierarchy, ONE before/after example, legitimate-exemption criteria ## Acceptance criteria - [ ] Lessons render through LessonRelay in a real gate failure - [ ] Each lesson passes the linter's own token budget (no recursive bloat) ## Origin - Trigger: lint-lessons design session 2026-08-26; parameter-lists exemption-request incident recounted by the user - Improvised this session: none - Chain: agents mis-fix or negotiate away offenses ← offense messages carry thresholds without design meaning ← DESIGN (feedback-lint-cop-messages-need-prescription; lesson-relay implementation this session) - Root candidate: this ticket

jared added the

plugin/os-sdlc

label

2026-08-26 21:33:59 +00:00

jared commented

2026-10-02 16:57:09 +00:00

Author

Owner

ADR-0265 replaces this ticket's lesson section list with the signal-first list: The signal; What it is a sign of; Why it matters; Your decision; Correction; Example. Lesson text must be codebase-independent: generic names, never names from this codebase.

jared commented

2026-10-02 17:06:03 +00:00

Author

Owner

Update 2026-10-02: lint lessons now ship with the plugin (ADR-0266, amends ADR-0265), in plugins/os-sdlc/lint-lessons/.md. The project's .sdlc/lint-lessons/ is no longer read after #908. Seed lessons written under this ticket belong in the plugin directory. Section list: ADR-0265 decision 4.

Update 2026-10-02: lint lessons now ship with the plugin (ADR-0266, amends ADR-0265), in plugins/os-sdlc/lint-lessons/<kebab-cop-name>.md. The project's .sdlc/lint-lessons/ is no longer read after #908. Seed lessons written under this ticket belong in the plugin directory. Section list: ADR-0265 decision 4.

jared added the

category/prose-artifact

label

2026-10-10 13:32:10 +00:00