mongo-ai/posthog-ship-fix

Ship-a-fix workflow

When to use

After the triage report identifies one of:

• A docs gap (missing page, incomplete instructions, misleading guidance)
• A troubleshooting step that should be documented
• A known issue that needs a public-facing note
• A simple code comment or error message that could be clearer

Step 1: Classify the fix type

| Type | Repo | Path pattern | Effort | |------|------|-------------|--------| | Docs update | PostHog/posthog.com | contents/docs/{product}/{page}.mdx | Low | | Troubleshooting addition | PostHog/posthog.com | contents/docs/{product}/troubleshooting.mdx | Low | | New troubleshooting section | PostHog/posthog.com | contents/docs/{product}/troubleshooting.mdx | Medium | | SDK docs update | PostHog/posthog.com | contents/docs/libraries/{sdk}/index.mdx | Low | | Handbook update | PostHog/posthog.com | contents/handbook/{section}/{page}.md | Low | | Error message improvement | PostHog/posthog-{sdk} | varies | Medium | | Code comment / docstring | PostHog/posthog | varies | Medium |

Step 2: Find the exact file

For docs fixes (most common)

Map the product area to the docs path:

| Product | Docs path | |---------|----------| | Session replay | contents/docs/session-replay/ | | Feature flags | contents/docs/feature-flags/ | | Experiments | contents/docs/experiments/ | | Events / ingestion | contents/docs/product-analytics/ | | Error tracking | contents/docs/error-tracking/ | | Surveys | contents/docs/surveys/ | | Pipelines / CDP | contents/docs/cdp/ | | Data warehouse | contents/docs/data-warehouse/ | | Web analytics | contents/docs/web-analytics/ | | SDKs | contents/docs/libraries/{sdk-name}/ |

Read the current file:

gh api repos/PostHog/posthog.com/contents/{path} --jq '.content' | base64 -d

For code fixes

Use DeepWiki to identify the relevant source file:

DeepWiki ask_question("PostHog/posthog-{sdk}",
  "Where is the code that handles {specific behavior}?")

Or use GitHub search:

gh search code --repo PostHog/posthog-{sdk} "{function or error string}"

Step 3: Draft the change

For docs additions

Write the new content in the same style as the existing page. PostHog docs are:

• Direct — no fluff, get to the point
• Practical — steps, code snippets, exact UI paths
• Scannable — headers, bullet points, tables over paragraphs
• Uses MDX components like <ProductScreenshot>, <FeatureAvailability>

For troubleshooting additions

Follow the existing troubleshooting page structure:

### [Symptom the customer would describe]

[Brief explanation of why this happens]

[Solution — exact steps, code snippets, or config changes]

Step 4: Produce the PR brief

Output this format:

## PR Brief: [One-line description of the fix]

**Repo:** PostHog/posthog.com (or PostHog/posthog-{sdk})
**File:** `{exact file path}`
**Type:** Docs update / Troubleshooting addition / New section / Code fix

### Why

[1-2 sentences — what support ticket revealed this gap, who it helps]

### What to add/change

[The exact content to add, including where in the file it should go.
 Reference the section header it should go under, or "add after line X".]

```markdown
[The actual content to add — ready to paste]

How to verify

[How to confirm the fix is correct — e.g., "build docs locally and check posthog.com/docs/{path} renders correctly"]

Source ticket

[Reference to the triage report that identified this gap]

## Rules

- **Read before writing**: Always read the current file content before drafting
  changes. Don't guess what's there.
- **Match the style**: PostHog docs are informal, direct, practical. No
  corporate jargon. Say "you" not "the user."
- **Small changes only**: This skill is for docs updates and minor fixes.
  Don't attempt architectural changes or major feature work.
- **Don't submit automatically**: Produce the PR brief for the support engineer
  to review and submit. Never create PRs, push code, or modify the PostHog repos.
- **Link to the source**: Always reference which triage report / ticket revealed
  the gap so the PR has context.
- **Check if it already exists**: Before drafting a new section, search the
  existing docs to make sure it isn't already covered elsewhere.