autogen-update-resource

name	autogen-update-resource
description	Use when updating an existing autogenerated (serviceapi) resource for API spec changes — typically surfaced by the "Updates auto-generated production resources (DO NOT MERGE)" bot PR or a scheduled regeneration diff, or when asked to incorporate a spec change, add a new attribute to a serviceapi resource, or follow up on an autogen visibility PR.

Update an existing autogen resource

Orchestrates incorporating an API spec change into an existing autogen resource: the regenerated code plus the complementary artifacts the regeneration does not produce. This skill owns sequencing and commands only — schema and config judgment lives in autogen-config, test conventions in acceptance-test-patterns, docs, examples, and changelog conventions in pr-and-documentation-standards.

Inputs

1. Resource name — the tools/codegen/config.yml key.
2. Spec source — default prod; otherwise a URL or already-fetched local file passed as spec_source.
3. Artifact selection — which complementary artifacts to produce. Default: all.
4. Output file (optional) — output_file, the path the run summary is written to. Non-interactive callers such as a CI workflow supply it; when it is absent the summary is presented in the session instead.

Flow

1. Understand the change
   • Read the triggering diff (visibility PR or local regeneration): which generated files changed, and which endpoint's schema gained or changed the field. Spec files often show only an x-xgen-sha bump because the spec content already landed via the internal-resources bot PR.
   • The resource, singular data source, and plural data source are generated from different endpoints — a change may appear on any combination of them. Check all three before assuming a gap.
2. Review overrides before regenerating — follow the autogen-config skill: computability and sensitive first, then collection type and descriptions, pairing every override with its upstream spec report.
3. Regenerate and build

   make autogen-update-api-spec              # prod
   make autogen-update-api-spec spec_source=<url-or-file>
   make autogen-generate-resources resource_name=<name>
   go build ./...
   

   Verify the diff only touches the expected generated files (schemas, model yaml, spec SHA), then run the post-generation schema review in autogen-config on the changed attributes.
4. Complementary artifacts, drafted from the regeneration diff (honoring the artifact selection):
   • Acceptance tests — extend the existing consolidated test rather than adding a new one; assert the new attribute on every surface that gained it, and cover the optional-attribute lifecycle, per acceptance-test-patterns.
   • Examples — wire new optional attributes through variables (e.g. default = null) rather than hardcoding values. Do not add a sibling directory unless the new attribute is a distinct user flow. Do not paste HCL into .md.tmpl.
   • Docs — make generate-doc resource_name=<name>; commit only the affected resource and data source docs.
   • Changelog — .changelog/<PR number>.txt with a release-note:enhancement block per affected resource/data source (a field landing on all three surfaces means three blocks). The filename must match the PR number — predict it from the latest issue/PR number and verify right after the PR exists.
5. Run summary — same contract as autogen-create-resource: a structured summary with Reasoning and Needs human attention sections (override choices with their upstream spec reports, test scenarios covered, skipped artifacts, possible breaking changes noticed in the diff, upstream module impact, likely resource_custom_hooks.go work — flag, never attempt). If the resource starts consuming a new API version, produce no complementary artifacts for it and flag it: surfacing that breaking change needs product and engineering input. State DO NOT MERGE prominently when the spec source is not prod; write to output_file when given, otherwise present in the session; never create the PR yourself.

Error handling

The spec-fetch, model-gen and code-gen failure modes are identical to autogen-create-resource — read its error table. Provider registration is not part of this flow, so that row does not apply. Update-specific: if the regeneration diff touches more than the target resource's generated files, stop and find out why before committing, rather than folding unrelated churn into the change.