Table of Contents
TL;DR
- Parent themes refactor between major versions. A v2.7 parent ships with a home.php that calls three helper functions. The v3.0 release moves those helpers into a hooks-and-filters extension layer and the function names go away. A child theme that overrode home.php at v2.7 silently keeps calling the dead functions and the PHP fatal error fires the first time a visitor loads the homepage after the update.
- An AI-planned child theme comes packaged with three artifacts. The minimum-viable file set (style.css with a Template header pointing to the parent’s folder, and functions.php with wp_enqueue_style declaring the parent stylesheet as a dependency). The override rationale per file. The upgrade-path note flagging which files break on v-next and which are hook-replaceable.
- Five-step setup. List the customizations needed in concrete one-sentence form. Paste the parent theme’s file tree. Name the parent theme version and grep its functions.php for do_action and apply_filters. Ask for the three artifacts together with WordPress and PHP versions stated. Test against the parent theme’s release-candidate before its GA lands.
- The chat’s training corpus knows popular parent themes (Astra, GeneratePress, Kadence, Twenty Twenty-Four, Twenty Twenty-Five) and their high-level documentation. The chat may not know your specific parent’s hook list, especially for niche or commercial themes. Read the parent’s functions.php for do_action and apply_filters before approving the chat’s plan.
- The smallest defensible child theme is two files — style.css with a Template header pointing to the parent’s folder, and functions.php with wp_enqueue_style declaring the parent stylesheet as a dependency. Everything beyond those two files is a deliberate decision and a maintenance liability the next parent update may invalidate.
The senior dev of a three-developer agency opens the parent theme’s v3 changelog on a Thursday morning. Three lines into the breaking-changes section. The parent theme has refactored the homepage template. The child theme she built three months ago overrode that template.
She traces the override. Her child theme’s home.php references three function calls that no longer exist in the parent. Two of the functions moved into a hooks-and-filters extension layer. One was renamed.
The override worked at v2.7. The override breaks at v3.0. The agency’s client site is two clicks from a hard 500 error if the parent ships now.
This piece is about the AI chat that plans child-theme overrides with the parent-theme upgrade path in mind. The chat reads three artifacts: the parent theme’s file tree, the customizations needed, and the parent theme version. The chat returns the minimum-viable file set, a per-file rationale, and an upgrade-path note for each override.
Why does a child theme decay across parent-theme updates?
Parent themes refactor.
A v2.7 parent theme ships with a home.php that calls three helper functions. The same parent theme’s v3.0 release moves those helpers into a hooks-and-filters extension layer. The function names go away. The behavior moves to a do_action('theme_homepage_intro') call.
A child theme that overrode home.php at v2.7 silently keeps calling the dead functions. The PHP fatal error fires the first time a visitor loads the homepage after the parent theme update.
Three patterns produce decay.
The override copies a template file that the parent later refactors. The original template’s helper functions go away. The override calls dead functions.
The override copies a template file that the parent later replaces with a hook-extension. The hook is the documented extension point. The file override is silent legacy that ignores the new hook.
The override touches a file that the parent later removes entirely. Block themes and full-site editing have moved many template files into block markup. The file the child theme copied no longer exists in the parent.
The pattern is universal. Parent themes are not stable interfaces — they are evolving codebases.
What does an AI-planned child theme actually contain?
Three artifacts together. The chat returns the minimum-viable file set, the override rationale, and the upgrade-path note.
The minimum-viable file set, per the WordPress child themes handbook, is two files. The style.css with the Template: header pointing to the parent theme’s folder name. The functions.php with wp_enqueue_style() declaring the parent stylesheet as a dependency.
Everything else is optional. Every additional file is a maintenance liability the next parent update may invalidate.
The override rationale names each file the chat recommends adding. Why this template file needs overriding rather than a hook. What the override changes from the parent. What the parent does not yet expose as a hook.
The upgrade-path note flags risk per file. Files where the parent’s API is stable. Files where the parent has refactored before. Files that may not exist in the parent’s next major version because of the move toward block themes.
The chat returns all three together because they reinforce each other. The minimum file set is the foundation. The rationale defends each addition. The upgrade-path note tells you what to test before the next parent update lands.
How do you set up the prompt for a minimum-viable child theme?
Five steps. None of them needs more than fifteen minutes.
Step 1 — list the customizations needed. One sentence each. The header logo color, the footer link list, the homepage intro paragraph above the post grid. Concrete, not abstract.
Step 2 — paste the parent theme’s file tree. Run tree wp-content/themes/<parent-theme-slug> -L 2 if you have shell access. Otherwise list the files visible in the WordPress Theme File Editor. The chat needs the file tree to know which override targets exist.
Step 3 — name the parent theme version and check its hook list. Open the parent theme’s functions.php and list every do_action and apply_filters call. The chat reads the hook list to recommend hook-extension over file override where possible.
Step 4 — ask for three artifacts together. The minimum-viable file set. The override rationale per file. The upgrade-path note per file. State the WordPress version and PHP version so the chat can scope to current APIs.
Step 5 — test against the parent theme’s beta release. Most reputable parent themes ship a release-candidate two weeks before the major version. Apply the child theme on a staging site against the parent’s RC. Run the front-end pages and the wp-admin Theme File Editor before the parent’s GA release lands.
tree wp-content/themes/parent-theme-slug -L 2
grep -rE 'do_action|apply_filters' wp-content/themes/parent-theme-slug
About forty-five minutes from current parent to plan-the-overrides. Longer for full-site-editing parents where most of the structure lives in block markup.
When does the AI plan miss a parent-theme-specific override?
When the parent theme exposes a hook the chat does not know about.
The chat’s training corpus contains popular parent themes — Astra, GeneratePress, Kadence, Twenty Twenty-Four, Twenty Twenty-Five — and their high-level documentation. The chat may not know your specific parent theme’s hook list, especially for niche or commercial themes.
Three gaps the AI plan may miss.
The parent theme exposes a do_action('theme_header_logo') hook that lets you replace the logo without overriding header.php. The chat recommends a header.php override because the chat’s training corpus over-represents file-override patterns. The hook approach was the right one.
The parent theme uses a block-pattern slug like parent-theme/homepage-intro that you can override by registering a child-theme pattern with the same slug. The chat may recommend a front-page.php template override that block-theme parents do not load. The override does nothing.
The parent theme’s functions.php adds a filter on the_content that injects a stylesheet. Disabling that filter from the child theme’s functions.php is two lines of remove_filter plus an add_action. The chat may recommend overriding the entire content template instead.
Read the parent theme’s functions.php for hook list before approving the chat’s plan. The chat is good at template-override patterns. The chat is less good at parent-theme-specific extension points the parent’s developer documented in their own knowledge base. The same read-the-code discipline applies to plugins via AI plugin code review before the install lands.
What can go wrong with this approach?
Three traps catch developers who already build child themes regularly.
Trap 1 — over-override. Every file copied from parent to child is a file the next parent update may invalidate. Ask the chat for the smallest override set that meets the requirement, and push back when the recommendation looks larger than necessary.
Trap 2 — hook-versus-override confusion. The chat may recommend a file override when the parent theme already exposes a hook for the change. Read the parent’s functions.php for do_action and apply_filters before accepting the file-override recommendation.
Trap 3 — missing the parent’s beta release. The parent theme ships a major version every six to twelve months. Most reputable parents ship a release-candidate two weeks before. The child theme that survives the parent update is the one tested against the RC.
Why is a child theme the smallest patch rather than a fork?
A child theme is not a fork of the parent theme.
A child theme is the smallest patch that makes the parent theme do what your site needs. Every additional file in the child theme is a maintenance liability. Every override copied from the parent is a future support ticket waiting for the parent’s next major version. The prior question of whether to swap parent A for parent B is the AI theme-switch risk audit — that piece settles the parent before this one settles the patch.
The defensible WordPress agency ships the smallest child theme it can. The parent theme is the load-bearing structure. The child theme is the renovation that does not touch the load-bearing walls.
The renovation that touches the load-bearing walls is a fork. Forks ship as their own theme, not as a child.
Other questions worth answering
How does WordPress decide which template file renders a given URL?
WordPress walks a fixed fallback chain:
- Custom page templates assigned in wp-admin.
- page-{slug}.php for that page slug.
- page-{ID}.php matching the page ID.
- page.php, then singular.php, then index.php as last resort.
The WordPress Theme Developer Handbook on page template files names this chain. Naming a child file page-about.php auto-limits it to one URL.
How do you organize version control for the customization layer?
Two repos. The customization folder lives outside wp-content/themes/, with its own git history.
WordPress.org and composer are the common upstream channels for parent themes, each with its git workflow. Mixing histories invites mistakes — a pull that overwrites your work, or a commit adding upstream files.
A deploy script copies the customization repo into wp-content/themes/
What kind of behavior belongs in a site-wide plugin file instead?
Three categories. Custom post types, tracking code, and shortcodes called from many pages — those belong in a standalone plugin file (mu-plugins/ or hand-rolled).
The reason is portability. Swap the design layer and the post types keep running. A function tied to functions.php dies when the layer changes.
As of 2026, the WordPress Theme Developer Handbook on child themes notes extensive customizations can become burdensome.
Why does the customization layer need its own documentation file?
Because the next developer who reads it needs to know what produced it.
README.md names what produced the customization, the parent name tested, and the file list with one-line reasons. CHANGELOG.md tracks each change against parent versions tested.
When v3.0 ships and a function name goes missing, the next developer finds the override to revisit. WP Beginner’s setup guide names style.css metadata fields but stops short of per-file rationale.
How small can the child theme be?
Two files, in the smallest defensible case.
The style.css with the Template: header pointing to the parent theme’s folder. The functions.php with wp_enqueue_style() declaring the parent stylesheet as a dependency. That is enough for the child theme to load and inherit the parent.
Every file you add beyond those two is a deliberate decision. A template override because the parent does not yet expose a hook for the change. A custom CSS rule because the parent’s variable does not cover your case. A remove_filter in functions.php because the parent ships a default behavior you do not want.
The defensible question is not what should I override. The defensible question is what is the smallest override that meets the requirement.
About forty-five minutes per parent if the customization list is short. Longer for full-site-editing parents where the structure lives in block markup and the override targets are different.
This piece pairs with the AI theme-switch risk audit post. The theme-switch risk audit covers the question of whether to move from parent A to parent B at all. This child-theme override plan covers the smallest customization layer once the parent is decided. Together they cover the architectural and the additive halves of the theme decision.
If you want a calm second opinion on your AI-planned child theme before the parent’s next major release, you can contact me here. Send me your parent theme name and version, the customization list, and the chat’s planned override set. I will read all three and tell you which override to test against the parent’s RC first. There is no pitch, no upsell, and the conversation is free.