Skip to content

[Design tracker] Make rule timing and activation language predictable #888

Description

@malpern

User problem

KeyPath's rule editors do not teach one transferable mental model.

The same kinds of choices are described with different words, while some similar-sounding controls actually behave differently. Users cannot reliably predict what changing a timing value will do, transfer what they learned in one editor to another, or tell how a rule is activated. Leader and Hyper also appear as unexplained magic keys, and some community-derived names require outside knowledge.

This is a comprehension problem, not a request for a broad prose polish pass.

Desired outcome

A first-time user should be able to:

  • Understand what a control changes and what increasing its value will feel like.
  • Recognize the same concept when it appears in another rule editor.
  • Tell what they physically do to activate any rule.
  • Understand the difference between Leader and Hyper.
  • Choose a rule family without knowing its community source.

Workstreams

Additional one-off string fixes should be attached to the relevant workstream or filed as focused tickets. They should not accumulate here as one large implementation batch.

Sequencing

  1. Complete Explain Leader and Hyper wherever users encounter them #1202 because its terminology is already conceptually distinct and it provides immediate user value.
  2. Approve the vocabulary in Define a shared timing vocabulary for rule editors #1203.
  3. Create and implement timing-copy tickets by editor family, with behavior-specific tests and docs.
  4. Approve Choose and standardize the activation-hint format for rule families #1204 and apply its pattern in bounded catalog/editor slices.
  5. Resolve Decide descriptive names for community-derived rule families #1205 independently; it should not block clearer timing or activation language.

Completion criteria

  • Each design decision is recorded in its child issue.
  • Approved changes have been implemented in small, reviewable slices or deliberately declined.
  • User guides and copy-focused tests agree with the shipped UI.
  • No remaining editor exposes an unexplained timing term or activation mechanism identified by these workstreams.

Non-goals

  • One pull request that rewrites every editor.
  • Changing rule behavior as part of copy cleanup.
  • Renaming internal configuration keys without a separate migration justification.

This issue is coordination-only; do not implement it as one PR.

Metadata

Metadata

Assignees

No one assigned

    Labels

    devuxhuman-in-loopHuman involvement required; use on-hold separately when implementation cannot proceedkeypathScope: KeyPath product, app, installer, or repository workneeds-decisionRequires a product or scope decision before implementationpost-releasePost-public-1.0 work; not required before stable 1.0 releasetracking-onlyOpen coordination or roadmap issue; do not implement as one PR

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions