Redirect, canonical and 404 hygiene

Paste into any coding agent: Claude Code, Cursor, Codex, Copilot, Windsurf or Cline.

# Redirect, canonical and 404 hygiene

Every extra redirect hop, page that returns 200 for a missing item, and old URL that dead-ends wastes crawl budget and visitor trust on the production site. Clean up how the site answers for URLs it does not serve, so every URL either works, redirects once to the right place, or says clearly that it is gone.

Site: not given. Find the production URL in the project config, or ask me.

## Ground rules

1. Read before you write. Explore the parts of the codebase this job touches and tell me what is already in place.
2. Plan, then stop. Give me a numbered plan: what you will change, in which files, and why. Wait for my approval before editing anything.
3. Fix things at their source (the shared layout, the config, the generator), not with one-off patches page by page.
4. Keep the project's conventions: its framework APIs, file layout, naming and code style. Add no new dependency without asking.
5. Where something is already done well, say so and leave it alone.

## You will not

- Edit `.env` files, secrets or API keys, or print their values.
- Deploy, push, merge or publish anything.
- Delete data, or run migrations or scripts against a production database.
- Add tracking, third-party scripts or links to any site I did not ask for.
- Change copy, design or behaviour that this job does not need.
- Redirect missing pages to the homepage.
- Change DNS or host settings outside this repository.

## Your stack

- Framework: Work out the framework, router and build output from the project files (package.json, lockfiles, framework config) before planning, and say which you found.
- Host: Work out where the site is hosted from the config files (vercel.json, netlify.toml, wrangler config, Dockerfile, fly.toml) and say which you found.

## Steps

### 1. Map how the site answers

Find every place redirects and error statuses are decided: framework config, middleware, host config (the current host), and page code that renders a 'not found' state. List the redirects that exist, and which page types can render an empty or missing state.

### 2. One canonical host and form

Pick one host (`www` or not) and one trailing-slash form, and make every other variant redirect there in a single 301 (HTTP to HTTPS and `www` to apex in the same hop where the host allows). No redirect chains: an old URL should reach its final destination in one step.

### 3. Real status codes

- A missing item (deleted product, unknown slug, typo) must return 404 with a helpful page: search, popular links, a way home. Not a 200 page that says 'not found' (a soft 404), and not a redirect to the homepage.
- Content removed for good can return 410.
- Empty list pages that will fill later should still return 200 but carry `noindex` until they have content.
- Server errors return 500 with a friendly page, never a 200.

### 4. Old URLs

When a slug changes, record the old one and 301 it to the new one. Find renamed routes in the git history and in analytics or search data if I can share it, and add 301s for any that still get traffic or links. Keep the redirect list in one place in code.

### 5. Guard it

Add tests that an unknown slug for each dynamic page type returns 404, and that a sample of old URLs redirect once to the right place.

## Done means

- [ ] Every host and slash variant redirects to the canonical form in one hop.
- [ ] No redirect chains remain.
- [ ] Unknown items return 404 with a helpful page; nothing returns a soft 404.
- [ ] Changed slugs and renamed routes 301 to their new URLs from one redirect list.
- [ ] Tests cover 404s for each dynamic page type.

## Report back

When you finish, give me:

- what you changed, file by file;
- anything you skipped, and why;
- anything I must do by hand (DNS records, dashboards, accounts, deploys);
- how to check each change on the live site.