Repository navigation
docs: Refresh and simplify SDK agent guidance - #255
Merged
Merged
Conversation
|
[Low risk] Updates developer guidance and documentation. The documentation changes appear safe to merge. Reviews (1) · Last reviewed commit: "docs: Refresh and simplify SDK agent gui..." |
Contributor
posthog-php-fork_curl Compliance ReportDate: 2026-10-05T08:50:41.247375+00:00
|
| Test | Status | Duration |
|---|---|---|
| Format Validation.Event Has Required Fields | ✅ | 33ms |
| Format Validation.Event Has Uuid | ✅ | 527ms |
| Format Validation.Event Has Lib Properties | ✅ | 527ms |
| Format Validation.Distinct Id Is String | ✅ | 528ms |
| Format Validation.Token Is Present | ✅ | 528ms |
| Format Validation.Custom Properties Preserved | ✅ | 527ms |
| Format Validation.Event Has Timestamp | ✅ | 528ms |
| Format Validation.Non Utc Event Timestamp Is Converted To Utc | ✅ | 528ms |
| Retry Behavior.Retries On 503 | ❌ | 5532ms |
| Retry Behavior.Does Not Retry On 400 | ✅ | 2532ms |
| Retry Behavior.Does Not Retry On 401 | ✅ | 2529ms |
| Retry Behavior.Respects Retry After Header | ❌ | 5534ms |
| Retry Behavior.Implements Backoff | ❌ | 15545ms |
| Retry Behavior.Retries On 500 | ❌ | 5534ms |
| Retry Behavior.Retries On 502 | ❌ | 5534ms |
| Retry Behavior.Retries On 504 | ❌ | 5537ms |
| Retry Behavior.Max Retries Respected | ❌ | 15546ms |
| Deduplication.Generates Unique Uuids | ✅ | 535ms |
| Deduplication.Preserves Uuid On Retry | ❌ | 5533ms |
| Deduplication.Preserves Uuid And Timestamp On Retry | ❌ | 10538ms |
| Deduplication.Preserves Uuid And Timestamp On Batch Retry | ❌ | 5538ms |
| Deduplication.No Duplicate Events In Batch | ✅ | 534ms |
| Deduplication.Different Events Have Different Uuids | ✅ | 529ms |
| Compression.Sends Gzip When Enabled | ✅ | 533ms |
| Batch Format.Uses Proper Batch Structure | ✅ | 528ms |
| Batch Format.Flush With No Events Sends Nothing | ✅ | 517ms |
| Batch Format.Multiple Events Batched Together | ✅ | 519ms |
| Error Handling.Does Not Retry On 403 | ✅ | 2530ms |
| Error Handling.Does Not Retry On 413 | ✅ | 2529ms |
| Error Handling.Retries On 408 | ❌ | 5534ms |
Failures
retry_behavior.retries_on_503
Expected at least 3 requests, got 1
retry_behavior.respects_retry_after_header
Expected at least 2 requests, got 1
retry_behavior.implements_backoff
Expected at least 3 requests, got 1
retry_behavior.retries_on_500
Expected at least 2 requests, got 1
retry_behavior.retries_on_502
Expected at least 2 requests, got 1
retry_behavior.retries_on_504
Expected at least 2 requests, got 1
retry_behavior.max_retries_respected
Expected 4 requests, got 1
deduplication.preserves_uuid_on_retry
Need at least 2 requests to check retry
deduplication.preserves_uuid_and_timestamp_on_retry
Expected at least 3 requests, got 1
deduplication.preserves_uuid_and_timestamp_on_batch_retry
Expected at least 2 requests, got 1
error_handling.retries_on_408
Expected at least 2 requests, got 1
Feature_Flags Tests
✅ 17/17 tests passed
View Details
| Test | Status | Duration |
|---|---|---|
| Request Payload.Request With Person Properties Device Id | ✅ | 521ms |
| Request Payload.Flags Request Uses V2 Query Param | ✅ | 519ms |
| Request Payload.Flags Request Hits Flags Path Not Decide | ✅ | 519ms |
| Request Payload.Flags Request Omits Authorization Header | ✅ | 521ms |
| Request Payload.Token In Flags Body Matches Init | ✅ | 520ms |
| Request Payload.Groups Round Trip | ✅ | 520ms |
| Request Payload.Groups Default To Empty Object | ✅ | 519ms |
| Request Payload.Disable Geoip False Propagates As Geoip Disable False | ✅ | 520ms |
| Request Payload.Disable Geoip Omitted Defaults To False | ✅ | 520ms |
| Request Payload.Flag Keys To Evaluate Contains Only Requested Key | ✅ | 521ms |
| Request Lifecycle.No Flags Request On Init Alone | ✅ | 515ms |
| Request Lifecycle.No Flags Request On Normal Capture | ✅ | 517ms |
| Request Lifecycle.Two Flag Calls Produce Two Remote Requests | ✅ | 522ms |
| Request Lifecycle.Mock Response Value Is Returned To Caller | ✅ | 522ms |
| Retry Behavior.Retries Flags On 502 | ✅ | 623ms |
| Retry Behavior.Retries Flags On 504 | ✅ | 622ms |
| Side Effect Events.Get Feature Flag Captures Feature Flag Called Event | ✅ | 530ms |
Contributor
posthog-php-lib_curl Compliance ReportDate: 2026-10-05T08:50:52.866894+00:00 ✅ All Tests Passed!47/47 tests passed Capture Tests✅ 30/30 tests passed View Details
Feature_Flags Tests✅ 17/17 tests passed View Details
|
Contributor
posthog-php-socket Compliance ReportDate: 2026-10-05T08:51:29.517866+00:00
|
| Test | Status | Duration |
|---|---|---|
| Format Validation.Event Has Required Fields | ✅ | 28ms |
| Format Validation.Event Has Uuid | ✅ | 522ms |
| Format Validation.Event Has Lib Properties | ✅ | 523ms |
| Format Validation.Distinct Id Is String | ✅ | 524ms |
| Format Validation.Token Is Present | ✅ | 523ms |
| Format Validation.Custom Properties Preserved | ✅ | 523ms |
| Format Validation.Event Has Timestamp | ✅ | 524ms |
| Format Validation.Non Utc Event Timestamp Is Converted To Utc | ✅ | 523ms |
| Retry Behavior.Retries On 503 | ❌ | 9232ms |
| Retry Behavior.Does Not Retry On 400 | ✅ | 2529ms |
| Retry Behavior.Does Not Retry On 401 | ✅ | 2524ms |
| Retry Behavior.Respects Retry After Header | ❌ | 9230ms |
| Retry Behavior.Implements Backoff | ❌ | 18734ms |
| Retry Behavior.Retries On 500 | ❌ | 8751ms |
| Retry Behavior.Retries On 502 | ❌ | 9235ms |
| Retry Behavior.Retries On 504 | ❌ | 9236ms |
| Retry Behavior.Max Retries Respected | ❌ | 19231ms |
| Deduplication.Generates Unique Uuids | ✅ | 46ms |
| Deduplication.Preserves Uuid On Retry | ❌ | 9234ms |
| Deduplication.Preserves Uuid And Timestamp On Retry | ❌ | 14241ms |
| Deduplication.Preserves Uuid And Timestamp On Batch Retry | ❌ | 9238ms |
| Deduplication.No Duplicate Events In Batch | ✅ | 532ms |
| Deduplication.Different Events Have Different Uuids | ✅ | 525ms |
| Compression.Sends Gzip When Enabled | ✅ | 523ms |
| Batch Format.Uses Proper Batch Structure | ✅ | 524ms |
| Batch Format.Flush With No Events Sends Nothing | ✅ | 519ms |
| Batch Format.Multiple Events Batched Together | ✅ | 513ms |
| Error Handling.Does Not Retry On 403 | ✅ | 2526ms |
| Error Handling.Does Not Retry On 413 | ✅ | 2524ms |
| Error Handling.Retries On 408 | ❌ | 5530ms |
Failures
retry_behavior.retries_on_503
Expected at least 3 requests, got 1
retry_behavior.respects_retry_after_header
Expected at least 2 requests, got 1
retry_behavior.implements_backoff
Expected at least 3 requests, got 1
retry_behavior.retries_on_500
Expected at least 2 requests, got 1
retry_behavior.retries_on_502
Expected at least 2 requests, got 1
retry_behavior.retries_on_504
Expected at least 2 requests, got 1
retry_behavior.max_retries_respected
Expected 4 requests, got 1
deduplication.preserves_uuid_on_retry
Need at least 2 requests to check retry
deduplication.preserves_uuid_and_timestamp_on_retry
Expected at least 3 requests, got 1
deduplication.preserves_uuid_and_timestamp_on_batch_retry
Expected at least 2 requests, got 1
error_handling.retries_on_408
Expected at least 2 requests, got 1
Feature_Flags Tests
✅ 17/17 tests passed
View Details
| Test | Status | Duration |
|---|---|---|
| Request Payload.Request With Person Properties Device Id | ✅ | 524ms |
| Request Payload.Flags Request Uses V2 Query Param | ✅ | 521ms |
| Request Payload.Flags Request Hits Flags Path Not Decide | ✅ | 520ms |
| Request Payload.Flags Request Omits Authorization Header | ✅ | 523ms |
| Request Payload.Token In Flags Body Matches Init | ✅ | 521ms |
| Request Payload.Groups Round Trip | ✅ | 521ms |
| Request Payload.Groups Default To Empty Object | ✅ | 522ms |
| Request Payload.Disable Geoip False Propagates As Geoip Disable False | ✅ | 522ms |
| Request Payload.Disable Geoip Omitted Defaults To False | ✅ | 521ms |
| Request Payload.Flag Keys To Evaluate Contains Only Requested Key | ✅ | 523ms |
| Request Lifecycle.No Flags Request On Init Alone | ✅ | 516ms |
| Request Lifecycle.No Flags Request On Normal Capture | ✅ | 510ms |
| Request Lifecycle.Two Flag Calls Produce Two Remote Requests | ✅ | 525ms |
| Request Lifecycle.Mock Response Value Is Returned To Caller | ✅ | 523ms |
| Retry Behavior.Retries Flags On 502 | ✅ | 624ms |
| Retry Behavior.Retries Flags On 504 | ✅ | 624ms |
| Side Effect Events.Get Feature Flag Captures Feature Flag Called Event | ✅ | 523ms |
marandaneto
marked this pull request as ready for review
October 5, 2026 08:53
dustinbyrne
approved these changes
Oct 5, 2026
marandaneto
deleted the
docs/refresh-agent-instructions-20261002-133550
branch
October 5, 2026 15:17
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
💡 Motivation and Context
The agent instructions contain stale references or repeat details maintained elsewhere. Keep repository-specific safeguards and make the instructions easier to use for focused SDK changes.
Clarify the published-spec review exemption and remove duplicated contributor-guide descriptions. Use the Composer-installed PHP_CodeSniffer command with phpcs.xml and explicit PHP extensions.
💚 How did you test it?
Checked local Markdown links, exact Git path casing, anchors, code fences, whitespace, changed-file scope, and preservation of the API approval and scoped spec-review rules. SDK runtime builds and tests were not run for this documentation-only change. Autoreview was skipped because every changed file is documentation.
📝 Checklist
No SDK code changes. Runtime tests and release changesets are not needed for this documentation-only PR.
If releasing new changes
pnpm changeto generate a change intent fileNot applicable. This PR does not release SDK changes.
🤖 Agent context
Autonomy: Human-driven (agent-assisted)
Tools: Pi, Git, and GitHub CLI. The SDK-wide documentation audit used Pi subagents for implementation and independent reviews. The human driver approved the audit and simplification plan. Useful details were moved to focused local guides rather than deleted. Human review is still required. No public session link is available.