Skip to content

add-new-plugin.md category table has no tiebreaker rule — cross-cutting plugins land in inconsistent category files #153

@ooloth

Description

@ooloth

Current state

Agents placing a plugin that fits more than one category (e.g., a plugin that does both UI rendering and LSP integration, or one that affects both editing and navigation) have no documented rule for choosing which category file to use. The playbook at docs/playbooks/add-new-plugin.md lists 12 category files with one-line descriptions but states no tiebreaker. The result is that cross-cutting plugins accumulate in whichever category file the agent happens to inspect first, and any global vim.opt or keymap for that plugin inherits the wrong conceptual namespace. Over time this makes the category files harder to audit because the category boundaries are not enforced.

This is distinct from issue #44, which documents which tier to use (spec file vs lang file vs category file). This issue is about which category file to use when a plugin's primary feature spans more than one category.

Ideal state

  • docs/playbooks/add-new-plugin.md includes a tiebreaker rule that an agent can apply mechanically when a plugin fits two or more category descriptions (e.g., "choose the category that activates the plugin's primary feature, not a secondary integration it provides").
  • The tiebreaker rule is stated as a single sentence in the category table or immediately above it, so an agent reading the table encounters it before making a placement decision.
  • At least one example of a cross-cutting plugin is cited to illustrate the rule in action.

Starting points

  • /docs/playbooks/add-new-plugin.md — the category table that needs the tiebreaker
  • /lua/config/plugins/ — browse category files to identify plugins that span multiple categories and see where they currently live
  • /CLAUDE.md — the domain vocabulary section that defines category files

QA plan

  1. Read docs/playbooks/add-new-plugin.md and identify a plugin that could plausibly belong in two categories (e.g., a plugin that provides both a UI panel and LSP diagnostics). Apply the documented tiebreaker rule. Expect a single, unambiguous answer with no need to inspect source files.
  2. Verify the tiebreaker rule is visible before or within the category table, not buried in a later section.
  3. Verify at least one concrete example of a cross-cutting plugin is cited alongside the rule.

Done when

An agent reading docs/playbooks/add-new-plugin.md can place any cross-cutting plugin in the correct category file on the first attempt without inspecting existing category files for precedent.

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions