chore: consolidate AI-agent context into one source; fix all stale claims by rahul-mixpanel · Pull Request #1005 · mixpanel/mixpanel-android

rahul-mixpanel · 2026-08-31T14:25:40Z

Summary

Reduces per-session token cost for AI coding agents and fixes widespread factual drift in the agent context files. Two commits:

1. Consolidation (7c8f67c6)

Merged CLAUDE.md + AGENTS.md into a single canonical root AGENTS.md (router-first: context map → config → commands → principles → architecture → release), with CLAUDE.md bridging to it.
Fixed the pervasive "instrumented tests only / no unit tests" claim across 8 files (Cursor rules, Copilot instructions, CI comments). Reality: 21 JVM unit tests in src/test/ + 18 instrumented in src/androidTest/.

2. Full-code audit (a01b11ae) — verified every doc claim against source, build config, and CI:

Removed fabrications: release.sh (deleted after 8.5.1), CENTRAL_PORTAL_* credentials, publish-maven.yml, :analytics:install, mMessages.enqueueMessage(). Release docs rewritten around the real flow (prepare-release.yml → release-maven-central.yml, driven by .github/modules.json, MAVEN_CENTRAL_*/SIGNING_* secrets).
Fixed architecture claims: data flow is not a chain — AnalyticsMessages owns both MPDbAdapter and the HTTP poster, and FeatureFlagManager is a second network path with no SQLite; two HandlerThreads (not one); real runtime deps documented (gson, json-logic-java, lifecycle-process, mixpanel-android-common); MPDbAdapter is rawQuery-based (not prepared statements); ~24 public types (not "only MixpanelAPI").
Closed coverage gaps: documented the published :session-replay module family, build-logic/ convention plugins, Gradle 9.3.1, Mockito + sharedTest, per-module release registry.
Nested context files: merged the duplicated mpmetrics/ and androidTest/ AGENTS.md+CLAUDE.md pairs into one corrected AGENTS.md each (CLAUDE.md imports via @AGENTS.md), removing their invalid --tests syntax and "do not create unit tests" directive.
Root CLAUDE.md switched from symlink to @AGENTS.md import (officially preferred bridge; Windows-safe).

Net: −1,579 / +479 lines across 18 doc files. No source code changes.

Follow-up

The audit surfaced a code issue tracked separately as SDK-155: MPDbAdapter builds SQL via string concatenation, which the repo's own rules label an injection risk.

Validation

Docs-only change; every retained claim verified against file:line evidence or CI history (e.g. createDebugCoverageReport kept because CI ran it green on Aug 28).
Stale-claim sweep: grep for all removed falsehoods returns no hits outside intentional contexts.

🤖 Generated with Claude Code

…aleness Reduce per-session token cost by making the auto-loaded context a lean, accurate router instead of duplicated prose that agents must re-verify. - Merge CLAUDE.md and AGENTS.md into a single canonical AGENTS.md (router first: context map, config, commands, principles, architecture, release). CLAUDE.md is now a symlink to AGENTS.md so the two can never drift. - Fix a pervasive falsehood ("instrumented tests only / no unit tests") across the codebase map, testing-strategy, Cursor rules, Copilot instructions, and CI. The SDK actually has 21 JVM unit tests in analytics/src/test/ plus 18 instrumented tests in analytics/src/androidTest/. - Correct the codebase map: drop dead references (DecideChecker, ConnectivityReceiver, ImageStore), move HttpService to util/, and add the real current files (FeatureFlag*, DeviceIdProvider, AutomaticEvents, etc). - Fix wrong Gradle module paths in copilot-instructions (:connectedAndroidTest -> :analytics:connectedAndroidTest). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Verified every claim in the agent docs against the actual source, build config, and CI. Corrections: Fabricated/deleted things removed: - release.sh no longer exists: rewrote the release docs around the real GitHub Actions flow (prepare-release.yml -> release-maven-central.yml, driven by .github/modules.json), with the real credentials (MAVEN_CENTRAL_*/SIGNING_*, not CENTRAL_PORTAL_*). - :analytics:install task does not exist (maven-publish). - mMessages.enqueueMessage() does not exist; snippets now show the real typed-method / mWorker.runMessage() pattern. Wrong architecture claims fixed: - Data flow was documented as a chain (... -> MPDbAdapter -> HttpService). Reality: AnalyticsMessages owns both the DB adapter and the poster, and FeatureFlagManager is a second network path with no SQLite. - "Single background HandlerThread": there are two HandlerThreads plus single-thread executors. - "No external dependencies": lifecycle-process, json-logic-java, gson and mixpanel-android-common are real runtime deps -> "minimal deps" rule. - "Prepared statements": MPDbAdapter is rawQuery-based. - "MixpanelAPI is the ONLY public class": ~24 public types exist. - HTTP timeouts are hardcoded (not configurable); GZIP is opt-in. Coverage/scope fixes: - Documented the :session-replay module family and build-logic/ (absent from all docs despite being published, versioned and CI-gated). - Fixed toolchain facts (Gradle 9.3.1, session-replay compileSdk 35, demo app Java 8) and test frameworks (Mockito, sharedTest source set). - Nested mpmetrics/ and androidTest/ AGENTS.md+CLAUDE.md pairs: merged each into one corrected AGENTS.md with CLAUDE.md as an @AGENTS.md import; removed their "instrumented tests only" directives and invalid `--tests` syntax. - Root CLAUDE.md switched from symlink to @AGENTS.md import (the officially preferred bridge; Windows-safe, allows Claude-specific adds). Kept: :analytics:createDebugCoverageReport (verified real — CI ran it green on Aug 28). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

greptile-apps · 2026-08-31T14:28:49Z

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains; the previously reported invalid test-class command now targets an existing instrumented test using the configured runner syntax.

Important Files Changed

Filename	Overview
AGENTS.md	Consolidates root agent guidance and updates repository commands and architecture facts.
CLAUDE.md	Becomes the intended one-line import shim for the canonical root guidance.
analytics/src/main/java/com/mixpanel/android/mpmetrics/AGENTS.md	Corrects core SDK guidance and now references an existing instrumented test.
analytics/src/main/java/com/mixpanel/android/mpmetrics/CLAUDE.md	Imports the directory-local canonical guidance.
.claude/context/workflows/release-process.md	Rewrites release documentation around the current GitHub Actions and Central Portal flow.

_{Reviews (4): Last reviewed commit: "chore: fix four doc inaccuracies found i..." | Re-trigger Greptile}

