Plan-review pattern for static-site fixes where the deployed artifact is generated from source files (e.g. sitemap/robots/static assets). Prevents review churn by separating durable regression checks from one-time migration verification and by validating built output, not just source files.
Plan-review pattern for static-site fixes where the deployed artifact is generated from source files (e.g. sitemap/robots/static assets). Prevents review churn by separating durable regression checks from one-time migration verification and by validating built output, not just source files.
version
1.0.0
Static-site build-artifact plan review
Use when:
a website repo serves generated dist/ output from source files
the planned change edits a source artifact like sitemap.xml, robots.txt, or other static content
reviewers may challenge whether validating the source file alone is enough
Problem this solves
A recurring review failure mode is drafting a plan that only verifies the source file after edit, while production actually serves a built/copied artifact from dist/.
Another recurring failure mode is mixing:
durable regression tests that should live forever, and
one-time migration verification steps that depend on pre-edit state.
This produced repeated MAJOR plan-review findings on #2357 even though the code change itself was tiny.
Required planning pattern
1. Verify the production surface, not just the source file
If the site is deployed from built output:
identify the build path explicitly (build.js, bundler, copy step, etc.)
include validation of the built/deployed artifact (dist/...) in the plan
do not stop at "edited source file looks right"
For sitemap-style changes, include all of:
source file verification
post-build dist/... verification
if applicable, post-deploy HTTP verification
Example planning language:
source: aceengineer-website/sitemap.xml
built artifact: aceengineer-website/dist/sitemap.xml
production URL: https://www.example.com/sitemap.xml
1A. Resolve source/generated/legacy HTML contracts explicitly
For generated static sites, do not assume the only non-source surface is root *.html.
Before a plan is approval-ready, classify all HTML surfaces:
canonical source: e.g. content/**/*.html and shared partials
generated deploy output: e.g. dist/**/*.html
checked-in legacy/non-authoritative HTML outside both source and deploy output, e.g. root *.html, blog/**, calculators/**, case-studies/**, demos/**, samples/**, or other historical generated trees
Then state exactly which happens to legacy checked-in HTML:
sync it during implementation, or
declare it non-authoritative and update tests/docs/scans so it cannot create false failures or stale pass conditions.
Also inspect existing tests and docs for the old contract. If tests read root/legacy pages directly or assert old branding/content, the plan must include updating those tests. If README/deploy/architecture docs still describe root HTML as authoritative, include conditional docs updates when choosing the non-authoritative path.
1B. For brand/content cleanup, scan visible body labels too
When the task is brand identity, naming, or copy cleanup, do not limit scope to nav/footer/metadata/schema. Reviewers may find visible in-page labels that remain stale.
Approval-ready plans should specify the target contexts:
visible chrome
page titles
consumer-facing body labels/headings/CTAs
OG/Twitter metadata
JSON-LD/schema identity fields
built output equivalents
Use a precise allowlist for historical/legal prose so tests are not brittle, but do not exclude visible consumer-facing body labels by accident.
2. Split validation into two classes
Always separate:
A. Durable regression checks
These should keep running after the issue ships.
Examples:
