How to Measure and Reduce Technical Debt on a Corporate Website

Inventorying website technical debt by scanning, ranking it with an impact and effort matrix, fitting it into the maintenance plan and deciding between a rebuild and gradual improvement.
Technical summary
Technology
WordPress, PHP, PHP_CodeSniffer, PHPCompatibilityWP, Composer, npm
Topic
Technical debt inventory and prioritization
Level
Intermediate–advanced
Prerequisites
  • Access to the site’s source code and server
  • A staging environment
In this article7 sections

Corporate websites rarely crash overnight. The more common picture is this: every change takes longer than the last, every update is a little scarier, and in the end nobody wants to touch the site. This is called technical debt: shortcuts taken for speed in the past being added as interest to every maintenance task today. Below, we explain how to inventory the debt, how to rank it by impact and effort, and the thresholds for deciding “should we rebuild or improve gradually?”

Typical sources of technical debt in web projects

Technical debt isn’t the same as “bad code”. A shortcut taken deliberately and written down can be managed; a habit nobody remembers can’t. On websites, debt usually accumulates from one of these sources:

  • Runtime regression: An unsupported PHP version, old MariaDB/MySQL, custom code or plugins that only work with old PHP. It directly blocks security updates.
  • Business logic embedded in the theme: Hundreds of lines of integration code in functions.php, custom post types and shortcodes that will be lost when the theme changes.
  • Template copies: WooCommerce or plugin templates overridden in the child theme. When the parent plugin updates the template, the copy stays old; WooCommerce reports this on the System Status screen as outdated template overrides.
  • Raw HTML inside the page builder: HTML widgets, inline CSS, components copied per page. Visual editing ends; a design change is made by hand on dozens of pages.
  • Plugin pile-up: Plugins with overlapping functions, abandoned plugins or ones with expired licenses.
  • Undocumented integrations: Scripts in the server crontab nobody remembers, API keys embedded in code, FTP transfers only one person knows about.
  • Environment and process gaps: Code without version control, no test environment, manual deployments.
  • Dependency aging: Scripts dependent on an old jQuery version or jQuery Migrate, Composer and npm packages that aren’t updated.

The item that backfires most expensively in the field is usually an undocumented integration. The person who wrote the script has left. And you only realize it was running when it stops.

How to build a technical debt inventory

The inventory comes from systematic scanning, not a code review meeting. Check order: environment first, then code, then content, process last.

Environment and dependency scan

The support status of the PHP version is verified on PHP’s supported versions page. Compatibility of custom code with the target version can be scanned statically with PHP_CodeSniffer and the PHPCompatibilityWP ruleset:

# Install as a development dependency with Composer
# (Composer 2.2+ may ask for allow-plugins approval for the PHPCS installer plugin)
composer require --dev phpcompatibility/phpcompatibility-wp:"*"

# Scan the theme and custom plugins for PHP 8.2 and above
vendor/bin/phpcs -p wp-content/themes/custom-theme wp-content/plugins/custom-plugin \
  --standard=PHPCompatibilityWP --runtime-set testVersion 8.2- \
  --extensions=php --report=summary

# Aging status of package dependencies
composer outdated --direct
npm outdated

Static scanning doesn’t catch everything. For dynamic calls and warnings that appear at runtime, you need to run real scenarios with the target PHP version in the test environment and watch the error log. The migration itself is covered as a separate project in the PHP version migration plan guide.

Code and configuration scan

  • Line count, whether under version control and last modified date for the theme and custom plugins.
  • A list of template overrides in the child theme and their version difference from the parent template.
  • URLs, API keys and passwords hard-coded in the code (a simple search like grep -rn "api_key\|password\|http://" wp-content/themes is enough to start with).
  • The server crontab (crontab -l, /etc/cron.d/) and WordPress cron jobs (wp cron event list).

Content and page builder scan

The number of pages using HTML widgets, inline styles and custom shortcodes is counted. Since Elementor stores page data as JSON in the _elementor_data meta field, the widget type can be searched for in this field. The query below gives the number of posts and templates containing an HTML widget (adjust the table prefix according to the wp db prefix output; the result may also count revisions):

wp db query 'SELECT COUNT(DISTINCT post_id) FROM wp_postmeta
  WHERE meta_key = "_elementor_data"
  AND meta_value LIKE "%\"widgetType\":\"html\"%";'

This number is the answer to “how many pages does a design change touch?” It’s also the first figure to show management.

Process scan

Version control, test environment, backup restore testing, deployment method and documentation are recorded as yes/no. A process gap isn’t a code problem on its own; but it makes paying off all other debt more expensive. Without a test environment, every fix is made on the live site.

Prioritizing with an impact and effort matrix

Each item in the inventory is scored on two axes. Impact is the risk and friction the item creates today: a vulnerability, a blocked update, performance loss, longer change times. Effort is the amount of work and risk in closing the item. A 1–3 scale is enough for most teams; the goal isn’t precise calculation but moving the discussion into a common language.

Example item Impact Effort Decision
Unsupported PHP version High Intermediate Plan immediately
API key embedded in code High Low Do immediately
Old WooCommerce template copies Intermediate Low Do immediately
Abandoned form plugin High Intermediate Plan immediately
Pages built with HTML widgets Intermediate High Gradually, combined with a redesign
Undocumented cron script Intermediate Low Document, then assess
Unused custom post type Low Low When the opportunity arises

The four zones read like this: high impact and low effort is “do immediately”; high impact and high effort is “plan as a project”; low impact and low effort is “do it when that area is touched”; low impact and high effort is “accept deliberately and record”. Don’t underestimate the last group. Not every debt needs paying off; but its acceptance should be in writing so it isn’t reopened at every meeting.

Items that block security and updates are moved forward regardless of the matrix. A single plugin dependent on an unsupported PHP version can stop every other component on the site from being updated. That’s the knock-on effect.

Fitting debt reduction work into the maintenance plan

Debt rarely goes down while waiting for a separate “cleanup project”; that project is always postponed in favor of new feature requests. The method that works is making debt reduction a fixed part of regular maintenance:

  • Fixed capacity: A set block of maintenance hours each month is allocated to debt items. It isn’t moved to other work except for emergencies.
  • Fix where you touch: When a page or component is opened for a new request, small debt items in that area are closed in the same piece of work.
  • Recording new debt: Shortcuts taken deliberately because of a deadline are written into the inventory the same day; “we’ll fix it later” doesn’t stay verbal.
  • Quarterly review: The inventory is re-scored, closed items are marked and new ones are added.

How debt reduction is reflected in the maintenance contract, along with scope and priority definitions, is explained in the SLA in a web maintenance contract article. To weed out plugin-related debt, the plugin inventory and safe removal guide can be applied directly.

Rewrite or gradual improvement

As debt grows, the suggestion “let’s start from scratch” becomes tempting. Sometimes it’s the right decision. But it requires rediscovering the implicit requirements the old site has accumulated over the years (redirects, form integrations, custom fields, URLs with SEO value); each one not discovered comes back as a failure on the new site. These thresholds can be used for the decision:

Status Gradual improvement Rebuild
Core and plugins can be updated Suitable Not required
The runtime can’t be moved to a supported version Difficult Strong candidate
Design changes are made by hand, page by page Component-by-component conversion Suitable if combined with a redesign
Business logic is scattered across theme files Move it into a plugin first Suitable if the architecture is changing
Information architecture and content will also change Limited benefit Suitable

A common pattern in gradual improvement is to build new components alongside the old ones and move traffic to the new ones step by step: first templates and global styles, then the page groups that change most often, and last the pages that are rarely touched. Each step should be releasable and reversible on its own. A step that can’t be reversed isn’t gradual.

When a rebuild is chosen, the biggest risk is a drop in search visibility from URL and content loss; the redirect and verification steps in the preventing SEO loss during migration guide should be part of the plan. If a platform change is also on the table, the WordPress vs Next.js comparison gives an additional decision framework.

Technical debt assessment checklist

  • PHP, database and web server versions were checked against the support schedule.
  • Custom themes and plugins are under version control; the person who made the last change is known.
  • A PHP compatibility scan was run for the target version and the results were recorded.
  • Template overrides were listed, and version differences from the parent template were noted.
  • Secrets embedded in code (keys, passwords) were identified; moving them to environment variables or a configuration file was planned.
  • Server and WordPress cron jobs were documented.
  • The number of pages using HTML widgets and inline styles was counted.
  • Each item was scored by impact and effort; accepted debt was recorded with its rationale.
  • Fixed capacity was set aside for debt reduction in the maintenance plan.
  • If a rebuild is being considered, the URL inventory and redirect plan are ready.

When the inventory leads to a modernization decision, the legacy website modernization service explains the relevant scope; when reducing debt within regular maintenance is preferred, the website maintenance and support contracts page does.

Frequently asked questions

Is technical debt always bad?

No. A shortcut taken deliberately for a deadline and recorded is a reasonable decision. The problem is debt that isn’t documented and accumulates without a repayment plan. Some low-impact debt can be deliberately accepted and never paid off.

How can I explain technical debt to management?

Write the items in terms of business outcomes, not technical terms: updates that can’t be done, vulnerabilities that can’t be closed, how many days a change takes. The impact and effort matrix makes it easier to show visually which work comes first and why.

Does rebuilding the site from scratch reset technical debt?

In the short term it closes many items; but if the implicit requirements in the old site aren’t discovered, new problems arise. If the inventory, maintenance rhythm and record-keeping discipline aren’t set up on the new site, debt accumulates again.

Is a PHP compatibility scan enough on its own?

No. PHPCompatibility does static analysis; it may not catch dynamic calls and runtime warnings. Complete the scan by running real usage scenarios with the target PHP version in the test environment and watching the error log.

Support

Contact us for support or a discovery session on this topic.

Contact form
[email protected]

Eretek Web

We build and maintain corporate websites, WordPress and CMS platforms, intranet and SharePoint portals, document management, and form and approval workflows, and keep them secure and up to date.

Knowledge Center

Other articles