The instrumented DB tests live in MixpanelBasicTest/PersistentIdentityTest; there is no MPDbAdapterTest. Verified every other test class named in the docs exists (incl. util/HttpServiceTest and session-replay's APICompatibilityTest). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

The 'Validate PR title' check run was created by a synchronize event that predates the title fix; reruns reuse that stale payload. A new head SHA makes all checks evaluate against the current title. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Copilot

Pull request overview

Consolidates AI-agent guidance and corrects stale architecture, testing, and release documentation.

Changes:

Makes AGENTS.md canonical, with CLAUDE.md bridges.
Documents unit and instrumented test layers.
Updates architecture, dependencies, and release workflows.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
`CLAUDE.md`	Imports canonical guidance.
`AGENTS.md`	Consolidates repository guidance.
`analytics/src/main/java/com/mixpanel/android/mpmetrics/CLAUDE.md`	Imports local guidance.
`analytics/src/main/java/com/mixpanel/android/mpmetrics/AGENTS.md`	Updates core SDK guidance.
`analytics/src/androidTest/CLAUDE.md`	Imports local test guidance.
`analytics/src/androidTest/AGENTS.md`	Revises instrumented-test guidance.
`.github/workflows/copilot-setup-steps.yml`	Corrects test-layer comment.
`.github/instructions/test-generation.instructions.md`	Documents test selection.
`.github/instructions/code-generation.instructions.md`	Corrects message dispatch example.
`.github/copilot-instructions.md`	Corrects test commands.
`.github/copilot-instructions-guide.md`	Updates testing summary.
`.cursor/rules/workflows/adding-features.mdc`	Corrects dispatch workflow.
`.cursor/rules/README.md`	Updates testing principles.
`.cursor/rules/features/testing-patterns.mdc`	Documents both test layers.
`.cursor/rules/always/architecture-principles.mdc`	Corrects network architecture.
`.claude/context/workflows/testing-strategy.md`	Updates test structure.
`.claude/context/workflows/release-process.md`	Rewrites release guidance.
`.claude/context/codebase-map.md`	Updates repository map.
`.claude/context/architecture/system-design.md`	Corrects system architecture.

Suppressed comments (2)

analytics/src/androidTest/AGENTS.md:67

These three documented TestUtils helpers do not exist. Listing them sends agents toward uncompilable test code; use the actual shared helpers instead (TestUtils.java:24-65,145-166).

- Clean state in `setUp` (TestUtils helpers: `getCleanMixpanelAPI`, `cleanDatabase`,
  `getDbAdapter`); clean up in `tearDown`/`finally`.

analytics/src/main/java/com/mixpanel/android/mpmetrics/AGENTS.md:45

Not every new public API is a queued tracking operation: accessors, configuration, and opt-in/control APIs should not all receive an opt-out guard or an AnalyticsMessages message. Narrow this recipe so agents do not force unrelated APIs through the tracking path.

**New public API method:** overload for progressive disclosure; validate + opt-out check +
try-catch in `MixpanelAPI`; hand off via an `AnalyticsMessages` typed method backed by a new
message type with an immutable description class; add tests.

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

- androidTest/AGENTS.md: replace nonexistent TestUtils.createMixpanelApiWithMockedMessages with the real capture idiom from MixpanelBasicTest (MPDbAdapter/AnalyticsMessages overrides + CleanMixpanelAPI), and fix phantom helper names (real API: cleanUpMixpanelData, EmptyPreferences, createMixpanelAPIWithMockHttpService). - mpmetrics/AGENTS.md: scope the opt-out/try-catch rule to tracking/mutating operations (accessors skip it by design; optInTracking must run while opted out). - mpmetrics/AGENTS.md: retry backoff is 100/200 ms before attempts 2-3; there is no 300 ms sleep after the final attempt (in-code comment is stale). - release-process.md: OSSRH URLs are hardcoded in MavenPublishConventionPlugin.kt; RELEASE_REPOSITORY_URL in analytics/gradle.properties is dead config. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

rahul-mixpanel and others added 2 commits August 31, 2026 19:35

greptile-apps Bot reviewed Aug 31, 2026

View reviewed changes

Comment thread analytics/src/main/java/com/mixpanel/android/mpmetrics/AGENTS.md Outdated

rahul-mixpanel mentioned this pull request Aug 31, 2026

chore: add verified AGENTS.md agent context; fix stale copilot-instructions mixpanel/mixpanel-swift#775

Draft

rahul-mixpanel changed the title ~~docs: consolidate AI-agent context into one source; fix all stale claims~~ Aug 31, 2026

rahul-mixpanel requested a balanced review from Copilot September 1, 2026 06:29

Copilot started reviewing on behalf of rahul-mixpanel September 1, 2026 06:29 View session

Copilot AI reviewed Sep 1, 2026

View reviewed changes

Comment thread analytics/src/androidTest/AGENTS.md Outdated

Comment thread analytics/src/main/java/com/mixpanel/android/mpmetrics/AGENTS.md Outdated

Comment thread .claude/context/workflows/release-process.md

Comment thread analytics/src/main/java/com/mixpanel/android/mpmetrics/AGENTS.md Outdated

Navigation Menu

Uh oh!

chore: consolidate AI-agent context into one source; fix all stale claims - #1005

chore: consolidate AI-agent context into one source; fix all stale claims#1005
rahul-mixpanel wants to merge 5 commits into
masterfrom
docs/consolidate-agent-context

rahul-mixpanel commented Aug 31, 2026

greptile-apps Bot commented Aug 31, 2026 •

edited

Loading

Important Files Changed

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Labels

2 participants

Uh oh!

Conversation

rahul-mixpanel commented Aug 31, 2026

Summary

Follow-up

Validation

greptile-apps Bot commented Aug 31, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Confidence Score: 5/5

Important Files Changed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Labels

2 participants

greptile-apps Bot commented Aug 31, 2026 •

edited

Loading