Imported from oysteinkrog/dotfiles (.claude/skills/user-support-triage-for-saas-and-open-source-projects/SKILL.md). Install upstream with npx skills add oysteinkrog/dotfiles --skill user-support-triage-for-saas-and-open-source-projects. Copyright stays with the author.

User Support Triage — SaaS & Open-Source Projects

Table of Contents

• Quick Start (Cold-Start Agent, Read This First)
• Two Modes (Onboard Once, Triage Forever)
• When To Use
• The Confirmation Rule (Non-Negotiable)
• Onboarding Phase (Run Once Per Project)
• Triage Phase (Every Session — 6 Phases + Operators)
• Operator Library (Cognitive Moves For Triage)
• Live Escalation (User Waiting In Real Time)
• Risk-Tier Runbooks (One Click Away)
• Operationalization Quality Gates
• Anti-Patterns (Hard-Won, Generalized From Real Incidents)
• Companion Skills
• References
• When NOT to Use This Skill
• Self-Test

Quick Start (Cold-Start Agent, Read This First)

If you're triaging right now and this project has never been onboarded, stop and onboard first — triage without the map produces hallucinated APIs and wrong policies. Otherwise:

# 1. Confirm the support-triage map exists. If not, run onboarding (see Phase 0-4 below).
test -f <project>/.claude/support-triage/README.md \
  && test -f <project>/.claude/support-triage/01-architecture.md \
  || echo "MISSING: run onboarding first"

# 2. Bootstrap helper skills (idempotent — skips already-installed).
./scripts/check-skills.sh <project>/.claude/support-triage/.workspace
./scripts/install-referenced-skills.sh <project>/.claude/support-triage/.workspace

# 3. Start one full cycle workspace. It fetches ground truth and creates the
#    owner-review draft bundle; it never sends customer messages.
./scripts/triage-cycle.sh <project>

# Optional: validate a project adapter or fire-drill fixture before triage.
python3 ./scripts/validate-adapter-output.py /tmp/open-items.json

# Optional: validate the whole project support map after onboarding.
python3 ./scripts/validate-support-map.py <project>/.claude/support-triage

Pick the pipeline by signal (full table in ORCHESTRATOR-WORKFLOW.md):

• "I get error X when I do Y" → Pipeline A (routine bug)
• "Refund please" → Pipeline B/C (small / >$200)
• "I found a vulnerability" → Pipeline D (security; ESCALATE first, draft later)
• 3+ tickets same fingerprint in 1h → Pipeline E (outage; ONE comms thread, not N replies)
• "GDPR" / "Article 15/17/20" → Pipeline F (DSAR; identity-verify FIRST)
• Insults / "lawsuit" / "regulator" → Pipeline G (hostile; do not mirror tone)
• "Can you add X?" → Pipeline H (feature request; 5–10 min budget)
• "I'm locked out" → Pipeline J (account recovery; identity-verify FIRST)
• "Webhook stopped working" → Pipeline K (integration failure)
• App-store/marketplace review, order dispute, or platform complaint → 🧭 DOMAIN-ADAPT first, then money/public-reply runbooks
• Employee/internal ops request → 🧭 DOMAIN-ADAPT; treat privacy/audit seriously even without external customers
• Healthcare/finance/education/minors/safety-regulated support → regulated mode; no agent-freelanced advice; counsel/compliance owner required
• OSS PR backlog, hostile contributor, or maintainer burnout → Pipeline N/O (OSS-specific; protect contributor time and maintainer bandwidth)
• NPS detractor, cancellation reason, repeated theme, or public mention → Pipeline V/R (VoC mining; turn support evidence into product intelligence)
• 3+ repeated how-to tickets or avoidable confusion → 📚 KB-SUGGEST + deflection loop
• Launch/pricing/migration likely to spike tickets → 🔮 PREDICT + pre-stage templates/comms
• Journalist / press contact → Pipeline T (counsel + comms-led; never agent-freelanced)
• Regulator / formal compliance inquiry → Pipeline U + ⛓ EVIDENCE-CHAIN (legal-hold mode)
• DPA, security questionnaire, custom MSA, enterprise SLA credit → ENTERPRISE-PLAYBOOKS.md; route to legal/security/account owner
• Feature/API/plan/product deprecation or shutdown → DEPRECATION-AND-SUNSET-COMMS.md; account-level impact + migration path
• Customer named harm; refund/credit/upgrade decision → 🎁 GOODWILL (four-dial calculus, not gut feel)
• Stage 3+ rage cycle / repeated ignored-feeling / identity threat → 🪄 EMPATHIZE → 🪜 LADDER (see CUSTOMER-PSYCHOLOGY.md)
• Accessibility barrier, screen-reader issue, low-bandwidth support, or complex formatting → ACCESSIBILITY-IN-SUPPORT.md
• Fraud/ATO/refund-abuse signals → FRAUD-AND-ABUSE-DETECTION.md before any account or money action
• Self-harm, abuse, stalking, violence, or minors-at-risk disclosure → TRAUMA-INFORMED-SUPPORT.md; stop routine triage
• Deceased user, executor, succession, or family access request → DECEASED-USER-AND-SUCCESSION.md; verify authority before data/account action

