mongo-ai/posthog-triage-report

Triage report generator

IMPORTANT: The canonical report structure is defined in the main agent prompt (.claude/agents/posthog-support-agent.md → "Triage report format"). If the agent prompt's template conflicts with this skill, the agent prompt wins. This skill provides supplementary guidance (Quick Brief, Evidence Pack detail) that complements the agent's structure.

Use this structure as a reference. The agent prompt may add sections (Context for Reviewers, Verify This Report, etc.) — always include those.

# PostHog Support Triage Report

**Ticket**: [ticket ID or short summary]
**Customer**: [org / user]
**Project**: [project ID]
**Issue Type**: [Bug / How-to / Feature request / Account / Integration / Data / Performance]
**Product Area**: [events / replay / flags / experiments / error tracking / surveys / pipelines / data warehouse / web analytics / other]
**Priority**: [P1 / P2 / P3 / P4]
**Plan Tier**: [Free / PAYG / Boost / Scale / Enterprise / Unknown]
**SLA Target**: [community only / 72h / 48h / 24h / 8h calendar hours / Unknown]
**Investigation Mode**: read-only

---

## Issue Summary

[What the customer reported, rewritten clearly]

## Evidence Gathered

| # | Query / Tool Used | Finding |
|---|-------------------|---------|
| 1 | [tool/query] | [finding] |
| 2 | [tool/query] | [finding] |
| 3 | [docs source] | [finding] |
| 4 | [GitHub search] | [finding] |

## Root-Cause Assessment

**Assessment**: [best current explanation]

**Confidence**:
- [ ] Confirmed by data
- [ ] Likely based on pattern match
- [ ] Suspected, needs human verification

**Reasoning**:
[Why this is the best explanation, including what supports it and what remains uncertain]

### Quick Brief (for you, not the customer)

> A 30-second read so you can understand and defend the diagnosis if the customer pushes back. 6-10 lines max.

- **What's actually happening** — [2-3 sentences explaining the technical issue like you're telling a colleague over coffee. Plain language, no jargon soup.]
- **Why we think this** — [The 1-2 strongest pieces of evidence and why they point here. E.g., "We found GitHub issue #X with the exact same symptoms" or "The docs say feature Y requires Z, and they don't have Z configured."]
- **What to say if they push back** — [Anticipate the most likely follow-up question and prepare a one-liner. E.g., "If they ask why it worked before: the v3.8.1 release changed the default throttle behavior."]
- **What you DON'T know** — [Honest gaps. E.g., "We couldn't verify their actual SDK version" or "This could also be a CSP issue but we'd need their browser console to confirm."]

## Known Bug Check

- **Search terms used**: ...
- **Matching issues found**: ...
- **Workaround available**: ...

## Recommended Next Action

1. ...
2. ...
3. ...

## Escalation Decision

- [ ] No escalation needed — handle in support
- [ ] Escalate to engineering

