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

package/starter-packs/support/Plugins/support-starter/skills/kb-article/SKILL.md

@@ -0,0 +1,350 @@
+---
+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
+
+> 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.
+
+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
+
+Ask your agent for the `kb-article` skill by name, or just describe the job and it will pick the skill up. Give it: <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]
+**Last updated:** [Date]
+
+---
+
+[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

package/starter-packs/support/Plugins/support-starter/skills/ticket-triage/SKILL.md

@@ -0,0 +1,273 @@
+---
+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
+
+> 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.
+
+Categorize, prioritize, and route an incoming support ticket or customer issue. Produces a structured triage assessment with a suggested initial response.
+
+## Usage
+
+Ask your agent for the `ticket-triage` skill by name, or just describe the job and it will pick the skill up. Give it: <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 the customer-escalation skill."
+
+---
+
+## 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

package/starter-packs/support/pack.yaml

@@ -0,0 +1,12 @@
+id: support
+name: Support
+description: "Pages about your products, known issues and tone, and skills for triage, replies, escalations and help articles."
+order: 3
+firstPagePrompt: |
+  Using our Hexis knowledge base, fill in the Products page in Knowledge for our support team: what each product does, who uses it, the questions customers ask most, and where to send what support can't answer. Ask me for anything you don't know, then save it.
+suggestedPages:
+  - "Products"
+  - "Known issues"
+  - "Tone of voice"
+  - "Escalations"
+  - "Glossary"