From b31151db3dae375721ea4e65cc7b245fac4c4d8b Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 10:01:09 -0500 Subject: [PATCH 1/7] add bugbot, and use wrong callout --- .cursor/rules/BUGBOT.md | 237 +++++++++++++++++++++++++++++++++++++ content/concepts/users.mdx | 2 +- 2 files changed, 238 insertions(+), 1 deletion(-) create mode 100644 .cursor/rules/BUGBOT.md diff --git a/.cursor/rules/BUGBOT.md b/.cursor/rules/BUGBOT.md new file mode 100644 index 000000000..f1952ecad --- /dev/null +++ b/.cursor/rules/BUGBOT.md @@ -0,0 +1,237 @@ +--- +description: Rules for validating Callout component usage and type selection +globs: + - content/**/*.mdx +alwaysApply: true +--- + +## Callout type validation + +When reviewing documentation, validate that Callout components use the appropriate type based on their content. The available types are: `info`, `warning`, `alert`, `enterprise`, `beta`, and `roadmap`. + +### Callout type definitions + +#### Info (`type="info"`) + +Use for nice-to-know information that helps users get more value out of a feature. This is for helpful tips, additional context, or supplementary information that enhances understanding. + +**Indicators:** + +- Words like: "tip", "note", "learn more", "you can also", "additionally" +- Helpful context that doesn't warn about problems +- Information about optional features or enhancements +- Links to related documentation + +**Example appropriate usage:** + +- Explaining an optional feature enhancement +- Providing additional context about how something works +- Linking to related documentation + +#### Warning (`type="warning"`) + +Use when incorrect usage may cause unintended side effects or errors. These situations usually won't break things completely but have the potential to generate non-urgent support tickets. If users don't pay attention, bad things may happen. + +**Indicators:** + +- Words like: "be careful", "note", "important", "may cause", "could result in", "potential issues" +- Mentions of incorrect usage leading to problems +- Warnings about side effects or unintended behavior +- Non-destructive but problematic outcomes +- Situations where errors can be handled by the calling app + +**Example appropriate usage:** + +- Warning about incorrect usage that may cause errors +- Noting potential side effects of a feature +- Explaining limitations that could cause issues if not understood +- API calls that can return error codes the app can handle + +#### Alert (`type="alert"`) + +Use for destructive operations where data can't be recovered, actions that can't be undone, or anywhere there's a security implication. This is for serious consequences that require immediate attention. + +**Indicators:** + +- Words like: "destructive", "cannot be undone", "permanent", "irreversible", "security", "delete", "remove permanently", "cannot recover" +- Actions that permanently delete or modify data +- Security-related warnings +- Operations that cannot be reversed +- Critical errors that cannot be handled gracefully + +**Example appropriate usage:** + +- Deleting data that cannot be recovered +- Security vulnerabilities or implications +- Permanent configuration changes +- Actions that cannot be undone + +#### Enterprise (`type="enterprise"`) + +Use for features or information specific to enterprise plans or enterprise customers. + +**Indicators:** + +- Mentions of "enterprise", "enterprise plan", "enterprise feature" +- Features restricted to enterprise accounts +- Enterprise-specific functionality + +#### Beta (`type="beta"`) + +Use for features that are in beta or experimental state. + +**Indicators:** + +- Mentions of "beta", "experimental", "preview", "early access" +- Features that may change +- New features not yet generally available + +#### Roadmap (`type="roadmap"`) + +Use for information about planned features or future roadmap items. + +**Indicators:** + +- Mentions of "coming soon", "planned", "roadmap", "future" +- Features that are not yet available +- Upcoming changes or improvements + +### Validation rules + +#### Rule 1: Check for incorrect type usage + +When reviewing a Callout, analyze the content to determine if the type matches the severity and nature of the message: + +1. **Alert used for non-destructive warnings:** + + - If a Callout uses `type="alert"` but describes non-destructive issues, errors that can be handled, or warnings about side effects, suggest changing to `type="warning"`. + - Example: "This API call may return an error code" β†’ should be `warning`, not `alert` + +2. **Warning used for destructive operations:** + + - If a Callout uses `type="warning"` but describes destructive operations, permanent deletions, or security implications, suggest changing to `type="alert"`. + - Example: "This action permanently deletes all data and cannot be undone" β†’ should be `alert`, not `warning` + +3. **Info used for warnings:** + + - If a Callout uses `type="info"` but warns about potential problems, errors, or side effects, suggest changing to `type="warning"`. + - Example: "Incorrect usage may cause errors" β†’ should be `warning`, not `info` + +4. **Warning/Alert used for helpful tips:** + - If a Callout uses `type="warning"` or `type="alert"` but only provides helpful information without warning about problems, suggest changing to `type="info"`. + - Example: "You can also use this feature to enhance your workflow" β†’ should be `info`, not `warning` + +#### Rule 2: Check for freeform callouts that should use standard types + +When a Callout uses custom `emoji` or `bgColor` props instead of a `type`, check if the content matches one of the standard types: + +1. **Freeform callout with warning content:** + + - If a Callout has custom emoji/bgColor but warns about problems, errors, or side effects, suggest using `type="warning"` or `type="alert"` instead. + - Look for warning language even if no type is specified + +2. **Freeform callout with info content:** + + - If a Callout has custom emoji/bgColor but only provides helpful information, suggest using `type="info"` instead. + +3. **Freeform callout matching standard types:** + - If the emoji or content matches a standard type (e.g., 🚧 for beta, 🏒 for enterprise), suggest using the appropriate `type` prop instead. + +### Review checklist + +When reviewing Callout usage, check: + +1. βœ… Does the type match the severity of the message? +2. βœ… Is this a destructive operation that should be `alert`? +3. βœ… Is this a warning about potential issues that should be `warning`? +4. βœ… Is this just helpful information that should be `info`? +5. βœ… Are freeform callouts (custom emoji/bgColor) using a standard type when appropriate? +6. βœ… Does the content match the type's definition? + +### Examples of incorrect usage + +❌ **Incorrect:** Using `type="alert"` for a non-destructive warning + +```mdx + +``` + +βœ… **Correct:** Should use `type="warning"` + +```mdx + +``` + +❌ **Incorrect:** Using `type="warning"` for a destructive operation + +```mdx + +``` + +βœ… **Correct:** Should use `type="alert"` + +```mdx + +``` + +❌ **Incorrect:** Using `type="info"` for a warning + +```mdx + +``` + +βœ… **Correct:** Should use `type="warning"` + +```mdx + +``` + +❌ **Incorrect:** Using freeform callout when standard type fits + +```mdx + +``` + +βœ… **Correct:** Should use `type="warning"` + +```mdx + +``` + +### When to flag + +Flag a Callout for review when: + +1. The type doesn't match the severity indicated by the content +2. A freeform callout (custom emoji/bgColor) could use a standard type +3. Destructive/security content uses `warning` instead of `alert` +4. Non-destructive warnings use `alert` instead of `warning` +5. Helpful tips use `warning` or `alert` instead of `info` + +### Suggested review message format + +When flagging incorrect Callout usage, use this format: + +> **Callout type mismatch:** This Callout uses `type="[current]"` but the content suggests it should be `type="[suggested]"` because [reason]. Consider updating the type to better match the severity and nature of the message. diff --git a/content/concepts/users.mdx b/content/concepts/users.mdx index e1fac7b87..eba412321 100644 --- a/content/concepts/users.mdx +++ b/content/concepts/users.mdx @@ -20,7 +20,7 @@ User data must be synchronized to Knock to send the user a notification or to re The identifier for a user is important as it's the unique key that we will use to merge users and determine recipients for a notification. Generally, the best practice here is to use your internal identifier for your users as the `id`. From 6752e099f87f9df4aae46ed2b8678bd45a087963 Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 10:20:36 -0500 Subject: [PATCH 2/7] update rule --- .cursor/rules/BUGBOT.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/.cursor/rules/BUGBOT.md b/.cursor/rules/BUGBOT.md index f1952ecad..37d095fb4 100644 --- a/.cursor/rules/BUGBOT.md +++ b/.cursor/rules/BUGBOT.md @@ -17,11 +17,13 @@ Use for nice-to-know information that helps users get more value out of a featur **Indicators:** -- Words like: "tip", "note", "learn more", "you can also", "additionally" +- Words like: "tip", "learn more", "you can also", "additionally" - Helpful context that doesn't warn about problems - Information about optional features or enhancements - Links to related documentation +**Note:** Keywords are hints, not definitive rules. Focus on whether the content provides helpful information without warning about problems. For example, "Note: This feature also supports X" would be `info` because it's helpful context, not a warning. + **Example appropriate usage:** - Explaining an optional feature enhancement @@ -34,12 +36,14 @@ Use when incorrect usage may cause unintended side effects or errors. These situ **Indicators:** -- Words like: "be careful", "note", "important", "may cause", "could result in", "potential issues" +- Words like: "be careful", "important", "may cause", "could result in", "potential issues" - Mentions of incorrect usage leading to problems - Warnings about side effects or unintended behavior - Non-destructive but problematic outcomes - Situations where errors can be handled by the calling app +**Note:** Keywords are hints, not definitive rules. Focus on whether the content warns about potential problems or side effects. For example, "Note: Incorrect usage may cause errors" would be `warning` because it warns about problems, even though it uses the word "note". + **Example appropriate usage:** - Warning about incorrect usage that may cause errors @@ -98,6 +102,8 @@ Use for information about planned features or future roadmap items. ### Validation rules +**Important:** When validating Callout types, focus on the semantic meaning and intent of the content, not just keyword matching. The same word can appear in different contextsβ€”what matters is whether the message describes problems (warning/alert) or helpful information (info). + #### Rule 1: Check for incorrect type usage When reviewing a Callout, analyze the content to determine if the type matches the severity and nature of the message: From 8666694203631bcfd8d375e5f939cf098ce8ad6d Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 10:23:43 -0500 Subject: [PATCH 3/7] update alert rule --- .cursor/rules/BUGBOT.md | 2 +- content/concepts/users.mdx | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.cursor/rules/BUGBOT.md b/.cursor/rules/BUGBOT.md index 37d095fb4..0407844fd 100644 --- a/.cursor/rules/BUGBOT.md +++ b/.cursor/rules/BUGBOT.md @@ -53,7 +53,7 @@ Use when incorrect usage may cause unintended side effects or errors. These situ #### Alert (`type="alert"`) -Use for destructive operations where data can't be recovered, actions that can't be undone, or anywhere there's a security implication. This is for serious consequences that require immediate attention. +Use for destructive operations where data can't be recovered, actions that can't be undone, or anywhere there's a security implication. This is for serious consequences that require immediate attention. Alerts should only be used sparingly, so when in doubt about the severity of an outcome, you can suggest a `warning` type. **Indicators:** diff --git a/content/concepts/users.mdx b/content/concepts/users.mdx index eba412321..e1fac7b87 100644 --- a/content/concepts/users.mdx +++ b/content/concepts/users.mdx @@ -20,7 +20,7 @@ User data must be synchronized to Knock to send the user a notification or to re The identifier for a user is important as it's the unique key that we will use to merge users and determine recipients for a notification. Generally, the best practice here is to use your internal identifier for your users as the `id`. From 64ca5c8494f02528afe8020ec6a4d0804832f043 Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 10:36:56 -0500 Subject: [PATCH 4/7] try bad callout --- content/concepts/users.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/concepts/users.mdx b/content/concepts/users.mdx index e1fac7b87..15961b605 100644 --- a/content/concepts/users.mdx +++ b/content/concepts/users.mdx @@ -33,6 +33,17 @@ The identifier for a user is important as it's the unique key that we will use t } /> + + If you delete a user, their data will be unrecoverable. Proceed with + caution. + + } +/> + ### Required attributes The following attributes are required for each user you identify with Knock. From 2f4b2cf1128308877a932fc3d25b93f762d72a9a Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 10:52:24 -0500 Subject: [PATCH 5/7] add ent callout --- content/concepts/users.mdx | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/content/concepts/users.mdx b/content/concepts/users.mdx index 15961b605..ee032ad1a 100644 --- a/content/concepts/users.mdx +++ b/content/concepts/users.mdx @@ -44,6 +44,17 @@ The identifier for a user is important as it's the unique key that we will use t } /> + + Here's a cool new enterprise feature related to user relationships with + accounts or tenants. + + } +/> + ### Required attributes The following attributes are required for each user you identify with Knock. From 8b43e4c169c0f23a600eddb7ded6dce8edaf57f3 Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 10:57:30 -0500 Subject: [PATCH 6/7] remove bad callouts --- content/concepts/users.mdx | 22 ---------------------- 1 file changed, 22 deletions(-) diff --git a/content/concepts/users.mdx b/content/concepts/users.mdx index ee032ad1a..e1fac7b87 100644 --- a/content/concepts/users.mdx +++ b/content/concepts/users.mdx @@ -33,28 +33,6 @@ The identifier for a user is important as it's the unique key that we will use t } /> - - If you delete a user, their data will be unrecoverable. Proceed with - caution. - - } -/> - - - Here's a cool new enterprise feature related to user relationships with - accounts or tenants. - - } -/> - ### Required attributes The following attributes are required for each user you identify with Knock. From 173d4cf2a90cfe9489813a623c15f4f4864500f0 Mon Sep 17 00:00:00 2001 From: Jeff Everhart Date: Thu, 6 Nov 2025 11:58:24 -0500 Subject: [PATCH 7/7] add more language examples --- .cursor/rules/BUGBOT.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.cursor/rules/BUGBOT.md b/.cursor/rules/BUGBOT.md index 0407844fd..a245d56c1 100644 --- a/.cursor/rules/BUGBOT.md +++ b/.cursor/rules/BUGBOT.md @@ -17,7 +17,7 @@ Use for nice-to-know information that helps users get more value out of a featur **Indicators:** -- Words like: "tip", "learn more", "you can also", "additionally" +- Words like: "tip", "learn more", "you can also", "additionally", "might want to", "could" - Helpful context that doesn't warn about problems - Information about optional features or enhancements - Links to related documentation @@ -36,7 +36,7 @@ Use when incorrect usage may cause unintended side effects or errors. These situ **Indicators:** -- Words like: "be careful", "important", "may cause", "could result in", "potential issues" +- Words like: "be careful", "important", "may cause", "could result in", "potential issues", "breaking changes", "not supported" - Mentions of incorrect usage leading to problems - Warnings about side effects or unintended behavior - Non-destructive but problematic outcomes