**Severity:** [Critical / High / Medium — see posthog-escalation skill]
**Reason**: [why this can't be resolved in support]
**Routing:** [which team — SDK, pipeline, replay, flags, platform, security]

> If escalating, generate a full escalation brief as an appendix using the
> `posthog-escalation` skill format. Include reproduction steps, evidence
> table, and a specific ask for engineering.

**Follow-up cadence:** [based on severity — Critical: 2-4h, High: 4-8h, Medium: daily]

## Docs Gap / Fix Suggestion

[If this ticket reveals a gap or fix opportunity, describe it here.
 PostHog values support engineers who "ship fixes, not just log bugs."]

- **Docs gap?** [Missing page, incomplete instructions, misleading guidance, or "None identified"]
- **Simple fix?** [Link to file + describe the change, or "None identified"]
- **Recurring issue?** [If this has come up before, suggest a KB article via posthog-kb-article skill]

## Draft Customer Response

> Use the `posthog-response-drafting` skill to draft this section.
> Match tone to the situation: collaborative for misconfig, empathetic for bugs,
> urgent for production-down. Never include internal tool names, HogQL queries,
> or project IDs in the customer-facing response.

[Ready-to-send response — follows acknowledgment → findings → next steps → closing structure]

## Evidence Pack

> For the support engineer reviewing this triage — maps every factual claim
> to a verifiable source. Do NOT include in customer-facing communication.

### Engineer TL;DR

> A 2-4 sentence plain-language summary of what's actually going on, written
> for the support engineer (not the customer). No jargon-avoidance needed here
> — be technically precise but concise. Think "what would I tell a colleague
> who walked up to my desk and asked what this ticket is about?"

**What's happening:** [Plain-language summary of the root cause or situation]
**How sure are we:** [One sentence on confidence — "Nailed it" / "Pretty sure but..." / "Best guess, needs verification"]
**What the customer needs to do:** [The actual action in one line]

### Issue Flow Diagram

> Include a Mermaid diagram when it helps the engineer understand the issue
> at a glance. Use for:
> - **Data flow issues**: Show where events/data flow breaks down
> - **Timing/race conditions**: Show the sequence that causes the bug
> - **Config chain issues**: Show what depends on what
> - **Decision trees**: Show the diagnostic path taken
>
> Skip the diagram for simple issues (e.g., "upgrade your SDK") with a brief
> note: "Simple issue — diagram not needed."

```mermaid
[Appropriate diagram type — flowchart, sequence, or graph. 5-10 nodes max.]

Claim-Source Map

| # | Claim (from response) | Source Type | Source URL / Reference | Supporting Snippet | Status | |---|----------------------|-------------|----------------------|-------------------|--------| | 1 | [factual assertion] | PostHog Docs | [URL] | "[exact quote or summary]" | Verified | | 2 | [factual assertion] | GitHub Issue | [URL] | "[status, key detail]" | Verified | | 3 | [factual assertion] | Project Data | [HogQL query used] | "[result summary]" | Verified | | 4 | [factual assertion] | SDK Docs | [Context7 query] | "[finding]" | Inferred | | 5 | [factual assertion] | — | — | — | Unverified |

Source types: PostHog Docs / GitHub Issue / GitHub PR / Project Data (HogQL) / SDK Docs (Context7) / Codebase (DeepWiki) / Browser Inspection / Community Thread

Status definitions:

• Verified: Source directly confirms the claim
• Inferred: Source is consistent but does not directly confirm (pattern match, architectural reasoning, similar-but-not-identical issue)
• Unverified: No supporting source found — requires human verification

Confidence Score

Overall: [High/Medium/Low] ([N]%)

Calculation: (verified_count x 1.0 + inferred_count x 0.5) / total_claims x 100

• Verified claims: [N] of [total]
• Inferred claims: [N] of [total]
• Unverified claims: [N] of [total]

Confidence drivers:

• Up: [e.g., "Exact GitHub issue match with same symptoms"]
• Down: [e.g., "No project data available — could not verify customer's actual config"]

What would increase confidence:

• [e.g., "Customer sharing posthog.init() config would verify claims 2 and 4"]

Source Cross-Reference

| # | Source | URL / Reference | Claims Supported | |---|--------|----------------|-----------------| | 1 | [source name] | [URL] | Claims 1, 3 | | 2 | [source name] | [URL] | Claims 2, 5 |

Contradictions found: [None / describe any conflicting information between sources]

## Output files

Every triage produces these outputs (saved by the agent in Phase 3):

1. **Triage report** — this full template, saved to `triage-reports/`
2. **Customer response** — the Draft Customer Response section extracted as a
   standalone file for easy copy-paste into Zendesk/GitHub
3. **Slack message** (when posting) — internal triage summary formatted per
   `posthog-slack-triage` skill, plus customer response as a thread reply

The customer response file contains ONLY the customer-facing text — no evidence
pack, no internal notes, no emoji. Ready to paste directly into the reply channel.

When the `posthog-slack-triage` skill posts to Slack, it MUST post the customer
response as a thread reply on the internal triage message. This keeps the channel
scannable while making the customer draft immediately accessible.

## Checklist

Before finalizing:

1. Every evidence line must cite a real tool/query
2. Version-sensitive claims must come from live docs (docs-search or Context7)
3. GitHub must be searched with at least 2 variants
4. Confidence must be honest
5. If confidence is only suspected, escalation should be recommended
6. Every troubleshooting recommendation must cite a live docs-search result or
   GitHub issue — not embedded skill knowledge
7. Include docs-search source URLs in the evidence table
8. Draft Customer Response follows posthog-response-drafting quality checklist
9. If escalating, escalation brief follows posthog-escalation format
10. Customer response tone matches the situation (check tone spectrum)
11. Engineer TL;DR is present, technically precise, and covers what/confidence/action
12. Mermaid diagram included if issue involves data flow, timing, or config chains
    (skipped with brief note if issue is simple)
13. Evidence Pack complete: every claim mapped or marked Unverified
14. Confidence score calculated correctly and matches claim counts
15. No Unverified claims remain in response without being hedged or flagged
16. Source Cross-Reference lists all unique sources with what they confirmed
17. Any contradictions between sources are flagged
18. Quick Brief is present, concise (6-10 lines), and covers all four points: what's happening, why we think this, pushback prep, and honest gaps
19. Customer response extracted as standalone file (no internal notes leaked)
20. If Slack posting requested: customer response queued as thread reply