What happened
On PR #6611, commit 662eacc introduced TRIGGER_ENTITY_URL as a new env-var name. Human reviewer waynesun09 identified that docs/normative/normalized-event/v1/jira-poll-adapter.md already defines FULLSEND_WORK_ITEM_URL as the canonical name for entity.url with MUST-level language. The review agent caught the surface-level title/code mismatch (renaming from TRIGGER_ENTITY_URL to match the title) but did not discover the normative spec, missing the deeper spec-compliance issue.
What could go better
The AGENTS.md topic-specific guidance table has entries for 'Workflow Contracts' and 'CI Workflows' but no entry directing reviewers to docs/normative/ when adding or renaming env variables in dispatch workflows. The review agent reads AGENTS.md-referenced guides during review, so adding this pointer would give it the context to check for existing canonical names before accepting a new variable name. This complements existing issue #3285 (review agent should cross-reference governance docs), which proposes the broader agent behavior change — this proposal is an interim repo-specific fix that makes the normative spec discoverable without waiting for the agent-layer improvement. Moderate confidence: the agent would still need to reason from the spec to the variable name, but having the spec in its context window is a prerequisite.
Proposed change
Add a row to the topic-specific guidance table in AGENTS.md:
| [Normalized Event Spec](docs/normative/normalized-event/v1/README.md) | Adding or renaming environment variables in dispatch workflows, or changing how event data is projected to agent runtime — covers canonical env-var names (`FULLSEND_WORK_ITEM_*`) and payload projection rules |
Also add an inline comment in reusable-dispatch.yml near the first FULLSEND_WORK_ITEM_URL env entry:
# Env-var naming: canonical names for dispatch-projected variables are
# defined in docs/normative/normalized-event/v1/ (jira-poll-adapter.md).
# Check the normative spec before introducing new variable names.
Validation criteria
On the next 3 PRs that add or rename an env variable in dispatch workflows, check the review agent's transcript (tool calls in the fullsend-review artifact) for evidence it read docs/normative/. If the agent reads it and identifies spec-compliance issues, the gap is closed. If it reads it but fails to connect the spec to the variable names, the agent-layer fix (#3285) is needed.
Generated by retro agent from #6611
What happened
On PR #6611, commit 662eacc introduced
TRIGGER_ENTITY_URLas a new env-var name. Human reviewer waynesun09 identified thatdocs/normative/normalized-event/v1/jira-poll-adapter.mdalready definesFULLSEND_WORK_ITEM_URLas the canonical name forentity.urlwith MUST-level language. The review agent caught the surface-level title/code mismatch (renaming from TRIGGER_ENTITY_URL to match the title) but did not discover the normative spec, missing the deeper spec-compliance issue.What could go better
The AGENTS.md topic-specific guidance table has entries for 'Workflow Contracts' and 'CI Workflows' but no entry directing reviewers to
docs/normative/when adding or renaming env variables in dispatch workflows. The review agent reads AGENTS.md-referenced guides during review, so adding this pointer would give it the context to check for existing canonical names before accepting a new variable name. This complements existing issue #3285 (review agent should cross-reference governance docs), which proposes the broader agent behavior change — this proposal is an interim repo-specific fix that makes the normative spec discoverable without waiting for the agent-layer improvement. Moderate confidence: the agent would still need to reason from the spec to the variable name, but having the spec in its context window is a prerequisite.Proposed change
Add a row to the topic-specific guidance table in
AGENTS.md:Also add an inline comment in
reusable-dispatch.ymlnear the firstFULLSEND_WORK_ITEM_URLenv entry:Validation criteria
On the next 3 PRs that add or rename an env variable in dispatch workflows, check the review agent's transcript (tool calls in the fullsend-review artifact) for evidence it read
docs/normative/. If the agent reads it and identifies spec-compliance issues, the gap is closed. If it reads it but fails to connect the spec to the variable names, the agent-layer fix (#3285) is needed.Generated by retro agent from #6611