PostHog / PostHog/warlock

Add INTEGRATING.md guide for consumers

Open Beginner friendly
#31 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
0
Forks
1
PR merge metrics
No merged PRs in 30d

Description

Problem

The Warlock skill (.claude/skills/warlock) references an INTEGRATING.md"guide for engineers integrating the Warlock into a consumer application; update this when changing the public API" — but the file doesn't actually exist. The repo only has README.md and CONTRIBUTING.md.

Right now the README doubles as both the charter/design doc and the de-facto integration reference. That works, but there's no single place that walks a consumer (context-mill, and future ones) through wiring the Warlock in end to end.

What it should cover

  • Installing the Warlock as a dependency (incl. the git+https://... install pattern context-mill currently uses, and how to refresh it)
  • Minimal scan() usage + reading ScanMatch (rule, metadata, matchedStrings)
  • Opt-in triageMatches() usage: providing an LLM callback, batching/truncation behavior, the fail-safe-to-true_positive contract
  • Which parts of the API are stable vs. which evolve (rule names are not API; categories/severities are)
  • A note that consumers decide actions — the Warlock only detects

Why the Warlock is the right home

Integration guidance for the Warlock's public API belongs next to the API it documents, so it stays in sync when the API changes. Putting it in a consumer repo would drift and wouldn't serve future consumers equally.

Context

Surfaced while adding the matchedStrings field to ScanMatch — updating the docs revealed the referenced INTEGRATING.md was never created.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Read README.md, CONTRIBUTING.md, and the .claude/skills/warlock reference before creating INTEGRATING.md. Document dependency installation and refresh steps, scan() and ScanMatch usage, opt-in triageMatches() behavior, stable versus evolving API elements, and the consumer's responsibility for actions; done means a consumer can follow the guide end to end.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
78/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.