Hard floor before any send: ✓ CONFIRM operator (owner approval) + 🧹 DE-SLOPIFY pass via the canonical /de-slopify skill on the reply body. Both non-negotiable. Skipping either is the #1 trust-destroyer in real triage sessions.

Auto-install of /de-slopify: de-slopify is marked REQUIRED in scripts/check-skills.sh. Step 2 of bootstrap (install-referenced-skills.sh) installs it FIRST via jsm install de-slopify before any optional skill. If jsm is missing or unauthenticated, the bootstrap script prints the installer URL and continues — every customer-facing draft must then use the inline AI-tell remover fallback (VOICE-CALIBRATION.md + DE-SLOPIFY-INTEGRATION.md) until jsm install de-slopify succeeds. The same auto-install path covers every other referenced skill (codebase-archaeology, multi-model-triangulation, idea-wizard, etc.) on a best-effort basis; only de-slopify carries the REQUIRED-fail loud-warning.

User Support Triage (SaaS + OSS + Product Support)

Core Insight: User reports are hints, not facts. Triage is verification, not stenography. The first time a project is touched, the skill produces a durable map of where support lives — so every later session can dive straight into triage with no rediscovery. Every customer-facing message goes through the Confirmation Gate before sending.

Two Modes (Onboard Once, Triage Forever)

┌─────────────────────────────────────────────────────────────┐
│  ONBOARDING (one-time per project)                          │
│  ─────────────────────────────                              │
│  Codebase-archaeology + codebase-report applied to the      │
│  *support surface*. Outputs durable docs into the target    │
│  project at  .claude/support-triage/  so future sessions    │
│  load instantly. Ends with a policy-elicitation handshake   │
│  with the owner so refunds/SLAs/voice are codified.         │
└──────────────────────────┬──────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────────┐
│  TRIAGE (every session after)                               │
│  ────────────────────────────                               │
│  Read the onboarding map → fetch open items → classify →    │
│  apply operators (★ ORIENT, 🔍 REPRO, ⊕ CORRELATE, ⚖ DECIDE,│
│  ✉ DRAFT, ✓ CONFIRM, 📤 SEND, 🔁 VERIFY) → ask owner for    │
│  approval on every customer-facing send → act → file beads  │
│  → write an outcome record so the map improves next time.   │
└─────────────────────────────────────────────────────────────┘

Re-run onboarding only when the support surface changes materially (new ticketing system, new SLA tier, new business policy, new payment provider, new third-party support tool).

When To Use

• "Triage open tickets for <project>."
• "Review GitHub issues + PRs on owner/repo."
• "Onboard <project> to agent-driven support."
• "Map support for a marketplace, mobile app, community, internal tool, agency/client service, or regulated product."
• "User is escalating live and someone needs to investigate before responding."
• "SLA breach alert fired."
• "Refund / billing dispute landed."
• "Security report came in via DM."
• "GDPR/DSAR request received."
• "Hostile / harassing user — what now?"

