Skip to content

Decouple complexity-classification rubric from its consumers #622

Description

@williamthorsen

Problem

packages/agents/content/skills/_data/complexity-classification.md has a "Consumer levels" section that enumerates each consuming skill by name and pairs it with that consumer's level-to-decision mapping. This inverts the natural dependency direction: a shared rubric (the definitions of complexity levels) should be generic and unaware of who consumes it, but the current table makes the rubric aware of every consumer that uses it. Adding a new consumer or changing one's decision logic requires editing the foundation.

The coupling surfaced during issue #592: a regression fix to one consumer (next-steps-after-review) required mirroring an edit in complexity-classification.md's consumer-levels row, expanding the PR's scope into the rubric file even though the rubric's definitions themselves didn't change.

Context

Current shape (post-PR #557 / #592):

  • complexity-classification.md defines levels 1–4 with characteristics, AND lists per-consumer level-to-decision mappings in a "Consumer levels" table.
  • Each consumer (wrap-up drive-by, next-steps-after-plan, next-steps-after-review, planned orchestrated-architect) appears as a row with its own threshold and decision text.
  • A reader of any single consumer's file does not see the level-based decision in that file; they must cross-reference the rubric.

The rubric's level descriptions and the "when uncertain, prefer the higher level" rule are genuinely shared and belong in the rubric. The per-consumer decisions are not.

Considerations

  • Moving the per-consumer rows out preserves the rubric's reusability for future skills without requiring them to register back into the rubric first.
  • Each consumer's file becomes the single home for its decision logic, improving discoverability for maintainers reading individual consumer files.
  • The "Consumer levels" table currently provides a cross-cutting overview of consumer behavior. Losing that overview is the main cost; it can be partly mitigated by an index in the rubric file that links to each consumer's decision section (a registry of names, not of behavior).
  • The refactor is mechanical (content moves, not content changes), but touches 4–5 files atomically.

Proposed solution

  1. Move each consumer's level-to-decision content into a complexity-routing section within the consumer's own file:
    • wrap-up's drive-by-pass logic into the wrap-up skill body.
    • next-steps-after-plan row into a new section in next-steps-after-plan.md.
    • next-steps-after-review row into a new section in next-steps-after-review.md.
    • orchestrated-architect (planned) row: defer until that consumer exists; it can author its own section from the start.
  2. Remove the "Consumer levels" table from complexity-classification.md.
  3. Optionally replace the table with a one-line index listing the consumers and linking to their decision sections. This keeps the cross-cutting view available without re-introducing the dependency on consumer behavior.
  4. Update any cross-references in skills that point at the rubric's consumer table.

Acceptance criteria

  • complexity-classification.md no longer contains a "Consumer levels" table that enumerates consumers by name with their decisions.
  • Each existing consumer's level-to-decision mapping lives in the consumer's own file (or the file documenting the consumer's behavior).
  • A reader of any single consumer's file sees the complete complexity-based routing logic for that consumer without needing to cross-reference the rubric.
  • The rubric continues to define levels 1–4 with characteristics and the "when uncertain, prefer the higher level" rule.
  • Cross-references in other skills that pointed at the consumer-levels table are updated to point at each consumer's local decision section.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions