os-aidd-lint: Tier-1 advisory cop — extract trigger clauses from description into when_to_use #190

New issue

Closed

opened 2026-07-31 14:40:35 +00:00 by jared · 2 comments

jared commented

2026-07-31 14:40:35 +00:00

Owner

Approved 2026-07-31: amend the Tier-2 duplicated-authority charter entry with a fourth structural scale — frontmatter field-vs-field duplication (description vs when_to_use, which Claude Code concatenates under one shared 1,536-char routing cap; see skill_description_budget.rb header). Amendment draft exists (see session context / issue #189's sibling work). BLOCKED: catalog discipline requires a verbatim in-repo exemplar, and a full scan (2026-07-31) found zero other SKILL.md files using when_to_use at all — the only instance (cc-architect) was already fixed. Unblock when a real when_to_use-bearing skill exhibits the duplication; then: amending ADR (precedent 0062/0063/0068), charter edit per its change-control banner, update charter_test/judge_test pins. Alternative noted by the scan: description-internal trigger-clause duplication (os-vault/os-adr/os-backlog skills) is a different smell shape and would need its own decision.

Approved 2026-07-31: amend the Tier-2 `duplicated-authority` charter entry with a fourth structural scale — frontmatter field-vs-field duplication (`description` vs `when_to_use`, which Claude Code concatenates under one shared 1,536-char routing cap; see skill_description_budget.rb header). Amendment draft exists (see session context / issue #189's sibling work). BLOCKED: catalog discipline requires a verbatim in-repo exemplar, and a full scan (2026-07-31) found zero other SKILL.md files using `when_to_use` at all — the only instance (cc-architect) was already fixed. Unblock when a real when_to_use-bearing skill exhibits the duplication; then: amending ADR (precedent 0062/0063/0068), charter edit per its change-control banner, update charter_test/judge_test pins. Alternative noted by the scan: description-internal trigger-clause duplication (os-vault/os-adr/os-backlog skills) is a different smell shape and would need its own decision.

jared changed title from ~~os-aidd-lint: duplicated-authority fourth scale (description vs when_to_use) — approved, blocked on exemplar~~ to os-aidd-lint: Tier-1 advisory cop — extract trigger clauses from description into when_to_use

2026-07-31 14:56:24 +00:00

jared commented

2026-07-31 14:56:27 +00:00

Author

Owner

Reframed 2026-07-31 after owner review. The original premise (Tier-2 duplicated-authority fourth scale, blocked on an exemplar) is retired: cc-architect was simply the first when_to_use adopter, and description-vs-when_to_use duplication is an artifact, not the smell. The actual rule wanted: a Tier-1 ADVISORY cop that detects trigger phrasing inside the description frontmatter field (patterns like 'Use unprompted WHEN', 'Use when', 'Trigger on', 'Triggers:', 'Invoked by' trigger clauses) and recommends extracting it into when_to_use, leaving description as the capability sentence. Rationale: both fields concatenate for routing (shared 1,536-char cap), so placement is style — but the normalized style is capability in description, triggers in when_to_use; body placement remains a true defect and is already covered by skill-trigger-in-body. Exemplar corpus is abundant: os-vault query/write, os-adr create/find, os-backlog capture/route SKILL.md descriptions all embed 'Use unprompted WHEN…' clauses. No Tier-2 catalog change and no ADR-0060 amendment needed. Implementation should follow the existing cop pattern (see MissingArgumentsFrontmatter for a recent example) with minitest coverage, and be self-tested against the exemplar corpus.

Reframed 2026-07-31 after owner review. The original premise (Tier-2 duplicated-authority fourth scale, blocked on an exemplar) is retired: cc-architect was simply the first when_to_use adopter, and description-vs-when_to_use duplication is an artifact, not the smell. The actual rule wanted: a Tier-1 ADVISORY cop that detects trigger phrasing inside the `description` frontmatter field (patterns like 'Use unprompted WHEN', 'Use when', 'Trigger on', 'Triggers:', 'Invoked by' trigger clauses) and recommends extracting it into `when_to_use`, leaving description as the capability sentence. Rationale: both fields concatenate for routing (shared 1,536-char cap), so placement is style — but the normalized style is capability in description, triggers in when_to_use; body placement remains a true defect and is already covered by skill-trigger-in-body. Exemplar corpus is abundant: os-vault query/write, os-adr create/find, os-backlog capture/route SKILL.md descriptions all embed 'Use unprompted WHEN…' clauses. No Tier-2 catalog change and no ADR-0060 amendment needed. Implementation should follow the existing cop pattern (see MissingArgumentsFrontmatter for a recent example) with minitest coverage, and be self-tested against the exemplar corpus.

jared added the

review

label

2026-07-31 15:25:59 +00:00

jared referenced this issue from a commit

2026-07-31 15:50:02 +00:00

Add Tier-1 advisory cops MissingArgumentsFrontmatter and DescriptionTriggerPhrasing

jared commented

2026-07-31 18:54:20 +00:00

Author

Owner

Already implemented: DescriptionTriggerPhrasing cop (advisory severity) in plugins/os-aidd-lint/lib/aidd_lint/cops/description_trigger_phrasing.rb — verified firing via bin/aidd-lint. Closing as done.

jared closed this issue

2026-07-31 18:54:22 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

jared/cc-os#190

No description provided.

Rows
Columns