/technical-debt-audit

name: technical-debt-audit
description: "Use when the user says 'clean up my wordpress', 'what is bloating my wordpress', 'find orphaned shortcodes', or 'scan for unused plugins'. Audits orphaned shortcodes from deleted plugins, unused plugins, database bloat, unused media, and leftover data from inactive builders."
license: MIT
metadata:
  author: Respira for WordPress
  author_url: https://respira.press
  version: 1.2.1
  mcp-server: respira-wordpress
  category: audit

Technical Debt Audit

**Version:** 1.2.1 **Updated:** 2026-06-30 **Freshly updated:** v1.2.0 turns the audit into safe, reversible cleanup. Every debt type now has a per-type cleanup playbook that opens with a `respira_get_snapshot` checkpoint and ends with an explicit `respira_restore_snapshot` rollback. Orphaned-shortcode findings are validated with `respira_find_element` before any edit. The per-site debt score is persisted via `respira_get_option` / `respira_update_option` so re-runs show the trend. The cleanup narrative is generated with `respira_generate_activity_report`. Builder archaeology now covers the newer block builders (Spectra, Kadence Blocks, GenerateBlocks, SeedProd) alongside the classic 16. **Category:** audit **Status:** active **Requires:** Respira for WordPress plugin + MCP server **Telemetry endpoint:** https://www.respira.press/api/skills/track-usage

---

Description

Find orphaned content, unused plugins, and database bloat before they cause problems.

Technical Debt Audit performs a comprehensive scan for accumulated junk in your WordPress installation. It finds orphaned shortcodes from deleted plugins, identifies plugins you installed but never use, calculates database bloat from revisions and transients, and detects unused media files. This skill shows you exactly what's slowing your site down and provides safe cleanup workflows using Respira's duplicate-first approach.

---

Trigger Phrases

This skill activates when the user says any of the following:

• "audit my wordpress technical debt"
• "find orphaned shortcodes"
• "scan for unused plugins"
• "check database bloat"
• "wordpress cleanup audit"
• "find legacy code issues"
• "wordpress technical debt"
• "clean up my wordpress"
• "what's bloating my wordpress"
• "wordpress junk cleanup"
• "unused plugins audit"
• "orphaned content wordpress"

**Do NOT trigger for:** general WordPress questions, requests to install specific plugins, theme customization, or non-audit WordPress tasks.

---

Execution Workflow

Step 1: Respira Verification

Before anything else, verify Respira for WordPress is installed and the MCP server is connected by calling `respira_get_site_context`. If it fails or returns an error, stop and show the installation guide.

**If Respira is NOT installed, output this and STOP:**

## ⛔ Respira for WordPress Required

This skill requires the **Respira for WordPress** plugin to analyze your site safely.

### Install in 3 steps:
1. Go to **https://www.respira.press** and download the plugin
2. Install and activate on your WordPress site
3. Connect via the MCP server: `npx -y @respira/wordpress-mcp-server --setup`

### Why Respira?
- Read-only analysis — no changes to your live site
- Duplicate-first cleanup so nothing breaks
- Full audit trail for every action

Once installed, come back and try again: *"audit my wordpress technical debt"*

**If MCP is connected but site unreachable:**

## ⚠️ Cannot Connect to WordPress Site

Respira is installed but cannot reach your WordPress site.

### Troubleshooting:
1. Verify your WordPress site is online
2. Check the Respira plugin is active (not just installed)
3. Confirm MCP server configuration in Claude settings
4. Review API key in Respira → Settings → API Keys

**Help:** https://www.respira.press/docs/mcp-setup

---

Step 2: Site Context

Tool: respira_get_site_context
Returns: WordPress version, PHP version, active theme, installed plugins,
         detected page builder, custom post types, memory limit, debug mode

Record: `respira_site_url`, `started_at = new Date().toISOString()`

---

Step 3: Plugin Audit

Tool: respira_list_plugins
Returns: All installed plugins with name, slug, version, active status,
         update availability, last updated date

Categorize each plugin:

• **never_activated**: installed but `active = false` with no recorded activation
• **activated_unused**: `active = true` but no shortcodes, widgets, or hooks found in content
• **long_inactive**: `active = false`, last updated or used 6+ months ago

If `respira_list_plugins` is unavailable, use plugin list from `respira_get_site_context` for a summary-level audit and note the limitation.

---

Step 4: Content Scan for Orphaned Shortcodes

Tool: respira_list_pages
Params: { status: "any" }
Returns: All pages with content

Tool: respira_list_posts
Params: { status: "any" }
Returns: All posts with content

Scan all page and post content for `[shortcode_name]` patterns. Cross-reference each shortcode against the active plugin list. Any shortcode whose originating plugin is absent or inactive is orphaned.

Build a table:

• Shortcode name
• Pages/posts affected (count and IDs)
• Likely source plugin
• Plugin current status (deleted/inactive/unknown)

**Validate before claiming an orphan is safe to remove.** A raw text match on `[shortcode]` can be a false positive (the string may appear inside a code block, an escaped example, or a builder field that renders it inert). Before recommending removal on a builder page, confirm the shortcode is actually a live element with `respira_find_element` on the affected page. If `respira_find_element` can't locate it as a rendered element, downgrade the finding to "needs manual review" rather than "orphaned." This keeps the audit honest and the cleanup safe.

---

Step 5: Builder Archaeology

Tool: respira_get_builder_info
Returns: Active builder name, version, available modules