@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/starter-packs/support/Plugins/support-starter/skills/customer-escalation/SKILL.md

@@ -0,0 +1,246 @@
+---
+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
+
+> Names like `~~chat` or `~~project tracker` mean whichever tool of that kind is connected: a tool in one of your Hexis plugins, or one your agent has itself. The **knowledge base** is this workspace's knowledge base in Hexis, plus any other docs tool that is connected. When a source is not connected, skip it and say what you could not check.
+
+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
+
+Ask your agent for the `customer-escalation` skill by name, or just describe the job and it will pick the skill up. Give it: <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:** [L2 Support / 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

package/starter-packs/support/Plugins/support-starter/skills/customer-research/SKILL.md

@@ -0,0 +1,250 @@
+---
+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
+
+> Names like `~~chat` or `~~project tracker` mean whichever tool of that kind is connected: a tool in one of your Hexis plugins, or one your agent has itself. The **knowledge base** is this workspace's knowledge base in Hexis, plus any other docs tool that is connected. When a source is not connected, skip it and say what you could not check.
+
+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
+
+Ask your agent for the `customer-research` skill by name, or just describe the job and it will pick the skill up. Give it: <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 (this workspace's, in Hexis): 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)