chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,8 @@
|
||||
{
|
||||
"name": "customer-support",
|
||||
"version": "1.3.0",
|
||||
"description": "Triage tickets, draft responses, escalate issues, and build your knowledge base. Research customer context and turn resolved issues into self-service content.",
|
||||
"author": {
|
||||
"name": "Anthropic"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
{
|
||||
"mcpServers": {
|
||||
"slack": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.slack.com/mcp",
|
||||
"oauth": {
|
||||
"clientId": "1601185624273.8899143856786",
|
||||
"callbackPort": 3118
|
||||
}
|
||||
},
|
||||
"intercom": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.intercom.com/mcp"
|
||||
},
|
||||
"hubspot": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.hubspot.com/anthropic"
|
||||
},
|
||||
"guru": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.api.getguru.com/mcp"
|
||||
},
|
||||
"atlassian": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.atlassian.com/v1/mcp"
|
||||
},
|
||||
"notion": {
|
||||
"type": "http",
|
||||
"url": "https://mcp.notion.com/mcp"
|
||||
},
|
||||
"google calendar": {
|
||||
"type": "http",
|
||||
"url": ""
|
||||
},
|
||||
"gmail": {
|
||||
"type": "http",
|
||||
"url": ""
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
# Connectors
|
||||
|
||||
## How tool references work
|
||||
|
||||
Plugin files use `~~category` as a placeholder for whatever tool the user connects in that category. For example, `~~support platform` might mean Intercom, Zendesk, or any other support tool with an MCP server.
|
||||
|
||||
Plugins are **tool-agnostic** — they describe workflows in terms of categories (support platform, CRM, chat, etc.) rather than specific products. The `.mcp.json` pre-configures specific MCP servers, but any MCP server in that category works.
|
||||
|
||||
## Connectors for this plugin
|
||||
|
||||
| Category | Placeholder | Included servers | Other options |
|
||||
|----------|-------------|-----------------|---------------|
|
||||
| Chat | `~~chat` | Slack | Microsoft Teams |
|
||||
| Email | `~~email` | Microsoft 365 | — |
|
||||
| Cloud storage | `~~cloud storage` | Microsoft 365 | — |
|
||||
| Support platform | `~~support platform` | Intercom | Zendesk, Freshdesk, HubSpot Service Hub |
|
||||
| CRM | `~~CRM` | HubSpot | Salesforce, Pipedrive |
|
||||
| Knowledge base | `~~knowledge base` | Guru, Notion | Confluence, Help Scout |
|
||||
| Project tracker | `~~project tracker` | Atlassian (Jira/Confluence) | Linear, Asana |
|
||||
@@ -0,0 +1,202 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -0,0 +1,139 @@
|
||||
# Customer Support Plugin
|
||||
|
||||
A customer support plugin primarily designed for [Cowork](https://claude.com/product/cowork), Anthropic's agentic desktop application — though it also works in Claude Code. Provides ticket triage, escalation management, response drafting, customer research, and knowledge base authoring for support teams.
|
||||
|
||||
## Installation
|
||||
|
||||
```
|
||||
claude plugins add knowledge-work-plugins/customer-support
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
This plugin turns Claude into a customer support co-pilot. It helps you:
|
||||
|
||||
- **Triage incoming tickets** with structured categorization, priority assessment, and routing recommendations
|
||||
- **Research customer questions** by synthesizing information from multiple sources with confidence scoring
|
||||
- **Draft professional responses** tailored to the situation, urgency, and communication channel
|
||||
- **Package escalations** with full context, reproduction steps, and business impact for engineering or product
|
||||
- **Write KB articles** from resolved issues to reduce future ticket volume
|
||||
|
||||
## Commands
|
||||
|
||||
| Command | Description |
|
||||
|---|---|
|
||||
| `/triage` | Categorize, prioritize, and route a support ticket or customer issue |
|
||||
| `/research` | Multi-source research on a customer question or topic |
|
||||
| `/draft-response` | Draft a customer-facing response for any situation |
|
||||
| `/escalate` | Package an escalation for engineering, product, or leadership |
|
||||
| `/kb-article` | Draft a knowledge base article from a resolved issue |
|
||||
|
||||
## Skills
|
||||
|
||||
| Skill | Description |
|
||||
|---|---|
|
||||
| `ticket-triage` | Category taxonomy, priority framework (P1-P4), routing rules, duplicate detection |
|
||||
| `customer-research` | Multi-source research methodology, source prioritization, answer synthesis |
|
||||
| `response-drafting` | Communication best practices, tone guidelines, templates for common scenarios |
|
||||
| `escalation` | Escalation tiers, structured escalation format, impact assessment, follow-up cadence |
|
||||
| `knowledge-management` | Article structure standards, writing for searchability, review cadence, maintenance |
|
||||
|
||||
## Data Sources
|
||||
|
||||
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](CONNECTORS.md).
|
||||
|
||||
Connect your support platform, knowledge base, and communication tools for the best experience. Without them, provide customer context manually.
|
||||
|
||||
**Included MCP connections:**
|
||||
- Chat (Slack) for internal discussions and customer channel context
|
||||
- Support platform (Intercom) for ticket history and customer conversations
|
||||
- CRM (HubSpot) for account details and contact information
|
||||
- Knowledge base (Guru, Notion) for internal documentation and runbooks
|
||||
- Project tracker (Atlassian) for bug reports and feature requests
|
||||
- Email and cloud storage (Microsoft 365) for customer correspondence
|
||||
|
||||
**Additional options:**
|
||||
- See [CONNECTORS.md](CONNECTORS.md) for alternative tools in each category
|
||||
|
||||
## Example Workflows
|
||||
|
||||
### Triaging an Incoming Ticket
|
||||
|
||||
```
|
||||
You: /triage Customer says their dashboard has been showing a blank
|
||||
page since this morning — they're on the Enterprise plan
|
||||
|
||||
Claude: Analyzing the issue...
|
||||
|
||||
## Triage: Dashboard blank page — Enterprise customer
|
||||
|
||||
**Category:** Bug
|
||||
**Priority:** P2 — High (core feature broken, enterprise customer)
|
||||
**Product area:** Dashboard / Frontend
|
||||
|
||||
### Routing Recommendation
|
||||
Route to: Tier 2 Support (investigate browser/account specifics,
|
||||
then escalate to Engineering if reproducible)
|
||||
|
||||
### Suggested Initial Response
|
||||
[Draft acknowledging the issue, asking clarifying questions
|
||||
about browser and any recent changes, offering status page link]
|
||||
```
|
||||
|
||||
### Researching a Customer Question
|
||||
|
||||
```
|
||||
You: /research Does our platform support SSO with Okta?
|
||||
|
||||
Claude: Let me check across available sources...
|
||||
|
||||
[Searches docs, knowledge base, previous conversations,
|
||||
and web sources — synthesizes answer with confidence
|
||||
level and source attribution]
|
||||
```
|
||||
|
||||
### Packaging an Escalation
|
||||
|
||||
```
|
||||
You: /escalate API returning 500 errors intermittently — 3
|
||||
Enterprise customers reported this week
|
||||
|
||||
Claude: I'll gather context and build the escalation brief...
|
||||
|
||||
[Pulls ticket history, identifies affected accounts,
|
||||
structures reproduction steps, assesses business impact,
|
||||
and generates a structured escalation for engineering]
|
||||
```
|
||||
|
||||
### Drafting a Response
|
||||
|
||||
```
|
||||
You: /draft-response Customer escalation — their integration
|
||||
has been down for 2 days and they're frustrated
|
||||
|
||||
Claude: [Generates empathetic, professional response acknowledging
|
||||
the frustration, taking ownership, providing a clear action
|
||||
plan with timeline, and offering a call]
|
||||
```
|
||||
|
||||
### Writing a KB Article
|
||||
|
||||
```
|
||||
You: /kb-article How to configure webhook notifications —
|
||||
just resolved this for the third customer this month
|
||||
|
||||
Claude: [Generates a structured how-to article with prerequisites,
|
||||
step-by-step instructions, verification steps, and common
|
||||
issues — optimized for search]
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
The plugin works out of the box with the included MCP connections. For the richest experience, connect additional data sources through your Claude settings:
|
||||
|
||||
1. **Support platform**: Add your ticketing system for ticket history and customer context
|
||||
2. **Knowledge base**: Add your wiki for internal documentation and existing KB articles
|
||||
3. **Project tracker**: Add your issue tracker for bug reports and feature requests
|
||||
4. **CRM**: Add your CRM for account details and contact information
|
||||
|
||||
Without these connections, the plugin will ask you to provide context manually and offer frameworks and templates you can fill in with your own data.
|
||||
@@ -0,0 +1,248 @@
|
||||
---
|
||||
name: customer-escalation
|
||||
description: Package an escalation for engineering, product, or leadership with full context. Use when a bug needs engineering attention beyond normal support, multiple customers report the same issue, a customer is threatening to churn, or an issue has sat unresolved past its SLA.
|
||||
argument-hint: "<issue summary> [customer name]"
|
||||
---
|
||||
|
||||
# /customer-escalation
|
||||
|
||||
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
|
||||
|
||||
Package a support issue into a structured escalation brief for engineering, product, or leadership. Gathers context, structures reproduction steps, assesses business impact, and identifies the right escalation target.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/customer-escalation <issue description> [customer name or account]
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `/customer-escalation API returning 500 errors intermittently for Acme Corp`
|
||||
- `/customer-escalation Data export is missing rows — 3 customers reported this week`
|
||||
- `/customer-escalation SSO login loop affecting all Enterprise customers`
|
||||
- `/customer-escalation Customer threatening to churn over missing audit log feature`
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Understand the Issue
|
||||
|
||||
Parse the input and determine:
|
||||
|
||||
- **What's broken or needed**: The core technical or product issue
|
||||
- **Who's affected**: Specific customer(s), segment, or all users
|
||||
- **How long**: When did this start? How long has the customer been waiting?
|
||||
- **What's been tried**: Any troubleshooting or workarounds attempted
|
||||
- **Why escalate now**: What makes this need attention beyond normal support
|
||||
|
||||
Use the "When to Escalate vs. Handle in Support" criteria below to confirm this warrants escalation.
|
||||
|
||||
### 2. Gather Context
|
||||
|
||||
Pull together relevant information from available sources:
|
||||
|
||||
- **~~support platform**: Related tickets, timeline of communications, previous troubleshooting
|
||||
- **~~CRM** (if connected): Account details, key contacts, previous escalations
|
||||
- **~~chat**: Internal discussions about this issue, similar reports from other customers
|
||||
- **~~project tracker** (if connected): Related bug reports or feature requests, engineering status
|
||||
- **~~knowledge base**: Known issues or workarounds, relevant documentation
|
||||
|
||||
### 3. Assess Business Impact
|
||||
|
||||
Using the impact dimensions below, quantify:
|
||||
|
||||
- **Breadth**: How many customers/users affected? Growing?
|
||||
- **Depth**: Blocked vs. inconvenienced?
|
||||
- **Duration**: How long has this been going on?
|
||||
- **Revenue**: ARR at risk? Pending deals affected?
|
||||
- **Time pressure**: Hard deadline?
|
||||
|
||||
### 4. Determine Escalation Target
|
||||
|
||||
Using the escalation tiers below, identify the right target: L2 Support, Engineering, Product, Security, or Leadership.
|
||||
|
||||
### 5. Structure Reproduction Steps (for bugs)
|
||||
|
||||
If the issue is a bug, follow the reproduction step best practices below to document clear repro steps with environment details and evidence.
|
||||
|
||||
### 6. Generate Escalation Brief
|
||||
|
||||
```
|
||||
## ESCALATION: [One-line summary]
|
||||
|
||||
**Severity:** [Critical / High / Medium]
|
||||
**Target team:** [Engineering / Product / Security / Leadership]
|
||||
**Reported by:** [Your name/team]
|
||||
**Date:** [Today's date]
|
||||
|
||||
### Impact
|
||||
- **Customers affected:** [Who and how many]
|
||||
- **Workflow impact:** [What they can't do]
|
||||
- **Revenue at risk:** [If applicable]
|
||||
- **Time in queue:** [How long this has been an issue]
|
||||
|
||||
### Issue Description
|
||||
[Clear, concise description of the problem — 3-5 sentences]
|
||||
|
||||
### What's Been Tried
|
||||
1. [Troubleshooting step and result]
|
||||
2. [Troubleshooting step and result]
|
||||
3. [Troubleshooting step and result]
|
||||
|
||||
### Reproduction Steps
|
||||
[If applicable — follow the format below]
|
||||
1. [Step]
|
||||
2. [Step]
|
||||
3. [Step]
|
||||
Expected: [X]
|
||||
Actual: [Y]
|
||||
Environment: [Details]
|
||||
|
||||
### Customer Communication
|
||||
- **Last update to customer:** [Date and what was communicated]
|
||||
- **Customer expectation:** [What they're expecting and by when]
|
||||
- **Escalation risk:** [Will they escalate further if not resolved by X?]
|
||||
|
||||
### What's Needed
|
||||
- [Specific ask — "investigate root cause", "prioritize fix",
|
||||
"make product decision on X", "approve exception for Y"]
|
||||
- **Deadline:** [When this needs resolution or an update]
|
||||
|
||||
### Supporting Context
|
||||
- [Related tickets or links]
|
||||
- [Internal discussion threads]
|
||||
- [Documentation or logs]
|
||||
```
|
||||
|
||||
### 7. Offer Next Steps
|
||||
|
||||
After generating the escalation:
|
||||
- "Want me to post this in a ~~chat channel for the target team?"
|
||||
- "Should I update the customer with an interim response?"
|
||||
- "Want me to set a follow-up reminder to check on this?"
|
||||
- "Should I draft a customer-facing update with the current status?"
|
||||
|
||||
---
|
||||
|
||||
## When to Escalate vs. Handle in Support
|
||||
|
||||
### Handle in Support When:
|
||||
- The issue has a documented solution or known workaround
|
||||
- It's a configuration or setup issue you can resolve
|
||||
- The customer needs guidance or training, not a fix
|
||||
- The issue is a known limitation with a documented alternative
|
||||
- Previous similar tickets were resolved at the support level
|
||||
|
||||
### Escalate When:
|
||||
- **Technical**: Bug confirmed and needs a code fix, infrastructure investigation needed, data corruption or loss
|
||||
- **Complexity**: Issue is beyond support's ability to diagnose, requires access support doesn't have, involves custom implementation
|
||||
- **Impact**: Multiple customers affected, production system down, data integrity at risk, security concern
|
||||
- **Business**: High-value customer at risk, SLA breach imminent or occurred, customer requesting executive involvement
|
||||
- **Time**: Issue has been open beyond SLA, customer has been waiting unreasonably long, normal support channels aren't progressing
|
||||
- **Pattern**: Same issue reported by 3+ customers, recurring issue that was supposedly fixed, increasing severity over time
|
||||
|
||||
## Escalation Tiers
|
||||
|
||||
### L1 → L2 (Support Escalation)
|
||||
**From:** Frontline support
|
||||
**To:** Senior support / technical support specialists
|
||||
**When:** Issue requires deeper investigation, specialized product knowledge, or advanced troubleshooting
|
||||
**What to include:** Ticket summary, steps already tried, customer context
|
||||
|
||||
### L2 → Engineering
|
||||
**From:** Senior support
|
||||
**To:** Engineering team (relevant product area)
|
||||
**When:** Confirmed bug, infrastructure issue, needs code change, requires system-level investigation
|
||||
**What to include:** Full reproduction steps, environment details, logs or error messages, business impact, customer timeline
|
||||
|
||||
### L2 → Product
|
||||
**From:** Senior support
|
||||
**To:** Product management
|
||||
**When:** Feature gap causing customer pain, design decision needed, workflow doesn't match customer expectations, competing customer needs require prioritization
|
||||
**What to include:** Customer use case, business impact, frequency of request, competitive pressure (if known)
|
||||
|
||||
### Any → Security
|
||||
**From:** Any support tier
|
||||
**To:** Security team
|
||||
**When:** Potential data exposure, unauthorized access, vulnerability report, compliance concern
|
||||
**What to include:** What was observed, who/what is potentially affected, immediate containment steps taken, urgency assessment
|
||||
**Note:** Security escalations bypass normal tier progression — escalate immediately regardless of your level
|
||||
|
||||
### Any → Leadership
|
||||
**From:** Any tier (usually L2 or manager)
|
||||
**To:** Support leadership, executive team
|
||||
**When:** High-revenue customer threatening churn, SLA breach on critical account, cross-functional decision needed, exception to policy required, PR or legal risk
|
||||
**What to include:** Full business context, revenue at risk, what's been tried, specific decision or action needed, deadline
|
||||
|
||||
## Business Impact Assessment
|
||||
|
||||
When escalating, quantify impact where possible:
|
||||
|
||||
### Impact Dimensions
|
||||
|
||||
| Dimension | Questions to Answer |
|
||||
|-----------|-------------------|
|
||||
| **Breadth** | How many customers/users are affected? Is it growing? |
|
||||
| **Depth** | How severely are they impacted? Blocked vs. inconvenienced? |
|
||||
| **Duration** | How long has this been going on? How long until it's critical? |
|
||||
| **Revenue** | What's the ARR at risk? Are there pending deals affected? |
|
||||
| **Reputation** | Could this become public? Is it a reference customer? |
|
||||
| **Contractual** | Are SLAs being breached? Are there contractual obligations? |
|
||||
|
||||
### Severity Shorthand
|
||||
|
||||
- **Critical**: Production down, data at risk, security breach, or multiple high-value customers affected. Needs immediate attention.
|
||||
- **High**: Major functionality broken, key customer blocked, SLA at risk. Needs same-day attention.
|
||||
- **Medium**: Significant issue with workaround, important but not urgent business impact. Needs attention this week.
|
||||
|
||||
## Writing Reproduction Steps
|
||||
|
||||
Good reproduction steps are the single most valuable thing in a bug escalation. Follow these practices:
|
||||
|
||||
1. **Start from a clean state**: Describe the starting point (account type, configuration, permissions)
|
||||
2. **Be specific**: "Click the Export button in the top-right of the Dashboard page" not "try to export"
|
||||
3. **Include exact values**: Use specific inputs, dates, IDs — not "enter some data"
|
||||
4. **Note the environment**: Browser, OS, account type, feature flags, plan level
|
||||
5. **Capture the frequency**: Always reproducible? Intermittent? Only under certain conditions?
|
||||
6. **Include evidence**: Screenshots, error messages (exact text), network logs, console output
|
||||
7. **Note what you've ruled out**: "Tested in Chrome and Firefox — same behavior" "Not account-specific — reproduced on test account"
|
||||
|
||||
## Follow-up Cadence After Escalation
|
||||
|
||||
Don't escalate and forget. Maintain ownership of the customer relationship.
|
||||
|
||||
| Severity | Internal Follow-up | Customer Update |
|
||||
|----------|-------------------|-----------------|
|
||||
| **Critical** | Every 2 hours | Every 2-4 hours (or per SLA) |
|
||||
| **High** | Every 4 hours | Every 4-8 hours |
|
||||
| **Medium** | Daily | Every 1-2 business days |
|
||||
|
||||
### Follow-up Actions
|
||||
- Check with the receiving team for progress
|
||||
- Update the customer even if there's no new information ("We're still investigating — here's what we know so far")
|
||||
- Adjust severity if the situation changes (better or worse)
|
||||
- Document all updates in the ticket for audit trail
|
||||
- Close the loop when resolved: confirm with customer, update internal tracking, capture learnings
|
||||
|
||||
## De-escalation
|
||||
|
||||
Not every escalation stays escalated. De-escalate when:
|
||||
- Root cause is found and it's a support-resolvable issue
|
||||
- A workaround is found that unblocks the customer
|
||||
- The issue resolves itself (but still document root cause)
|
||||
- New information changes the severity assessment
|
||||
|
||||
When de-escalating:
|
||||
- Notify the team you escalated to
|
||||
- Update the ticket with the resolution
|
||||
- Inform the customer of the resolution
|
||||
- Document what was learned for future reference
|
||||
|
||||
## Escalation Best Practices
|
||||
|
||||
1. Always quantify impact — vague escalations get deprioritized
|
||||
2. Include reproduction steps for bugs — this is the #1 thing engineering needs
|
||||
3. Be clear about what you need — "investigate" vs. "fix" vs. "decide" are different asks
|
||||
4. Set and communicate a deadline — urgency without a deadline is ambiguous
|
||||
5. Maintain ownership of the customer relationship even after escalating the technical issue
|
||||
6. Follow up proactively — don't wait for the receiving team to come to you
|
||||
7. Document everything — the escalation trail is valuable for pattern detection and process improvement
|
||||
@@ -0,0 +1,252 @@
|
||||
---
|
||||
name: customer-research
|
||||
description: Multi-source research on a customer question or topic with source attribution. Use when a customer asks something you need to look up, investigating whether a bug has been reported before, checking what was previously told to a specific account, or gathering background before drafting a response.
|
||||
argument-hint: "<question or topic>"
|
||||
---
|
||||
|
||||
# /customer-research
|
||||
|
||||
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
|
||||
|
||||
Multi-source research on a customer question, product topic, or account-related inquiry. Synthesizes findings from all available sources with clear attribution and confidence scoring.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/customer-research <question or topic>
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Parse the Research Request
|
||||
|
||||
Identify what type of research is needed:
|
||||
- **Customer question**: Something a customer has asked that needs an answer (e.g., "Does our product support SSO with Okta?")
|
||||
- **Issue investigation**: Background on a reported problem (e.g., "Has this bug been reported before? What's the known workaround?")
|
||||
- **Account context**: History with a specific customer (e.g., "What did we tell Acme Corp last time they asked about this?")
|
||||
- **Topic research**: General topic relevant to support work (e.g., "Best practices for webhook retry logic")
|
||||
|
||||
Before searching, clarify what you're actually trying to find:
|
||||
- Is this a factual question with a definitive answer?
|
||||
- Is this a contextual question requiring multiple perspectives?
|
||||
- Is this an exploratory question where the scope is still being defined?
|
||||
- Who is the audience for the answer (internal team, customer, leadership)?
|
||||
|
||||
### 2. Search Available Sources
|
||||
|
||||
Search systematically through the source tiers below, adapting to what is connected. Don't stop at the first result — cross-reference across sources.
|
||||
|
||||
**Tier 1 — Official Internal Sources (highest confidence):**
|
||||
- ~~knowledge base (if connected): product docs, runbooks, FAQs, policy documents
|
||||
- ~~cloud storage: internal documents, specs, guides, past research
|
||||
- Product roadmap (internal-facing): feature timelines, priorities
|
||||
|
||||
**Tier 2 — Organizational Context:**
|
||||
- ~~CRM notes: account notes, activity history, previous answers, opportunity details
|
||||
- ~~support platform (if connected): previous resolutions, known issues, workarounds
|
||||
- Meeting notes: previous discussions, decisions, commitments
|
||||
|
||||
**Tier 3 — Team Communications:**
|
||||
- ~~chat: search for the topic in relevant channels; check if teammates have discussed or answered this before
|
||||
- ~~email: search for previous correspondence on this topic
|
||||
- Calendar notes: meeting agendas and post-meeting notes
|
||||
|
||||
**Tier 4 — External Sources:**
|
||||
- Web search: official documentation, blog posts, community forums
|
||||
- Public knowledge bases, help centers, release notes
|
||||
- Third-party documentation: integration partners, complementary tools
|
||||
|
||||
**Tier 5 — Inferred or Analogical (use when direct sources don't yield answers):**
|
||||
- Similar situations: how similar questions were handled before
|
||||
- Analogous customers: what worked for comparable accounts
|
||||
- General best practices: industry standards and norms
|
||||
|
||||
### 3. Synthesize Findings
|
||||
|
||||
Compile results into a structured research brief:
|
||||
|
||||
```
|
||||
## Research: [Question/Topic]
|
||||
|
||||
### Answer
|
||||
[Clear, direct answer to the question — lead with the bottom line]
|
||||
|
||||
**Confidence:** [High / Medium / Low]
|
||||
[Explain what drives the confidence level]
|
||||
|
||||
### Key Findings
|
||||
|
||||
**From [Source 1]:**
|
||||
- [Finding with specific detail]
|
||||
- [Finding with specific detail]
|
||||
|
||||
**From [Source 2]:**
|
||||
- [Finding with specific detail]
|
||||
|
||||
### Context & Nuance
|
||||
[Any caveats, edge cases, or additional context that matters]
|
||||
|
||||
### Sources
|
||||
1. [Source name/link] — [what it contributed]
|
||||
2. [Source name/link] — [what it contributed]
|
||||
3. [Source name/link] — [what it contributed]
|
||||
|
||||
### Gaps & Unknowns
|
||||
- [What couldn't be confirmed]
|
||||
- [What might need verification from a subject matter expert]
|
||||
|
||||
### Recommended Next Steps
|
||||
- [Action if the answer needs to go to a customer]
|
||||
- [Action if further research is needed]
|
||||
- [Who to consult for verification if needed]
|
||||
```
|
||||
|
||||
### 4. Handle Insufficient Sources
|
||||
|
||||
If no connected sources yield results:
|
||||
|
||||
- Perform web research on the topic
|
||||
- Ask the user for internal context:
|
||||
- "I couldn't find this in connected sources. Do you have internal docs or knowledge base articles about this?"
|
||||
- "Has your team discussed this topic before? Any ~~chat channels I should check?"
|
||||
- "Is there a subject matter expert who would know the answer?"
|
||||
- Be transparent about limitations:
|
||||
- "This answer is based on web research only — please verify against your internal documentation before sharing with the customer."
|
||||
- "I found a possible answer but couldn't confirm it from an authoritative internal source."
|
||||
|
||||
### 5. Customer-Facing Considerations
|
||||
|
||||
If the research is to answer a customer question:
|
||||
|
||||
- Flag if the answer involves product roadmap, pricing, legal, or security topics that may need review
|
||||
- Note if the answer differs from what may have been communicated previously
|
||||
- Suggest appropriate caveats for the customer-facing response
|
||||
- Offer to draft the customer response: "Want me to draft a response to the customer based on these findings?"
|
||||
|
||||
### 6. Knowledge Capture
|
||||
|
||||
After research is complete, suggest capturing the knowledge:
|
||||
|
||||
- "Should I save these findings to your knowledge base for future reference?"
|
||||
- "Want me to create a FAQ entry based on this research?"
|
||||
- "This might be worth documenting — should I draft a runbook entry?"
|
||||
|
||||
This helps build institutional knowledge and reduces duplicate research effort across the team.
|
||||
|
||||
---
|
||||
|
||||
## Source Prioritization and Confidence
|
||||
|
||||
### Confidence by Source Tier
|
||||
|
||||
| Tier | Source Type | Confidence | Notes |
|
||||
|------|-------------|------------|-------|
|
||||
| 1 | Official internal docs, KB, policies | **High** | Trust unless clearly outdated — check dates |
|
||||
| 2 | CRM, support tickets, meeting notes | **Medium-High** | May be subjective or incomplete |
|
||||
| 3 | Chat, email, calendar notes | **Medium** | Informal, may be out of context or speculative |
|
||||
| 4 | Web, forums, third-party docs | **Low-Medium** | May not reflect your specific situation |
|
||||
| 5 | Inference, analogies, best practices | **Low** | Clearly flag as inference, not fact |
|
||||
|
||||
### Confidence Levels
|
||||
|
||||
Always assign and communicate a confidence level:
|
||||
|
||||
**High Confidence:**
|
||||
- Answer confirmed by official documentation or authoritative source
|
||||
- Multiple sources corroborate the same answer
|
||||
- Information is current (verified within a reasonable timeframe)
|
||||
- "I'm confident this is accurate based on [source]."
|
||||
|
||||
**Medium Confidence:**
|
||||
- Answer found in informal sources (chat, email) but not official docs
|
||||
- Single source without corroboration
|
||||
- Information may be slightly outdated but likely still valid
|
||||
- "Based on [source], this appears to be the case, but I'd recommend confirming with [team/person]."
|
||||
|
||||
**Low Confidence:**
|
||||
- Answer is inferred from related information
|
||||
- Sources are outdated or potentially unreliable
|
||||
- Contradictory information found across sources
|
||||
- "I wasn't able to find a definitive answer. Based on [context], my best assessment is [answer], but this should be verified before sharing with the customer."
|
||||
|
||||
**Unable to Determine:**
|
||||
- No relevant information found in any source
|
||||
- Question requires specialized knowledge not available in sources
|
||||
- "I couldn't find information about this. I recommend reaching out to [suggested expert/team] for a definitive answer."
|
||||
|
||||
### Handling Contradictions
|
||||
|
||||
When sources disagree:
|
||||
1. Note the contradiction explicitly
|
||||
2. Identify which source is more authoritative or more recent
|
||||
3. Present both perspectives with context
|
||||
4. Recommend how to resolve the discrepancy
|
||||
5. If going to a customer: use the most conservative/cautious answer until resolved
|
||||
|
||||
## When to Escalate vs. Answer Directly
|
||||
|
||||
### Answer Directly When:
|
||||
- Official documentation clearly addresses the question
|
||||
- Multiple reliable sources corroborate the answer
|
||||
- The question is factual and non-sensitive
|
||||
- The answer doesn't involve commitments, timelines, or pricing
|
||||
- You've answered similar questions before with confirmed accuracy
|
||||
|
||||
### Escalate or Verify When:
|
||||
- The answer involves product roadmap commitments or timelines
|
||||
- Pricing, legal terms, or contract-specific questions
|
||||
- Security, compliance, or data handling questions
|
||||
- The answer could set a precedent or create expectations
|
||||
- You found contradictory information in sources
|
||||
- The question involves a specific customer's custom configuration
|
||||
- The answer requires specialized expertise you don't have
|
||||
- The customer is at risk and the wrong answer could exacerbate the situation
|
||||
|
||||
### Escalation Path:
|
||||
1. **Subject matter expert**: For technical or domain-specific questions
|
||||
2. **Product team**: For roadmap, feature, or capability questions
|
||||
3. **Legal/compliance**: For terms, privacy, security, or regulatory questions
|
||||
4. **Billing/finance**: For pricing, invoice, or payment-related questions
|
||||
5. **Engineering**: For custom configurations, bugs, or technical root causes
|
||||
6. **Leadership**: For strategic decisions, exceptions, or high-stakes situations
|
||||
|
||||
## Research Documentation for Team Knowledge Base
|
||||
|
||||
After completing research, capture the knowledge for future use.
|
||||
|
||||
### When to Document:
|
||||
- Question has come up before or likely will again
|
||||
- Research took significant effort to compile
|
||||
- Answer required synthesizing multiple sources
|
||||
- Answer corrects a common misunderstanding
|
||||
- Answer involves nuance that's easy to get wrong
|
||||
|
||||
### Documentation Format:
|
||||
```
|
||||
## [Question/Topic]
|
||||
|
||||
**Last Verified:** [date]
|
||||
**Confidence:** [level]
|
||||
|
||||
### Answer
|
||||
[Clear, direct answer]
|
||||
|
||||
### Details
|
||||
[Supporting detail, context, and nuance]
|
||||
|
||||
### Sources
|
||||
[Where this information came from]
|
||||
|
||||
### Related Questions
|
||||
[Other questions this might help answer]
|
||||
|
||||
### Review Notes
|
||||
[When to re-verify, what might change this answer]
|
||||
```
|
||||
|
||||
### Knowledge Base Hygiene:
|
||||
- Date-stamp all entries
|
||||
- Flag entries that reference specific product versions or features
|
||||
- Review and update entries quarterly
|
||||
- Archive entries that are no longer relevant
|
||||
- Tag entries for searchability (by topic, product area, customer segment)
|
||||
@@ -0,0 +1,418 @@
|
||||
---
|
||||
name: draft-response
|
||||
description: Draft a professional customer-facing response tailored to the situation and relationship. Use when answering a product question, responding to an escalation or outage, delivering bad news like a delay or won't-fix, declining a feature request, or replying to a billing issue.
|
||||
argument-hint: "<situation description>"
|
||||
---
|
||||
|
||||
# /draft-response
|
||||
|
||||
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
|
||||
|
||||
Draft a professional, customer-facing response tailored to the situation, customer relationship, and communication context.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/draft-response <context about the customer question, issue, or request>
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `/draft-response Acme Corp is asking when the new dashboard feature will ship`
|
||||
- `/draft-response Customer escalation — their integration has been down for 2 days`
|
||||
- `/draft-response Responding to a feature request we won't be building`
|
||||
- `/draft-response Customer hit a billing error and wants a resolution ASAP`
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Understand the Context
|
||||
|
||||
Parse the user's input to determine:
|
||||
|
||||
- **Customer**: Who is the communication for? Look up account context if available.
|
||||
- **Situation type**: Question, issue, escalation, announcement, negotiation, bad news, good news, follow-up
|
||||
- **Urgency**: Is this time-sensitive? How long has the customer been waiting?
|
||||
- **Channel**: Email, support ticket, chat, or other (adjust formality accordingly)
|
||||
- **Relationship stage**: New customer, established, frustrated/escalated
|
||||
- **Stakeholder level**: End user, manager, executive, technical, business
|
||||
|
||||
### 2. Research Context
|
||||
|
||||
Gather relevant background from available sources:
|
||||
|
||||
**~~email:**
|
||||
- Previous correspondence with this customer on this topic
|
||||
- Any commitments or timelines previously shared
|
||||
- Tone and style of the existing thread
|
||||
|
||||
**~~chat:**
|
||||
- Internal discussions about this customer or topic
|
||||
- Any guidance from product, engineering, or leadership
|
||||
- Similar situations and how they were handled
|
||||
|
||||
**~~CRM (if connected):**
|
||||
- Account details and plan level
|
||||
- Contact information and key stakeholders
|
||||
- Previous escalations or sensitive issues
|
||||
|
||||
**~~support platform (if connected):**
|
||||
- Related tickets and their resolution
|
||||
- Known issues or workarounds
|
||||
- SLA status and response time commitments
|
||||
|
||||
**~~knowledge base:**
|
||||
- Official documentation or help articles to reference
|
||||
- Product roadmap information (if shareable)
|
||||
- Policy or process documentation
|
||||
|
||||
### 3. Generate the Draft
|
||||
|
||||
Produce a response tailored to the situation:
|
||||
|
||||
```
|
||||
## Draft Response
|
||||
|
||||
**To:** [Customer contact name]
|
||||
**Re:** [Subject/topic]
|
||||
**Channel:** [Email / Ticket / Chat]
|
||||
**Tone:** [Empathetic / Professional / Technical / Celebratory / Candid]
|
||||
|
||||
---
|
||||
|
||||
[Draft response text]
|
||||
|
||||
---
|
||||
|
||||
### Notes for You (internal — do not send)
|
||||
- **Why this approach:** [Rationale for tone and content choices]
|
||||
- **Things to verify:** [Any facts or commitments to confirm before sending]
|
||||
- **Risk factors:** [Anything sensitive about this response]
|
||||
- **Follow-up needed:** [Actions to take after sending]
|
||||
- **Escalation note:** [If this should be reviewed by someone else first]
|
||||
```
|
||||
|
||||
### 4. Run Quality Checks
|
||||
|
||||
Before presenting the draft, verify:
|
||||
|
||||
- [ ] Tone matches the situation and relationship
|
||||
- [ ] No commitments beyond what's authorized
|
||||
- [ ] No product roadmap details that shouldn't be shared externally
|
||||
- [ ] Accurate references to previous conversations
|
||||
- [ ] Clear next steps and ownership
|
||||
- [ ] Appropriate for the stakeholder level (not too technical for executives, not too vague for engineers)
|
||||
- [ ] Length is appropriate for the channel (shorter for chat, fuller for email)
|
||||
|
||||
### 5. Offer Iterations
|
||||
|
||||
After presenting the draft:
|
||||
- "Want me to adjust the tone? (more formal, more casual, more empathetic, more direct)"
|
||||
- "Should I add or remove any specific points?"
|
||||
- "Want me to make this shorter/longer?"
|
||||
- "Should I draft a version for a different stakeholder?"
|
||||
- "Want me to draft the internal escalation note as well?"
|
||||
- "Should I prepare a follow-up message to send after [X days] if no response?"
|
||||
|
||||
---
|
||||
|
||||
## Customer Communication Best Practices
|
||||
|
||||
### Core Principles
|
||||
|
||||
1. **Lead with empathy**: Acknowledge the customer's situation before jumping to solutions
|
||||
2. **Be direct**: Get to the point — customers are busy. Bottom-line-up-front.
|
||||
3. **Be honest**: Never overpromise, never mislead, never hide bad news in jargon
|
||||
4. **Be specific**: Use concrete details, timelines, and names — avoid vague language
|
||||
5. **Own it**: Take responsibility when appropriate. "We" not "the system" or "the process"
|
||||
6. **Close the loop**: Every response should have a clear next step or call to action
|
||||
7. **Match their energy**: If they're frustrated, be empathetic first. If they're excited, be enthusiastic.
|
||||
|
||||
### Response Structure
|
||||
|
||||
For most customer communications, follow this structure:
|
||||
|
||||
```
|
||||
1. Acknowledgment / Context (1-2 sentences)
|
||||
- Acknowledge what they said, asked, or are experiencing
|
||||
- Show you understand their situation
|
||||
|
||||
2. Core Message (1-3 paragraphs)
|
||||
- Deliver the main information, answer, or update
|
||||
- Be specific and concrete
|
||||
- Include relevant details they need
|
||||
|
||||
3. Next Steps (1-3 bullets)
|
||||
- What YOU will do and by when
|
||||
- What THEY need to do (if anything)
|
||||
- When they'll hear from you next
|
||||
|
||||
4. Closing (1 sentence)
|
||||
- Warm but professional sign-off
|
||||
- Reinforce you're available if needed
|
||||
```
|
||||
|
||||
### Length Guidelines
|
||||
|
||||
- **Chat/IM**: 1-4 sentences. Get to the point immediately.
|
||||
- **Support ticket response**: 1-3 short paragraphs. Structured and scannable.
|
||||
- **Email**: 3-5 paragraphs max. Respect their inbox.
|
||||
- **Escalation response**: As long as needed to be thorough, but well-structured with headers.
|
||||
- **Executive communication**: Shorter is better. 2-3 paragraphs max. Data-driven.
|
||||
|
||||
## Tone and Style Guidelines
|
||||
|
||||
### Tone Spectrum
|
||||
|
||||
| Situation | Tone | Characteristics |
|
||||
|-----------|------|----------------|
|
||||
| Good news / wins | Celebratory | Enthusiastic, warm, congratulatory, forward-looking |
|
||||
| Routine update | Professional | Clear, concise, informative, friendly |
|
||||
| Technical response | Precise | Accurate, detailed, structured, patient |
|
||||
| Delayed delivery | Accountable | Honest, apologetic, action-oriented, specific |
|
||||
| Bad news | Candid | Direct, empathetic, solution-oriented, respectful |
|
||||
| Issue / outage | Urgent | Immediate, transparent, actionable, reassuring |
|
||||
| Escalation | Executive | Composed, ownership-taking, plan-presenting, confident |
|
||||
| Billing / account | Precise | Clear, factual, empathetic, resolution-focused |
|
||||
|
||||
### Tone Adjustments by Relationship Stage
|
||||
|
||||
**New Customer (0-3 months):**
|
||||
- More formal and professional
|
||||
- Extra context and explanation (don't assume knowledge)
|
||||
- Proactively offer help and resources
|
||||
- Build trust through reliability and responsiveness
|
||||
|
||||
**Established Customer (3+ months):**
|
||||
- Warm and collaborative
|
||||
- Can reference shared history and previous conversations
|
||||
- More direct and efficient communication
|
||||
- Show awareness of their goals and priorities
|
||||
|
||||
**Frustrated or Escalated Customer:**
|
||||
- Extra empathy and acknowledgment
|
||||
- Urgency in response times
|
||||
- Concrete action plans with specific commitments
|
||||
- Shorter feedback loops
|
||||
|
||||
### Writing Style Rules
|
||||
|
||||
**DO:**
|
||||
- Use active voice ("We'll investigate" not "This will be investigated")
|
||||
- Use "I" for personal commitments and "we" for team commitments
|
||||
- Name specific people when assigning actions ("Sarah from our engineering team will...")
|
||||
- Use the customer's terminology, not your internal jargon
|
||||
- Include specific dates and times, not relative terms ("by Friday January 24" not "in a few days")
|
||||
- Break up long responses with headers or bullet points
|
||||
|
||||
**DON'T:**
|
||||
- Use corporate jargon or buzzwords ("synergy", "leverage", "paradigm shift")
|
||||
- Deflect blame to other teams, systems, or processes
|
||||
- Use passive voice to avoid ownership ("Mistakes were made")
|
||||
- Include unnecessary caveats or hedging that undermines confidence
|
||||
- CC people unnecessarily — only include those who need to be in the conversation
|
||||
- Use exclamation marks excessively (one per email max, if any)
|
||||
|
||||
## Situation-Specific Approaches
|
||||
|
||||
**Answering a product question:**
|
||||
- Lead with the direct answer
|
||||
- Provide relevant documentation links
|
||||
- Offer to connect them with the right resource if needed
|
||||
- If you don't know the answer: say so honestly, commit to finding out, give a timeline
|
||||
|
||||
**Responding to an issue or bug:**
|
||||
- Acknowledge the impact on their work
|
||||
- State what you know about the issue and its status
|
||||
- Provide workaround if available
|
||||
- Set expectations for resolution timeline
|
||||
- Commit to updates at regular intervals
|
||||
|
||||
**Handling an escalation:**
|
||||
- Acknowledge the severity and their frustration
|
||||
- Take ownership (no deflecting or excuse-making)
|
||||
- Provide a clear action plan with timeline
|
||||
- Identify the person accountable for resolution
|
||||
- Offer a meeting or call if appropriate for the severity
|
||||
|
||||
**Delivering bad news (feature sunset, delay, can't-fix):**
|
||||
- Be direct — don't bury the news
|
||||
- Explain the reasoning honestly
|
||||
- Acknowledge the impact on them specifically
|
||||
- Offer alternatives or mitigation
|
||||
- Provide a clear path forward
|
||||
|
||||
**Sharing good news (feature launch, milestone, recognition):**
|
||||
- Lead with the positive outcome
|
||||
- Connect it to their specific goals or use case
|
||||
- Suggest next steps to capitalize on the good news
|
||||
- Express genuine enthusiasm
|
||||
|
||||
**Declining a request (feature request, discount, exception):**
|
||||
- Acknowledge the request and its reasoning
|
||||
- Be honest about the decision
|
||||
- Explain the why without being dismissive
|
||||
- Offer alternatives when possible
|
||||
- Leave the door open for future conversation
|
||||
|
||||
## Response Templates for Common Scenarios
|
||||
|
||||
### Acknowledging a Bug Report
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
Thank you for reporting this — I can see how [specific impact] would be
|
||||
frustrating for your team.
|
||||
|
||||
I've confirmed the issue and escalated it to our engineering team as a
|
||||
[priority level]. Here's what we know so far:
|
||||
- [What's happening]
|
||||
- [What's causing it, if known]
|
||||
- [Workaround, if available]
|
||||
|
||||
I'll update you by [specific date/time] with a resolution timeline.
|
||||
In the meantime, [workaround details if applicable].
|
||||
|
||||
Let me know if you have any questions or if this is impacting you in
|
||||
other ways I should know about.
|
||||
|
||||
Best,
|
||||
[Your name]
|
||||
```
|
||||
|
||||
### Acknowledging a Billing or Account Issue
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
Thank you for reaching out about this — I understand billing issues
|
||||
need prompt attention, and I want to make sure this gets resolved
|
||||
quickly.
|
||||
|
||||
I've looked into your account and here's what I'm seeing:
|
||||
- [What happened — clear factual explanation]
|
||||
- [Impact on their account — charges, access, etc.]
|
||||
|
||||
Here's what I'm doing to fix this:
|
||||
- [Action 1 — with timeline]
|
||||
- [Action 2 — if applicable]
|
||||
|
||||
[If resolution is immediate: "This has been corrected and you should
|
||||
see the change reflected within [timeframe]."]
|
||||
[If needs investigation: "I'm escalating this to our billing team
|
||||
and will have an update for you by [specific date]."]
|
||||
|
||||
I'm sorry for the inconvenience. Let me know if you have any
|
||||
questions about your account.
|
||||
|
||||
Best,
|
||||
[Your name]
|
||||
```
|
||||
|
||||
### Responding to a Feature Request You Won't Build
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
Thank you for sharing this request — I can see why [capability] would
|
||||
be valuable for [their use case].
|
||||
|
||||
I discussed this with our product team, and this isn't something we're
|
||||
planning to build in the near term. The primary reason is [honest,
|
||||
respectful explanation — e.g., it serves a narrow use case, it conflicts
|
||||
with our architecture direction, etc.].
|
||||
|
||||
That said, I want to make sure you can accomplish your goal. Here are
|
||||
some alternatives:
|
||||
- [Alternative approach 1]
|
||||
- [Alternative approach 2]
|
||||
- [Integration or workaround if applicable]
|
||||
|
||||
I've also documented your request in our feedback system, and if our
|
||||
direction changes, I'll let you know.
|
||||
|
||||
Would any of these alternatives work for your team? Happy to dig
|
||||
deeper into any of them.
|
||||
|
||||
Best,
|
||||
[Your name]
|
||||
```
|
||||
|
||||
### Outage or Incident Communication
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
I wanted to reach out directly to let you know about an issue affecting
|
||||
[service/feature] that I know your team relies on.
|
||||
|
||||
**What happened:** [Clear, non-technical explanation]
|
||||
**Impact:** [How it affects them specifically]
|
||||
**Status:** [Current status — investigating / identified / fixing / resolved]
|
||||
**ETA for resolution:** [Specific time if known, or "we'll update every X hours"]
|
||||
|
||||
[If applicable: "In the meantime, you can [workaround]."]
|
||||
|
||||
I'm personally tracking this and will update you as soon as we have a
|
||||
resolution. You can also check [status page URL] for real-time updates.
|
||||
|
||||
I'm sorry for the disruption to your team's work. We take this seriously
|
||||
and [what you're doing to prevent recurrence if known].
|
||||
|
||||
[Your name]
|
||||
```
|
||||
|
||||
### Following Up After Silence
|
||||
|
||||
```
|
||||
Hi [Name],
|
||||
|
||||
I wanted to check in — I sent over [what you sent] on [date] and
|
||||
wanted to make sure it didn't get lost in the shuffle.
|
||||
|
||||
[Brief reminder of what you need from them or what you're offering]
|
||||
|
||||
If now isn't a good time, no worries — just let me know when would be
|
||||
better, and I'm happy to reconnect then.
|
||||
|
||||
Best,
|
||||
[Your name]
|
||||
```
|
||||
|
||||
## Follow-up and Escalation Guidance
|
||||
|
||||
### Follow-up Cadence
|
||||
|
||||
| Situation | Follow-up Timing |
|
||||
|-----------|-----------------|
|
||||
| Unanswered question | 2-3 business days |
|
||||
| Open support issue | Daily until resolved for critical, 2-3 days for standard |
|
||||
| Post-meeting action items | Within 24 hours (send notes), then check at deadline |
|
||||
| General check-in | As needed for ongoing issues |
|
||||
| After delivering bad news | 1 week to check on impact and sentiment |
|
||||
|
||||
### When to Escalate
|
||||
|
||||
**Escalate to your manager when:**
|
||||
- Customer threatens to cancel or significantly downsell
|
||||
- Customer requests exception to policy you can't authorize
|
||||
- An issue has been unresolved for longer than SLA allows
|
||||
- Customer requests direct contact with leadership
|
||||
- You've made an error that needs senior involvement to resolve
|
||||
|
||||
**Escalate to product/engineering when:**
|
||||
- Bug is critical and blocking the customer's business
|
||||
- Feature gap is causing a competitive loss
|
||||
- Customer has unique technical requirements beyond standard support
|
||||
- Integration issues require engineering investigation
|
||||
|
||||
**Escalation format:**
|
||||
```
|
||||
ESCALATION: [Customer Name] — [One-line summary]
|
||||
|
||||
Urgency: [Critical / High / Medium]
|
||||
Customer impact: [What's broken for them]
|
||||
History: [Brief background — 2-3 sentences]
|
||||
What I've tried: [Actions taken so far]
|
||||
What I need: [Specific help or decision needed]
|
||||
Deadline: [When this needs to be resolved by]
|
||||
```
|
||||
@@ -0,0 +1,351 @@
|
||||
---
|
||||
name: kb-article
|
||||
description: Draft a knowledge base article from a resolved issue or common question. Use when a ticket resolution is worth documenting for self-service, the same question keeps coming up, a workaround needs to be published, or a known issue should be communicated to customers.
|
||||
argument-hint: "<resolved issue or ticket>"
|
||||
---
|
||||
|
||||
# /kb-article
|
||||
|
||||
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
|
||||
|
||||
Draft a publish-ready knowledge base article from a resolved support issue, common question, or documented workaround. Structures the content for searchability and self-service.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/kb-article <resolved issue, ticket reference, or topic description>
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `/kb-article How to configure SSO with Okta — resolved this for 3 customers last month`
|
||||
- `/kb-article Ticket #4521 — customer couldn't export data over 10k rows`
|
||||
- `/kb-article Common question: how to set up webhook notifications`
|
||||
- `/kb-article Known issue: dashboard charts not loading on Safari 16`
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Understand the Source Material
|
||||
|
||||
Parse the input to identify:
|
||||
|
||||
- **What was the problem?** The original issue, question, or error
|
||||
- **What was the solution?** The resolution, workaround, or answer
|
||||
- **Who does this affect?** User type, plan level, or configuration
|
||||
- **How common is this?** One-off or recurring issue
|
||||
- **What article type fits best?** How-to, troubleshooting, FAQ, known issue, or reference (see article types below)
|
||||
|
||||
If a ticket reference is provided, look up the full context:
|
||||
|
||||
- **~~support platform**: Pull the ticket thread, resolution, and any internal notes
|
||||
- **~~knowledge base**: Check if a similar article already exists (update vs. create new)
|
||||
- **~~project tracker**: Check if there's a related bug or feature request
|
||||
|
||||
### 2. Draft the Article
|
||||
|
||||
Using the article structure, formatting standards, and searchability best practices below:
|
||||
|
||||
- Follow the template for the chosen article type (how-to, troubleshooting, FAQ, known issue, or reference)
|
||||
- Apply the searchability best practices: customer-language title, plain-language opening sentence, exact error messages, common synonyms
|
||||
- Keep it scannable: headers, numbered steps, short paragraphs
|
||||
|
||||
### 3. Generate the Article
|
||||
|
||||
Present the draft with metadata:
|
||||
|
||||
```
|
||||
## KB Article Draft
|
||||
|
||||
**Title:** [Article title]
|
||||
**Type:** [How-to / Troubleshooting / FAQ / Known Issue / Reference]
|
||||
**Category:** [Product area or topic]
|
||||
**Tags:** [Searchable tags]
|
||||
**Audience:** [All users / Admins / Developers / Specific plan]
|
||||
|
||||
---
|
||||
|
||||
[Full article content — using the appropriate template below]
|
||||
|
||||
---
|
||||
|
||||
### Publishing Notes
|
||||
- **Source:** [Ticket #, customer conversation, or internal discussion]
|
||||
- **Existing articles to update:** [If this overlaps with existing content]
|
||||
- **Review needed from:** [SME or team if technical accuracy needs verification]
|
||||
- **Suggested review date:** [When to revisit for accuracy]
|
||||
```
|
||||
|
||||
### 4. Offer Next Steps
|
||||
|
||||
After generating the article:
|
||||
- "Want me to check if a similar article already exists in your ~~knowledge base?"
|
||||
- "Should I adjust the technical depth for a different audience?"
|
||||
- "Want me to draft a companion article (e.g., a how-to to go with this troubleshooting guide)?"
|
||||
- "Should I create an internal-only version with additional technical detail?"
|
||||
|
||||
---
|
||||
|
||||
## Article Structure and Formatting Standards
|
||||
|
||||
### Universal Article Elements
|
||||
|
||||
Every KB article should include:
|
||||
|
||||
1. **Title**: Clear, searchable, describes the outcome or problem (not internal jargon)
|
||||
2. **Overview**: 1-2 sentences explaining what this article covers and who it's for
|
||||
3. **Body**: Structured content appropriate to the article type
|
||||
4. **Related articles**: Links to relevant companion content
|
||||
5. **Metadata**: Category, tags, audience, last updated date
|
||||
|
||||
### Formatting Rules
|
||||
|
||||
- **Use headers (H2, H3)** to break content into scannable sections
|
||||
- **Use numbered lists** for sequential steps
|
||||
- **Use bullet lists** for non-sequential items
|
||||
- **Use bold** for UI element names, key terms, and emphasis
|
||||
- **Use code blocks** for commands, API calls, error messages, and configuration values
|
||||
- **Use tables** for comparisons, options, or reference data
|
||||
- **Use callouts/notes** for warnings, tips, and important caveats
|
||||
- **Keep paragraphs short** — 2-4 sentences max
|
||||
- **One idea per section** — if a section covers two topics, split it
|
||||
|
||||
## Writing for Searchability
|
||||
|
||||
Articles are useless if customers can't find them. Optimize every article for search:
|
||||
|
||||
### Title Best Practices
|
||||
|
||||
| Good Title | Bad Title | Why |
|
||||
|------------|-----------|-----|
|
||||
| "How to configure SSO with Okta" | "SSO Setup" | Specific, includes the tool name customers search for |
|
||||
| "Fix: Dashboard shows blank page" | "Dashboard Issue" | Includes the symptom customers experience |
|
||||
| "API rate limits and quotas" | "API Information" | Includes the specific terms customers search for |
|
||||
| "Error: 'Connection refused' when importing data" | "Import Problems" | Includes the exact error message |
|
||||
|
||||
### Keyword Optimization
|
||||
|
||||
- **Include exact error messages** — customers copy-paste error text into search
|
||||
- **Use customer language**, not internal terminology — "can't log in" not "authentication failure"
|
||||
- **Include common synonyms** — "delete/remove", "dashboard/home page", "export/download"
|
||||
- **Add alternate phrasings** — address the same issue from different angles in the overview
|
||||
- **Tag with product areas** — make sure category and tags match how customers think about the product
|
||||
|
||||
### Opening Sentence Formula
|
||||
|
||||
Start every article with a sentence that restates the problem or task in plain language:
|
||||
|
||||
- **How-to**: "This guide shows you how to [accomplish X]."
|
||||
- **Troubleshooting**: "If you're seeing [symptom], this article explains how to fix it."
|
||||
- **FAQ**: "[Question in the customer's words]? Here's the answer."
|
||||
- **Known issue**: "Some users are experiencing [symptom]. Here's what we know and how to work around it."
|
||||
|
||||
## Article Type Templates
|
||||
|
||||
### How-to Articles
|
||||
|
||||
**Purpose**: Step-by-step instructions for accomplishing a task.
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
# How to [accomplish task]
|
||||
|
||||
[Overview — what this guide covers and when you'd use it]
|
||||
|
||||
## Prerequisites
|
||||
- [What's needed before starting]
|
||||
|
||||
## Steps
|
||||
### 1. [Action]
|
||||
[Instruction with specific details]
|
||||
|
||||
### 2. [Action]
|
||||
[Instruction]
|
||||
|
||||
## Verify It Worked
|
||||
[How to confirm success]
|
||||
|
||||
## Common Issues
|
||||
- [Issue]: [Fix]
|
||||
|
||||
## Related Articles
|
||||
- [Links]
|
||||
```
|
||||
|
||||
**Best practices**:
|
||||
- Start each step with a verb
|
||||
- Include the specific path: "Go to Settings > Integrations > API Keys"
|
||||
- Mention what the user should see after each step ("You should see a green confirmation banner")
|
||||
- Test the steps yourself or verify with a recent ticket resolution
|
||||
|
||||
### Troubleshooting Articles
|
||||
|
||||
**Purpose**: Diagnose and resolve a specific problem.
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
# [Problem description — what the user sees]
|
||||
|
||||
## Symptoms
|
||||
- [What the user observes]
|
||||
|
||||
## Cause
|
||||
[Why this happens — brief, non-jargon explanation]
|
||||
|
||||
## Solution
|
||||
### Option 1: [Primary fix]
|
||||
[Steps]
|
||||
|
||||
### Option 2: [Alternative if Option 1 doesn't work]
|
||||
[Steps]
|
||||
|
||||
## Prevention
|
||||
[How to avoid this in the future]
|
||||
|
||||
## Still Having Issues?
|
||||
[How to get help]
|
||||
```
|
||||
|
||||
**Best practices**:
|
||||
- Lead with symptoms, not causes — customers search for what they see
|
||||
- Provide multiple solutions when possible (most likely fix first)
|
||||
- Include a "Still having issues?" section that points to support
|
||||
- If the root cause is complex, keep the customer-facing explanation simple
|
||||
|
||||
### FAQ Articles
|
||||
|
||||
**Purpose**: Quick answer to a common question.
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
# [Question — in the customer's words]
|
||||
|
||||
[Direct answer — 1-3 sentences]
|
||||
|
||||
## Details
|
||||
[Additional context, nuance, or explanation if needed]
|
||||
|
||||
## Related Questions
|
||||
- [Link to related FAQ]
|
||||
- [Link to related FAQ]
|
||||
```
|
||||
|
||||
**Best practices**:
|
||||
- Answer the question in the first sentence
|
||||
- Keep it concise — if the answer needs a walkthrough, it's a how-to, not an FAQ
|
||||
- Group related FAQs and link between them
|
||||
|
||||
### Known Issue Articles
|
||||
|
||||
**Purpose**: Document a known bug or limitation with a workaround.
|
||||
|
||||
**Structure**:
|
||||
```
|
||||
# [Known Issue]: [Brief description]
|
||||
|
||||
**Status:** [Investigating / Workaround Available / Fix In Progress / Resolved]
|
||||
**Affected:** [Who/what is affected]
|
||||
**Last updated:** [Date]
|
||||
|
||||
## Symptoms
|
||||
[What users experience]
|
||||
|
||||
## Workaround
|
||||
[Steps to work around the issue, or "No workaround available"]
|
||||
|
||||
## Fix Timeline
|
||||
[Expected fix date or current status]
|
||||
|
||||
## Updates
|
||||
- [Date]: [Update]
|
||||
```
|
||||
|
||||
**Best practices**:
|
||||
- Keep the status current — nothing erodes trust faster than a stale known issue article
|
||||
- Update the article when the fix ships and mark as resolved
|
||||
- If resolved, keep the article live for 30 days for customers still searching the old symptoms
|
||||
|
||||
## Review and Maintenance Cadence
|
||||
|
||||
Knowledge bases decay without maintenance. Follow this schedule:
|
||||
|
||||
| Activity | Frequency | Who |
|
||||
|----------|-----------|-----|
|
||||
| **New article review** | Before publishing | Peer review + SME for technical content |
|
||||
| **Accuracy audit** | Quarterly | Support team reviews top-traffic articles |
|
||||
| **Stale content check** | Monthly | Flag articles not updated in 6+ months |
|
||||
| **Known issue updates** | Weekly | Update status on all open known issues |
|
||||
| **Analytics review** | Monthly | Check which articles have low helpfulness ratings or high bounce rates |
|
||||
| **Gap analysis** | Quarterly | Identify top ticket topics without KB articles |
|
||||
|
||||
### Article Lifecycle
|
||||
|
||||
1. **Draft**: Written, needs review
|
||||
2. **Published**: Live and available to customers
|
||||
3. **Needs update**: Flagged for revision (product change, feedback, or age)
|
||||
4. **Archived**: No longer relevant but preserved for reference
|
||||
5. **Retired**: Removed from the knowledge base
|
||||
|
||||
### When to Update vs. Create New
|
||||
|
||||
**Update existing** when:
|
||||
- The product changed and steps need refreshing
|
||||
- The article is mostly right but missing a detail
|
||||
- Feedback indicates customers are confused by a specific section
|
||||
- A better workaround or solution was found
|
||||
|
||||
**Create new** when:
|
||||
- A new feature or product area needs documentation
|
||||
- A resolved ticket reveals a gap — no article exists for this topic
|
||||
- The existing article covers too many topics and should be split
|
||||
- A different audience needs the same information explained differently
|
||||
|
||||
## Linking and Categorization Taxonomy
|
||||
|
||||
### Category Structure
|
||||
|
||||
Organize articles into a hierarchy that matches how customers think:
|
||||
|
||||
```
|
||||
Getting Started
|
||||
├── Account setup
|
||||
├── First-time configuration
|
||||
└── Quick start guides
|
||||
|
||||
Features & How-tos
|
||||
├── [Feature area 1]
|
||||
├── [Feature area 2]
|
||||
└── [Feature area 3]
|
||||
|
||||
Integrations
|
||||
├── [Integration 1]
|
||||
├── [Integration 2]
|
||||
└── API reference
|
||||
|
||||
Troubleshooting
|
||||
├── Common errors
|
||||
├── Performance issues
|
||||
└── Known issues
|
||||
|
||||
Billing & Account
|
||||
├── Plans and pricing
|
||||
├── Billing questions
|
||||
└── Account management
|
||||
```
|
||||
|
||||
### Linking Best Practices
|
||||
|
||||
- **Link from troubleshooting to how-to**: "For setup instructions, see [How to configure X]"
|
||||
- **Link from how-to to troubleshooting**: "If you encounter errors, see [Troubleshooting X]"
|
||||
- **Link from FAQ to detailed articles**: "For a full walkthrough, see [Guide to X]"
|
||||
- **Link from known issues to workarounds**: Keep the chain from problem to solution short
|
||||
- **Use relative links** within the KB — they survive restructuring better than absolute URLs
|
||||
- **Avoid circular links** — if A links to B, B shouldn't link back to A unless both are genuinely useful entry points
|
||||
|
||||
## KB Writing Best Practices
|
||||
|
||||
1. Write for the customer who is frustrated and searching for an answer — be clear, direct, and helpful
|
||||
2. Every article should be findable through search using the words a customer would type
|
||||
3. Test your articles — follow the steps yourself or have someone unfamiliar with the topic follow them
|
||||
4. Keep articles focused — one problem, one solution. Split if an article is growing too long
|
||||
5. Maintain aggressively — a wrong article is worse than no article
|
||||
6. Track what's missing — every ticket that could have been a KB article is a content gap
|
||||
7. Measure impact — articles that don't get traffic or don't reduce tickets need to be improved or retired
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
name: ticket-triage
|
||||
description: Triage and prioritize a support ticket or customer issue. Use when a new ticket comes in and needs categorization, assigning P1-P4 priority, deciding which team should handle it, or checking whether it's a duplicate or known issue before routing.
|
||||
argument-hint: "<ticket or issue description>"
|
||||
---
|
||||
|
||||
# /ticket-triage
|
||||
|
||||
> If you see unfamiliar placeholders or need to check which tools are connected, see [CONNECTORS.md](../../CONNECTORS.md).
|
||||
|
||||
Categorize, prioritize, and route an incoming support ticket or customer issue. Produces a structured triage assessment with a suggested initial response.
|
||||
|
||||
## Usage
|
||||
|
||||
```
|
||||
/ticket-triage <ticket text, customer message, or issue description>
|
||||
```
|
||||
|
||||
Examples:
|
||||
- `/ticket-triage Customer says their dashboard has been showing a blank page since this morning`
|
||||
- `/ticket-triage "I was charged twice for my subscription this month"`
|
||||
- `/ticket-triage User can't connect their SSO — getting a 403 error on the callback URL`
|
||||
- `/ticket-triage Feature request: they want to export reports as PDF`
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Parse the Issue
|
||||
|
||||
Read the input and extract:
|
||||
|
||||
- **Core problem**: What is the customer actually experiencing?
|
||||
- **Symptoms**: What specific behavior or error are they seeing?
|
||||
- **Customer context**: Who is this? Any account details, plan level, or history available?
|
||||
- **Urgency signals**: Are they blocked? Is this production? How many users affected?
|
||||
- **Emotional state**: Frustrated, confused, matter-of-fact, escalating?
|
||||
|
||||
### 2. Categorize and Prioritize
|
||||
|
||||
Using the category taxonomy and priority framework below:
|
||||
|
||||
- Assign a **primary category** (bug, how-to, feature request, billing, account, integration, security, data, performance) and an optional secondary category
|
||||
- Assign a **priority** (P1–P4) based on impact and urgency
|
||||
- Identify the **product area** the issue maps to
|
||||
|
||||
### 3. Check for Duplicates and Known Issues
|
||||
|
||||
Before routing, check available sources:
|
||||
|
||||
- **~~support platform**: Search for similar open or recently resolved tickets
|
||||
- **~~knowledge base**: Check for known issues or existing documentation
|
||||
- **~~project tracker**: Check if there's an existing bug report or feature request
|
||||
|
||||
Apply the duplicate detection process below.
|
||||
|
||||
### 4. Determine Routing
|
||||
|
||||
Using the routing rules below, recommend which team or queue should handle this based on category and complexity.
|
||||
|
||||
### 5. Generate Triage Output
|
||||
|
||||
```
|
||||
## Triage: [One-line issue summary]
|
||||
|
||||
**Category:** [Primary] / [Secondary if applicable]
|
||||
**Priority:** [P1-P4] — [Brief justification]
|
||||
**Product area:** [Area/team]
|
||||
|
||||
### Issue Summary
|
||||
[2-3 sentence summary of what the customer is experiencing]
|
||||
|
||||
### Key Details
|
||||
- **Customer:** [Name/account if known]
|
||||
- **Impact:** [Who and what is affected]
|
||||
- **Workaround:** [Available / Not available / Unknown]
|
||||
- **Related tickets:** [Links to similar issues if found]
|
||||
- **Known issue:** [Yes — link / No / Checking]
|
||||
|
||||
### Routing Recommendation
|
||||
**Route to:** [Team or queue]
|
||||
**Why:** [Brief reasoning]
|
||||
|
||||
### Suggested Initial Response
|
||||
[Draft first response to the customer — acknowledge the issue,
|
||||
set expectations, provide workaround if available.
|
||||
Use the auto-response templates below as a starting point.]
|
||||
|
||||
### Internal Notes
|
||||
- [Any additional context for the agent picking this up]
|
||||
- [Reproduction hints if it's a bug]
|
||||
- [Escalation triggers to watch for]
|
||||
```
|
||||
|
||||
### 6. Offer Next Steps
|
||||
|
||||
After presenting the triage:
|
||||
- "Want me to draft a full response to the customer?"
|
||||
- "Should I search for more context on this issue?"
|
||||
- "Want me to check if this is a known bug in the tracker?"
|
||||
- "Should I escalate this? I can package it with /customer-escalation."
|
||||
|
||||
---
|
||||
|
||||
## Category Taxonomy
|
||||
|
||||
Assign every ticket a **primary category** and optionally a **secondary category**:
|
||||
|
||||
| Category | Description | Signal Words |
|
||||
|----------|-------------|-------------|
|
||||
| **Bug** | Product is behaving incorrectly or unexpectedly | Error, broken, crash, not working, unexpected, wrong, failing |
|
||||
| **How-to** | Customer needs guidance on using the product | How do I, can I, where is, setting up, configure, help with |
|
||||
| **Feature request** | Customer wants a capability that doesn't exist | Would be great if, wish I could, any plans to, requesting |
|
||||
| **Billing** | Payment, subscription, invoice, or pricing issues | Charge, invoice, payment, subscription, refund, upgrade, downgrade |
|
||||
| **Account** | Account access, permissions, settings, or user management | Login, password, access, permission, SSO, locked out, can't sign in |
|
||||
| **Integration** | Issues connecting to third-party tools or APIs | API, webhook, integration, connect, OAuth, sync, third-party |
|
||||
| **Security** | Security concerns, data access, or compliance questions | Data breach, unauthorized, compliance, GDPR, SOC 2, vulnerability |
|
||||
| **Data** | Data quality, migration, import/export issues | Missing data, export, import, migration, incorrect data, duplicates |
|
||||
| **Performance** | Speed, reliability, or availability issues | Slow, timeout, latency, down, unavailable, degraded |
|
||||
|
||||
### Category Determination Tips
|
||||
|
||||
- If the customer reports **both** a bug and a feature request, the bug is primary
|
||||
- If they can't log in due to a bug, category is **Bug** (not Account) — root cause drives the category
|
||||
- "It used to work and now it doesn't" = **Bug**
|
||||
- "I want it to work differently" = **Feature request**
|
||||
- "How do I make it work?" = **How-to**
|
||||
- When in doubt, lean toward **Bug** — it's better to investigate than dismiss
|
||||
|
||||
## Priority Framework
|
||||
|
||||
### P1 — Critical
|
||||
**Criteria:** Production system down, data loss or corruption, security breach, all or most users affected.
|
||||
|
||||
- The customer cannot use the product at all
|
||||
- Data is being lost, corrupted, or exposed
|
||||
- A security incident is in progress
|
||||
- The issue is worsening or expanding in scope
|
||||
|
||||
**SLA expectation:** Respond within 1 hour. Continuous work until resolved or mitigated. Updates every 1-2 hours.
|
||||
|
||||
### P2 — High
|
||||
**Criteria:** Major feature broken, significant workflow blocked, many users affected, no workaround.
|
||||
|
||||
- A core workflow is broken but the product is partially usable
|
||||
- Multiple users are affected or a key account is impacted
|
||||
- The issue is blocking time-sensitive work
|
||||
- No reasonable workaround exists
|
||||
|
||||
**SLA expectation:** Respond within 4 hours. Active investigation same day. Updates every 4 hours.
|
||||
|
||||
### P3 — Medium
|
||||
**Criteria:** Feature partially broken, workaround available, single user or small team affected.
|
||||
|
||||
- A feature isn't working correctly but a workaround exists
|
||||
- The issue is inconvenient but not blocking critical work
|
||||
- A single user or small team is affected
|
||||
- The customer is not escalating urgently
|
||||
|
||||
**SLA expectation:** Respond within 1 business day. Resolution or update within 3 business days.
|
||||
|
||||
### P4 — Low
|
||||
**Criteria:** Minor inconvenience, cosmetic issue, general question, feature request.
|
||||
|
||||
- Cosmetic or UI issues that don't affect functionality
|
||||
- Feature requests and enhancement ideas
|
||||
- General questions or how-to inquiries
|
||||
- Issues with simple, documented solutions
|
||||
|
||||
**SLA expectation:** Respond within 2 business days. Resolution at normal pace.
|
||||
|
||||
### Priority Escalation Triggers
|
||||
|
||||
Automatically bump priority up when:
|
||||
- Customer has been waiting longer than the SLA allows
|
||||
- Multiple customers report the same issue (pattern detected)
|
||||
- The customer explicitly escalates or mentions executive involvement
|
||||
- A workaround that was in place stops working
|
||||
- The issue expands in scope (more users, more data, new symptoms)
|
||||
|
||||
## Routing Rules
|
||||
|
||||
Route tickets based on category and complexity:
|
||||
|
||||
| Route to | When |
|
||||
|----------|------|
|
||||
| **Tier 1 (frontline support)** | How-to questions, known issues with documented solutions, billing inquiries, password resets |
|
||||
| **Tier 2 (senior support)** | Bugs requiring investigation, complex configuration, integration troubleshooting, account issues |
|
||||
| **Engineering** | Confirmed bugs needing code fixes, infrastructure issues, performance degradation |
|
||||
| **Product** | Feature requests with significant demand, design decisions, workflow gaps |
|
||||
| **Security** | Data access concerns, vulnerability reports, compliance questions |
|
||||
| **Billing/Finance** | Refund requests, contract disputes, complex billing adjustments |
|
||||
|
||||
## Duplicate Detection
|
||||
|
||||
Before creating a new ticket or routing, check for duplicates:
|
||||
|
||||
1. **Search by symptom**: Look for tickets with similar error messages or descriptions
|
||||
2. **Search by customer**: Check if this customer has an open ticket for the same issue
|
||||
3. **Search by product area**: Look for recent tickets in the same feature area
|
||||
4. **Check known issues**: Compare against documented known issues
|
||||
|
||||
**If a duplicate is found:**
|
||||
- Link the new ticket to the existing one
|
||||
- Notify the customer that this is a known issue being tracked
|
||||
- Add any new information from the new report to the existing ticket
|
||||
- Bump priority if the new report adds urgency (more customers affected, etc.)
|
||||
|
||||
## Auto-Response Templates by Category
|
||||
|
||||
### Bug — Initial Response
|
||||
```
|
||||
Thank you for reporting this. I can see how [specific impact]
|
||||
would be disruptive for your work.
|
||||
|
||||
I've logged this as a [priority] issue and our team is
|
||||
investigating. [If workaround exists: "In the meantime, you
|
||||
can [workaround]."]
|
||||
|
||||
I'll update you within [SLA timeframe] with what we find.
|
||||
```
|
||||
|
||||
### How-to — Initial Response
|
||||
```
|
||||
Great question! [Direct answer or link to documentation]
|
||||
|
||||
[If more complex: "Let me walk you through the steps:"]
|
||||
[Steps or guidance]
|
||||
|
||||
Let me know if that helps, or if you have any follow-up
|
||||
questions.
|
||||
```
|
||||
|
||||
### Feature Request — Initial Response
|
||||
```
|
||||
Thank you for this suggestion — I can see why [capability]
|
||||
would be valuable for your workflow.
|
||||
|
||||
I've documented this and shared it with our product team.
|
||||
While I can't commit to a specific timeline, your feedback
|
||||
directly informs our roadmap priorities.
|
||||
|
||||
[If alternative exists: "In the meantime, you might find
|
||||
[alternative] helpful for achieving something similar."]
|
||||
```
|
||||
|
||||
### Billing — Initial Response
|
||||
```
|
||||
I understand billing issues need prompt attention. Let me
|
||||
look into this for you.
|
||||
|
||||
[If straightforward: resolution details]
|
||||
[If complex: "I'm reviewing your account now and will have
|
||||
an answer for you within [timeframe]."]
|
||||
```
|
||||
|
||||
### Security — Initial Response
|
||||
```
|
||||
Thank you for flagging this — we take security concerns
|
||||
seriously and are reviewing this immediately.
|
||||
|
||||
I've escalated this to our security team for investigation.
|
||||
We'll follow up with you within [timeframe] with our findings.
|
||||
|
||||
[If action is needed: "In the meantime, we recommend
|
||||
[protective action]."]
|
||||
```
|
||||
|
||||
## Triage Best Practices
|
||||
|
||||
1. Read the full ticket before categorizing — context in later messages often changes the assessment
|
||||
2. Categorize by **root cause**, not just the symptom described
|
||||
3. When in doubt on priority, err on the side of higher — it's easier to de-escalate than to recover from a missed SLA
|
||||
4. Always check for duplicates and known issues before routing
|
||||
5. Write internal notes that help the next person pick up context quickly
|
||||
6. Include what you've already checked or ruled out to avoid duplicate investigation
|
||||
7. Flag patterns — if you're seeing the same issue repeatedly, escalate the pattern even if individual tickets are low priority
|
||||
Reference in New Issue
Block a user