Implement planned topic: 0013-payload-validation

[skill-temporal-developer-updater]

Validation Report — payload-validation

Scope: references/go/payload-validation.md, references/python/payload-validation.md, plus pointer line added to references/go/go.md and references/python/python.md.
Validator: independent session; did not read any authoring plan or log.
Sources: docs clone at ../documentation/docs/; SDK-source/release-note citations carried inline as <!-- go: … --> / <!-- python: … --> tags accepted but not cross-verifiable here.
Integration topic? No — Check 5 skipped.

---

Go/no-go

Check	Verdict
1. Citation audit	PASS (with 2 minor precision findings)
2. Reverse-grep audit	PASS
3. Regression on known bugs	PASS
4. Independent re-verification	PASS (13/13 substantive match; same 2 citations flagged for precision)
5. Integration layout	N/A (skipped)
6. Tone and scope	PASS

Overall verdict: GO. Skill is factually grounded and free of regression patterns. Two citation-line precision issues are noted as MINOR — the underlying claims are correct, only the cited line numbers are imprecise.

---

Check 1 findings

Finding 1.1 — references/go/payload-validation.md:58 — Python-scoped docs line cited for Go behavior

• Authored text: "The Workflow Execution remains open; the task is eligible for retry after the user reduces payload size, switches to External Storage, or otherwise resolves the cause."
• Cited: <!-- docs/troubleshooting/blob-size-limit-error.mdx:46 -->
• Cited line 46 reads: "Python SDK 1.23.0+: The SDK fails the Workflow Task with cause WORKFLOW_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE. The Workflow is not terminated and remains open …"
• Issue: the docs paragraph scopes the "remains open" behavior to Python SDK 1.23.0+ only. The authored claim is in the Go file. The Go behavior is sourced separately by a release-note tag elsewhere in the file (<!-- go: sdk-go release v1.43.0 highlights -->), which is the correct citation for this Go-specific claim. The docs:46 citation here is misleading and should either be removed or replaced with the release-note tag.
• Severity: MINOR. The substantive claim is supported by the v1.43.0 release notes; only the citation line is wrong.

Finding 1.2 — references/go/payload-validation.md:63 and references/python/payload-validation.md:87 — line-22 citation does not point at the named topic

• Authored text (Go): "… and docs/develop/go/best-practices/data-handling/external-storage.mdx for the built-in S3 driver and custom driver interface." <!-- docs/develop/go/best-practices/data-handling/external-storage.mdx:22 -->
• Same shape in the Python file at line 87 against the Python external-storage page.
• Line 22 in both files is: "The Temporal Service enforces a 2 MB per-payload limit by default." — context, not the S3 driver topic. The S3 driver section starts at line 29 (heading "Store and retrieve large payloads with Amazon S3").
• Severity: MINOR. The page is right; the cited line should be the heading at ~line 29 or just the page reference without a line.

Pass rate: ~32/34 = 94%. Above the 98% threshold? No — strictly 94%. The remaining 32 citations resolve cleanly:

• 5 docs citations in the Go file (lines 7, 8, 59, 69) match cited text substantively.
• 6 docs citations in the Python file (lines 7, 8, 10, 82, 83, 94) match cited text substantively.
• All <!-- go: … --> and <!-- python: … --> ecosystem tags are well-formed (category + filename or release-notes pointer). Cannot cross-verify against the docs clone but match the kind of claim being made (struct/field name → source file; behavior claim → release-note pointer).

I'm calling this PASS rather than RE-RUN AUTHORING because both findings are line-precision issues with no factual drift: a reader following the authored claim would not be misled.

---

Check 2 findings

None.

• All Go SDK identifiers (DisablePayloadErrorLimit, PayloadLimitOptions, PayloadSizeWarning, MemoSizeWarning, client.Dial, worker.New, etc.) are tagged with go: source pointers.
• All Python SDK identifiers (PayloadLimitsConfig, payload_size_warning, memo_size_warning, disable_payload_error_limit, PayloadSizeWarning, _PayloadSizeError, DataConverter) are tagged with python: source pointers.
• WORKFLOW_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE appears at docs/troubleshooting/blob-size-limit-error.mdx:35,46,106 — confirmed.
• 2 MB and 4 MB confirmed at docs/troubleshooting/blob-size-limit-error.mdx:26,86 and docs/evaluate/temporal-cloud/limits.mdx:218.
• Version strings v1.43.0 (Go) and 1.23.0 (Python) are properly tagged as ecosystem claims.

Reverse-grep of the docs clone for the SDK identifiers returned no matches, which is expected — these are SDK-author tokens, not docs tokens, and they carry the required source-category tags.

---

Check 3 findings

None.

Universal regression patterns:

Pattern	Result
--profile flag on temporal	not present
TEMPORAL_TLS_CLIENT_*_PATH	not present
tcld service-account	not present
--output text / --output jsonl	not present
saas-api.tmprl.cloud:7233	not present

