chore(metrics): remove in-repo internal design docs#73003
Conversation
Delete docs/internal/metrics/dashboard-mvp.md and deployment-layout.md. These are point-in-time design/planning artifacts (status fields, in-flight PR references, status matrices, deadlines) rather than durable architecture references. Nothing in the repo links to them, and one points to a sibling doc that does not exist. Generated-By: PostHog Code Task-Id: 2bbfdaa6-874f-4759-952a-30409e069fec
|
😎 This pull request was merged. |
DanielVisca
added
the
skip-agent-review
PostHog
|
Hey @DanielVisca! 👋 It looks like your git author email on this PR isn't your
You can fix it for this repo with: git config user.email "you@posthog.com"Or set it globally with |
🤖 CI report
|
| Project | Preview | Updated (UTC) |
|---|---|---|
| posthog.com | Open preview | Jul 22, 2026, 9:55 PM |
The preview should be ready in about 10 minutes. Open the preview at /handbook/engineering/.
|
|
Note 🤖 stamphog reviewed Greptile's concern is confirmed by reading the source: posthog/clickhouse/metrics/metric_events.py:20 explicitly points readers to docs/internal/metrics for context, and this PR deletes that directory entirely without updating the comment, leaving a dangling reference the author's own grep should have caught.
Gate mechanics and policy version
|
The design docs deleted in this PR were the target of a "See docs/internal/metrics for the history" pointer in metric_events.py. The comment above it already explains the fingerprint/dedup design, so remove the now-dangling reference rather than repoint it. Generated-By: PostHog Code Task-Id: 2bbfdaa6-874f-4759-952a-30409e069fec
![stamphog[bot]](https://avatars.githubusercontent.com/in/3000332?s=60&v=4){kind=small}
There was a problem hiding this comment.
Doc-only deletion plus a one-line comment edit removing the now-dangling reference to the deleted docs — the diff already addresses Greptile's flagged concern about the broken path. No risky territory, author has strong familiarity with these exact files.
- Author wrote 100% of the modified lines and has 7 merged PRs in these paths (familiarity STRONG).
- 👍 on the PR from greptile-apps[bot], hex-security-app[bot].
Gate mechanics and policy version
| Gate | Result | |
|---|---|---|
| prerequisites | ✓ | all clear |
| deny-list | ✓ | no deny categories matched |
| size | ✓ | 2L, 1F substantive, 282L/3F incl. docs/generated/snapshots — within ceiling |
| tier | ✓ | T1-agent / T1c-medium (282L, 3F, two-areas, chore) |
| stamphog 2.0.0b3 | .stamphog/policy.yml @ 2f27722 · reviewed head d758108 |
|
Retaining stamphog approval — delta since last review classified as |
1 participant
Problem
The metrics product had two internal design docs checked into the repo at
docs/internal/metrics/:dashboard-mvp.mddeployment-layout.mdThese are point-in-time design and planning artifacts, not durable references. They carry a
**Status:** designheader, owner handles, an alpha-timeline framing, in-flight PR references, and status matrices that go stale the moment the work moves. One of them even links to a siblingdocs/internal/prom-compat/design.mdthat does not exist in the repo.I checked precedent before removing anything.
docs/internal/does host other per-product folders (feature-flags/,workflows/), but those are durable "how it works" architecture references describing shipped systems, which is also whatdocs/README.mdscopesinternal/to (development workflows, migration patterns, team processes). Transient design/planning docs are a different kind of thing and don't have strong precedent here. Nothing in the codebase references either file.Changes
Deleted both files. That empties
docs/internal/metrics/, so the directory goes away too. No code, docs index, or agent instructions link to them, so nothing else changes.How did you test this code?
Doc-only deletion, no runtime behavior to test. I grepped the repo (code, markdown, agent instruction files, doc indexes) for inbound references to the two files and the
internal/metricspath and found none, so removal leaves no broken links.Automatic notifications
Docs update
N/A
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Daniel asked whether keeping these in-repo metrics design docs is standard practice and, if there's no strong precedent, to remove them. I (Claude) checked the other
docs/internal/folders anddocs/README.mdto characterize what belongs there, confirmed the metrics docs are transient planning artifacts rather than durable architecture references, verified nothing links to them, then deleted both. No skills were required for a doc-only deletion.Created with PostHog Code