If the project hasn't been onboarded yet, always run the onboarding phase first. Triage without the map produces hallucinated APIs, mis-routed escalations, and wrong response templates.

The Confirmation Rule (Non-Negotiable)

Never send a customer-facing message without explicit owner approval. Drafting, classifying, status updates, internal notes, beads — all fine without approval. Sending requires Y/n.

Draft → Show owner all drafts together → Owner edits/approves → Then send.

Why: a single confidently-wrong reply destroys more trust than a slow honest one. Confidence-without-evidence is the #1 cited anti-pattern from real triage sessions (ANTI-PATTERNS.md §10).

Exception: status-only acknowledgements that stop a SLA clock without sending email are OK without approval, because they're not customer-facing. Anything with email-out, public-comment, refund-execution, ban-action, or DM-reply requires approval.

Onboarding Phase (Run Once Per Project)

The onboarding output is <project>/.claude/support-triage/ — a folder of agent-intuitive markdown that future triage sessions load directly. Template: assets/ONBOARDING-TEMPLATE.md.

Phase 0 — Skill Bootstrap (Install Helper Skills via jsm)

This skill composes other skills (codebase-archaeology, codebase-report, github, admin-page-for-nextjs-sites, supabase, stripe-checkout, ga4, saas-customer-analytics, idea-wizard, user-support-ticketing-system-for-saas, e2e-testing-for-webapps, security-audit-for-saas, multi-model-triangulation). Before fan-out:

./scripts/check-skills.sh /path/to/project/.claude/support-triage/.workspace

Writes skill_inventory.json with present/missing per skill. If jsm is installed + authenticated and the user has an active jeffreys-skills.md subscription:

./scripts/install-referenced-skills.sh /path/to/project/.claude/support-triage/.workspace

If jsm is missing, walk the user through install (see SKILL-INSTALLATION.md). If they don't want a paid subscription, everything has an inline fallback — none of the helper skills are prerequisites. The skill always runs end-to-end with just gh + curl + your existing project tooling.

Phase 1 — Detect Support Surface

./scripts/detect-support-surface.sh /path/to/project
# → writes <project>/.claude/support-triage/_detection.json

Classifies the project into one or more of:

Most non-trivial projects hit multiple surfaces. Run each branch and merge findings into one onboarding doc.

Phase 2 — Map The Support Surface (codebase-archaeology applied narrowly)

For each detected surface, run the relevant playbook. Each produces a section of the onboarding doc:

.claude/support-triage/
├── README.md              ← orientation; what this folder is + how future agents load it
├── 00-intake.md           ← complexity band, routers, owner/source decisions
├── 01-architecture.md     ← codebase-archaeology output focused on support code paths
├── 02-channels.md         ← every place a user can ask for help (multi-channel intake)
├── 03-decision-matrix.md  ← issue-type → action → template (project-specific)
├── 04-templates/          ← response templates customized to brand voice
├── 05-policies.md         ← refund SOP, escalation paths, SLA tiers, business rules
├── 06-recurring-issues.md ← known issues + diagnostic shortcuts
├── 07-secrets.md          ← which env vars to read, which API keys to ask for (NOT the keys)
├── 08-voice.md            ← brand voice: register, sample phrases, do-say/don't-say
├── 09-knowledge-base.md   ← canonical answers; KB articles to link
├── 10-metrics.md          ← FRT/MTTR/CSAT targets and dashboards
├── 11-runbooks/           ← copy-paste runbooks per high-risk category (refund, security, GDPR)
├── 12-gap-dispositions.md ← explicit manual-only / blocked / policy-gap list
├── vocabularies/          ← controlled tags for themes/personas/outcomes when VoC is active
├── artifacts/             ← high-risk evidence, drafts, approvals, sends, verification
├── handoffs/              ← live escalation / migration machine-readable handoffs
└── _detection.json        ← machine-readable surface fingerprint