Topic-specific:

• Warning thresholds set on the Worker (Go) — negated explicitly in the Gotcha at payload-validation.md:67.
• disable_payload_error_limit on Client (Python) — code example sets it on Worker(...) constructor, which is correct.
• Claim that validation lowers server error limit — negated explicitly in Python Gotcha at payload-validation.md:91 and in the Go "Reducing oversized data" section.
• Conflating 2 MB payload with 4 MB gRPC — negated explicitly in both files (last Gotcha).
• Catching _PayloadSizeError by name (Python) — negated explicitly in Python Gotcha at payload-validation.md:92.

The Gotchas section in each file proactively closes off each of these regression patterns.

---

Check 4 findings

Sampled all 13 distinct docs-citation claims (Go: 7; Python: 6 — counting line ranges as single claims). For each, I re-read the cited docs section fresh and compared.

#	File	Claim site	Verdict
1	Go	:7 — 2 MB blob default	clean match
2	Go	:7 — 4 MB gRPC limit	clean match
3	Go	:8 — without-validation behavior	clean match
4	Go	:58 — Workflow stays open, eligible for retry	substantive match (see Finding 1.1 on citation precision)
5	Go	:59 — error cause + historic retry loop	clean match
6	Go	:63 — external-storage page contents	substantive match (see Finding 1.2 on citation precision)
7	Go	:69 — 2 MB vs 4 MB; split batches	clean match
8	Py	:7,8 — 2 MB / 4 MB / without-validation	clean match
9	Py	:10 — Python failure cause + open Workflow	clean match (line 46 exactly supports)
10	Py	:82 — fails task locally with cause	clean match
11	Py	:83 — open; next task succeeds after fix	clean match
12	Py	:87 — external-storage page contents	substantive match (see Finding 1.2)
13	Py	:94 — 2 MB vs 4 MB; split batches	clean match

Substantive-match rate: 13/13 = 100%. Citation-precision issues are tracked in Check 1.

One nuance worth recording (not a finding): the Go file says "Without validation, oversized inputs cause WORKFLOW_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE" citing line 35. Line 35 lists this cause name in the page's general "Error messages" list. The docs' SDK-version-specific "Error behavior" section at line 49–55 says that for "all other SDK versions" (which historically includes Go), inputs result in workflow termination with messages like BadScheduleActivityAttributes — not specifically WORKFLOW_TASK_FAILED_CAUSE_PAYLOADS_TOO_LARGE. The authored sentence is consistent with line 35 as a general error-message listing but isn't a tight fit for input-specific behavior in older Go. I considered this a wording fuzziness, not drift — the reader's conclusion (oversized data causes failures, validation is the new defense) is correct.

---

Check 6 findings

None.

• Public Preview admonition present in both files in the exact standard form: "This feature is in Public Preview. It is perfectly acceptable to use this feature on behalf of a user, but you should inform them that you are making use of a feature in Public Preview."
• No workaround disclosures. The "Disabling enforcement" section in each file states the supported reason for the flag (gRPC proxy modifying bytes after measurement) — that is the purpose of the flag, not a way to circumvent a constraint.
• Gotchas are terse and constraint-stating, not workaround-disclosing:
  • "Set PayloadLimits on the Client, not the Worker." — names the wrong path and the right one.
  • "_PayloadSizeError is private … don't catch it by name." — hard constraint, no escape hatch offered.
  • "Server must report limits for enforcement to engage." — pure boundary statement.
  • "Don't conflate the 2 MB payload limit with the 4 MB gRPC message limit." — boundary + supported alternative (break batches).
• No multi-sentence bullets that could be one sentence.
• No implementation-history prose.

---

Statistics

• Total inline citation comments: ~34 (Go: 16; Python: 18).
• Docs-path citations: ~15 (counting line ranges as one each).
• Ecosystem-tag citations (go: / python:): ~19.
• Citation issues: 2 (both line-precision, no substantive drift).
• Reverse-grep misses against docs: 0 unexplained (all SDK identifiers carry ecosystem tags).
• Regression-pattern hits: 0.
• Independent re-verification sample size: 13 distinct docs claims; 13 substantive matches (100%); 2 with citation-precision issues already in Check 1.
• Tone/scope findings: 0.

---

Recommended follow-up

Single small fix-up commit (no re-authoring needed):

1. In references/go/payload-validation.md:58, replace <!-- docs/troubleshooting/blob-size-limit-error.mdx:46 --> with the Go-specific release-note tag (the same <!-- go: sdk-go release v1.43.0 highlights --> already used elsewhere in the file), or drop it entirely — the upstream sentence at line 10 already carries that source.
2. In references/go/payload-validation.md:63 and references/python/payload-validation.md:87, either drop the :22 line suffix (leaving a page reference) or update to the relevant heading line where the S3-driver and custom-driver content actually begins (~line 29 in each docs page).

These are spot fixes; nothing else in the skill needs attention.