What happened
On PR #3385, the code agent (Claude Code, co-authoring with robnester-rh) introduced 3 preventable issues when modifying Kubernetes manifests in the release/ directory: (1) after removing the ServiceAccount resource from setup.yaml, the leading --- separator was left behind, creating an empty YAML document that would fail GVK resolution in apply flows; (2) the README.md in the same directory was not updated to reflect the removal of the ServiceAccount, still claiming setup.yaml creates one; (3) Role and RoleBinding resources were renamed from tenant-release to conforma-release without considering that existing clusters would retain stale RBAC objects under the old names. All 3 issues were caught by the Qodo review bot and fixed via a force-push before merge.
What could go better
The code agent lacked repo-specific context about Kubernetes manifest conventions. With explicit guidance in AGENTS.md, these issues could have been avoided in the initial commit: (1) YAML document structure awareness when removing resources from multi-document files, (2) documentation co-change requirements when release/ manifests change, and (3) migration impact analysis when Kubernetes resources are renamed. This would reduce rework iterations from 2 to 1 for this class of change.
Proposed change
Add a 'Release and Kubernetes Manifests' section to AGENTS.md with these guidelines: (1) when removing a resource from a multi-document YAML file, verify no empty documents remain between --- separators; (2) when modifying release/ manifests, always check release/README.md for stale references that need updating; (3) when renaming Kubernetes resources, prefer updating fields in-place rather than renaming, or document migration steps for existing clusters that will retain stale objects under old names.
Validation criteria
Future code agent PRs modifying release/ manifests should not introduce empty YAML documents, should proactively update release/README.md, and should consider migration implications for resource renames. Can be validated by reviewing subsequent PRs touching release/ for these issue types.
Generated by retro agent from #3385
What happened
On PR #3385, the code agent (Claude Code, co-authoring with robnester-rh) introduced 3 preventable issues when modifying Kubernetes manifests in the release/ directory: (1) after removing the ServiceAccount resource from setup.yaml, the leading --- separator was left behind, creating an empty YAML document that would fail GVK resolution in apply flows; (2) the README.md in the same directory was not updated to reflect the removal of the ServiceAccount, still claiming setup.yaml creates one; (3) Role and RoleBinding resources were renamed from tenant-release to conforma-release without considering that existing clusters would retain stale RBAC objects under the old names. All 3 issues were caught by the Qodo review bot and fixed via a force-push before merge.
What could go better
The code agent lacked repo-specific context about Kubernetes manifest conventions. With explicit guidance in AGENTS.md, these issues could have been avoided in the initial commit: (1) YAML document structure awareness when removing resources from multi-document files, (2) documentation co-change requirements when release/ manifests change, and (3) migration impact analysis when Kubernetes resources are renamed. This would reduce rework iterations from 2 to 1 for this class of change.
Proposed change
Add a 'Release and Kubernetes Manifests' section to AGENTS.md with these guidelines: (1) when removing a resource from a multi-document YAML file, verify no empty documents remain between --- separators; (2) when modifying release/ manifests, always check release/README.md for stale references that need updating; (3) when renaming Kubernetes resources, prefer updating fields in-place rather than renaming, or document migration steps for existing clusters that will retain stale objects under old names.
Validation criteria
Future code agent PRs modifying release/ manifests should not introduce empty YAML documents, should proactively update release/README.md, and should consider migration implications for resource renames. Can be validated by reviewing subsequent PRs touching release/ for these issue types.
Generated by retro agent from #3385