Section templates: assets/ONBOARDING-TEMPLATE.md. Voice analysis details: VOICE-CALIBRATION.md.

Every surface should eventually expose the universal adapter from ADAPTER-CONTRACT.md. The adapter is the contract that lets this skill triage GitHub, custom DB tickets, and third-party support tools through one read-only input shape.

Phase 3 — Resolve Ambiguity With The Owner

Onboarding always finds gaps. Surface them in a single batched prompt — never pester one-at-a-time:

🤔 ONBOARDING — POLICY DECISIONS NEEDED

We mapped your support surface but found ambiguity. Pick one for each:

1. SLA on P2 first response — current behavior is "no SLA tracked".
2. Refunds within 14 days — currently handled case-by-case.
3. Feature requests — currently get "thanks, logged" with no follow-up.
4. Hostile user posture — lock-and-block / owner-reviews / soft-decline?
5. Security-disclosure ack template — do you have one?
6. GDPR/DSAR contact and SLA?

Once you choose, we'll write these into 05-policies.md so the next session
can apply them automatically.

Full elicitation script: POLICY-ELICITATION.md.

Phase 4 — Wire Outbound Email (If Missing)

If the project sends customer email but RESEND_API_KEY (or equivalent) is missing, walk the owner through Resend setup (RESEND-SETUP.md). Same for Zendesk / Intercom / Help Scout API tokens — ask once, store via the project's existing secrets mechanism, document the names (not values) in 07-secrets.md.

Onboarding Acceptance

• _detection.json lists every surface
• 00-intake.md records complexity band, lifecycle mode, audience segments, routers used, and source anchors for owner answers
• 02-channels.md enumerates every place users can ask for help (don't miss email bounces, community/social, app-store/marketplace reviews, sales/customer-success handoffs, or internal ops queues)
• 03-decision-matrix.md covers ≥80% of historical ticket categories
• 05-policies.md answers: who gets refunded, who gets escalated, what's the SLA, who handles security/legal
• 07-secrets.md lists every env var name with a one-line purpose (NEVER the values)
• 08-voice.md has 5+ historical reply samples + voice analysis
• 11-runbooks/ has at least: REFUND, SECURITY-DISCLOSURE, GDPR-DSAR, HOSTILE-USER, OUTAGE-COMMS
• If the project wants product feedback loops, vocabularies/themes.md exists with owner-approved theme tags and a slow-growth policy
• At least one templated reply per category in 04-templates/
• Owner approved the policy decisions from Phase 3
• scripts/list-open.sh returns support-adapter-v1 JSON or clearly documents why a manual channel remains outside automation
• python3 <skill>/scripts/validate-adapter-output.py <open-items.json> passes for the project adapter
• At least one routine fire drill and one high-risk fire drill pass with no customer-visible sends
• 05-policies.md high-risk rules cite evidence anchors or TBD-OWNER
• 12-gap-dispositions.md gives every known gap one disposition: confirmed, not-applicable, manual-only, blocked-by-access, provider-gap, policy-gap, evidence-gap, deferred, or unknown
• High-risk runbooks point to the artifact contract for evidence, draft, approval, send, and verification records
• python3 <skill>/scripts/validate-support-map.py <project>/.claude/support-triage passes, or blockers are recorded with owners

Triage Phase (Every Session — 6 Phases + Operators)

Once onboarded, every triage session follows the 6-phase loop, applying operators within each phase. Always run in order — you can't draft without ground truth, can't act without drafts, and the skill does not improve unless outcomes are recorded.

Full per-phase playbook with surface-specific commands: TRIAGE-WORKFLOW.md. Operator library: OPERATOR-LIBRARY.md.

Accretive Support Flywheel

The session is not done when the last reply is sent. Phase 6 must route each meaningful support artifact to one value loop:

If no loop applies, record not-accretive-this-session in the outcome. Do not let support evidence disappear into a closed ticket.

What To Surface vs Just Handle

Operator Library (Cognitive Moves For Triage)

Adapted from /operationalizing-expertise Track A. Each operator has triggers, failure modes, and a copy-paste prompt module. Drop them into your working context per ticket. Full cards: OPERATOR-LIBRARY.md.

Live Escalation (User Waiting In Real Time)

Stakes are higher when an owner is relaying live customer chat. Different rules:

• Inventory the working tree — note overlapping edits before hotfixing, preserve unrelated work, and avoid touching peer-owned files; only overlapping dirty files should change the emergency plan.
• Relay verbatim quotes — paraphrased "Too Many Requests" loses the signal that says rate-limit-tier-bug.
• Assume the first fix surfaces another bug. Don't send "all fixed!" until the user confirms end-to-end.
• Schedule a fresh-eyes audit the next day — hotfixes-under-pressure miss things.

Full protocol: LIVE-ESCALATION.md.

Risk-Tier Runbooks (One Click Away)

These are the categories that must have a runbook because the cost of getting them wrong is high:

Each runbook has: trigger conditions, evidence to collect, decision tree, drafts, escalation path, audit-trail template.

Operationalization Quality Gates

Borrowed from /operationalizing-expertise: this skill is useful only if future agents can verify where every rule came from and can run the workflow without rediscovering context.

Before declaring a project onboarded:

1. Evidence anchors exist. Every non-obvious policy or recurring issue in 05-policies.md / 06-recurring-issues.md cites its source: owner answer, code path, ticket id, issue URL, commit SHA, or provider doc URL + access date.
2. Operator contract is executable. scripts/list-open.sh works for every channel in 02-channels.md; scripts/post-reply.sh is either implemented with the confirmation gate or intentionally exits with a clear "manual send only" message.
3. Kernel is concise. README.md + 03-decision-matrix.md should be enough for a cold agent to triage one routine ticket. Deep details live in runbooks and references.
4. Policy gaps are explicit. Unknowns are marked TBD-OWNER, batched into a single owner prompt, and never silently filled with guesses.
5. Counter-example tested. Run at least one routine ticket and one high-risk ticket (refund/security/GDPR/hostile) through the map. If the map does not route both cleanly, onboarding is not done.
6. Adapter contract validates. list-open.sh output passes ADAPTER-CONTRACT.md's validator, or the channel is documented as manual-only.
7. Fire drill passes. New runbooks/operators are rehearsed with FIRE-DRILL-HARNESS.md before being trusted in live support.
8. Outcome loop exists. Every live triage session writes the Phase 6 record from POST-SEND-OUTCOME.md.
9. Support map validates. The project map passes scripts/validate-support-map.py, including intake, gap dispositions, artifacts, handoffs, runbooks, adapter capabilities, and dispatch scripts.
10. Audience and lifecycle are explicit. Drafts and escalation choices name the audience/persona and lifecycle mode, not just the ticket category.
11. Pattern probes are used. Phase 2 investigations check the symptom against the issue-pattern library before accepting a narrow explanation.

When the skill itself is expanded, use the same rule: add operators, validation, or sharper failure modes. Do not add doctrine that gives agents more to read but nothing new to do.

Anti-Patterns (Hard-Won, Generalized From Real Incidents)

These mistakes cost real time and trust. Each maps to a specific failure mode from the corpus.

1. Trusting reported counts. "I think there are two tickets" → there were three. Always re-fetch.
2. Declaring a fix without end-to-end repro. Individual curls pass; the chained user flow still fails.
3. First fix is rarely the last. Plan for iteration; don't close the loop unilaterally.
4. Failing to correlate before responding. Two "different" reports often share one root cause.
5. Quoting stale admin notes. Old notes reference shipped fixes that didn't actually ship.
6. Deploy blockers compound under pressure. Keep workspace + CI green so hotfixes ship instantly.
7. Tier-blind rate limiting. Paid users hitting 429s = ticket factory.
8. Infra problems without a tracking ticket. "Noted" ≠ resolved.
9. Internal notes ≠ user notification. Verify the message actually reaches the user.
10. Confidence without evidence. "Yes, this works" with no production reproduction destroys trust irreparably.
11. Reopen-on-reply for closed tickets. Customer's tangential reply re-opens; SLA "breaches" immediately.
12. Math.random() for ticket IDs. Real bug: collisions; predictable IDs.
13. TTY-detection disabling headless fallback. VPS users locked out of OAuth.
14. Cron with missing CRON_SECRET. Silent 403s; SLAs untracked.
15. Auto-deploy disabled in vercel.json. Fix committed, never shipped.
16. DSAR erasure that leaves audit-log emails. Incomplete erasure → re-DSAR + complaint.
17. Public reply to a security report. Embargo blown; CVE assignment compromised.
18. Security.txt missing. Researchers find no responsible-disclosure path; vulns get posted publicly instead.
19. Public roadmap voting captured by 5 power users. Misaligns priorities.
20. Status page "all green" while support queue is 6h backed up. Monitoring measures uptime not response time.

Full case studies + how to recognize each early: ANTI-PATTERNS.md.

Companion Skills

• /user-support-ticketing-system-for-saas — scaffold a production-grade in-app ticketing system into a SaaS app that has none. Next.js is the default example; the handoff and adapter contracts are portable.
• /admin-page-for-nextjs-sites — broader admin cockpit; ticket triage UI is one slice.
• /saas-customer-analytics — churn / segment data informs triage prioritization.
• /codebase-archaeology + /codebase-report — used inside Onboarding Phase 2.
• /gh-cli (gh) — used inside the GitHub fork.
• /multi-model-triangulation — used by 🪞 SECOND-OPINION operator on hard cases.
• /security-audit-for-saas — referenced by SECURITY-DISCLOSURE runbook.
• /e2e-testing-for-webapps — used to write regression tests after fixing user-reported bugs.
• /idea-wizard — used for FEATURE-REQUEST replies that need a "smaller version we can ship".
• /cass — mine prior triage sessions for working patterns.

If a companion skill is not installed, every workflow has an inline fallback in this skill's references.

References

Core

Surface forks

Decision support

Risk-tier runbooks

Lifecycle

Composition / Craft

Scripts

Subagents

When NOT to Use This Skill

The skill is appropriate when there is (a) a real user inbound, (b) a project owner who can approve sends, and (c) a need to ship action plus reply within an SLA. If any are missing, route accordingly.

Self-Test

Should activate this skill:

• "Triage open tickets for my SaaS"
• "Onboard this project to agent-driven support"
• "Review GitHub issues on owner/repo"
• "User just reported they can't log in — investigate"
• "SLA breach alert; what do I do"
• "Customer is asking for a refund — walk me through it"
• "Someone DM'd a vulnerability — handle it"
• "We got a GDPR DSAR; respond"
• "Hostile user is spamming our Discord; what's the playbook"
• "Map support for our app-store reviews and marketplace order complaints"
• "Triage employee support requests for an internal ops tool"

Should NOT activate this skill (route accordingly):

• "Build the ticketing system / SLA engine / admin queue from scratch" → /user-support-ticketing-system-for-saas
• "Polish this draft for tone before sending" → /de-slopify (this skill calls /de-slopify; doesn't replace it)
• "OSS-only GitHub triage with no customer-comms layer" → /gh-triage-ru
• "Mine prior triage sessions for what I asked" → /cass
• "Pattern extraction across many projects" → /codebase-pattern-extraction
• "Generic README polish on the project's voice section" → /readme-writing

Pre-flight smoke (every triage session):

# Map exists? If not, the next call should be onboarding, not triage.
ls <project>/.claude/support-triage/01-architecture.md 2>/dev/null \
  && echo "ONBOARDED — proceed to Phase 1 of triage" \
  || echo "NOT ONBOARDED — run scripts/detect-support-surface.sh and onboarding first"

# Bootstrap helpers (idempotent)
./scripts/check-skills.sh <project>/.claude/support-triage/.workspace

If the map is missing, stop and onboard first. Triage without the map produces hallucinated APIs, wrong policies, and mis-routed escalations.