=== Ravnsight Detective – Diagnose Errors & Changes ===
Contributors: pihlfelt
Tags: error monitoring, change tracking, troubleshooting, diagnostics, woocommerce
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.1
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Site broke after an update? See the PHP error, the plugin behind it, and every change on one timeline — not just that something broke.

== Description ==

When a WordPress site breaks, the question is never just "what is the error?" — it is "**what changed right before it started?**". Ravnsight Detective answers both, locally, on your own site:

* **Error Detective** — catches PHP warnings, deprecations and fatal errors, groups identical errors into one row (a hundred thousand repeats is one line, not a flooded log), and attributes each one to the **plugin, theme or core** that caused it.
* **Change Detective** — records every plugin/theme/core install, update, activation and switch, changes to important options, and takes a daily environment snapshot so even manual FTP changes and host-side PHP upgrades are noticed.
* **Timeline** — errors and changes on one axis. The debut of an error right after an update stops being a mystery.
* **Investigation Mode** — name the problem ("slow", "white screen", "broke after an update") and get the most probable cause, its evidence, a confidence level, and a safe test to confirm it.
* **Spike detection** — a dashboard warning when the last 24 hours carry more errors than the rest of the week.

Everything is stored in your own database and pruned automatically. Sensitive data (e-mail addresses, phone numbers, card-like numbers, query-string values, full server paths) is redacted **before** it is stored.

= What Detective checks for =

Detective is a suite of local detectors. Each can be turned on or off in settings. In plain terms, this is exactly what they look for:

* **Error Detective** — PHP fatal errors, warnings and deprecation notices, database (SQL) errors, and failed e-mail sends (`wp_mail`). Identical errors are grouped into one row and attributed to the plugin, theme or core responsible.
* **Change Detective** — every plugin/theme/core install, update, activation, deactivation, switch or removal; direct edits to theme files; the WordPress, PHP and database versions; changes to important options and constants; and a daily environment snapshot so even manual FTP changes and host-side upgrades are caught.
* **JavaScript Detective** — real front-end JavaScript errors happening in your visitors' browsers (opt-in), attributed to the responsible script, so a broken block editor or checkout script does not stay invisible.
* **Performance Detective** — slow front-end requests, slow database queries, the same query run many times on one page (duplicated queries), and requests that use too much memory.
* **Database Detective** — crashed or corrupt database tables (via CHECK TABLE), tables that are very large or grew unusually fast since yesterday, and orphaned data (e.g. postmeta whose post was deleted). Detection only — it never modifies your database.
* **Mail Detective** — outgoing e-mails that fail to send, so a broken SMTP setup or a mail plugin regression surfaces before customers report missing receipts.
* **WooCommerce Detective** — checkout and payment-gateway errors, failed orders, failed WooCommerce webhooks, outdated WooCommerce template overrides in your theme, and stock inconsistencies. No customer personal data is stored.
* **Cron Detective** — WP-cron overdue or stalled (scheduled tasks not running), Action Scheduler failed actions and past-due backlog, and individual scheduled jobs caught throwing errors on a supervised test run.
* **Health Detective** — PHP errors being shown to visitors in production (leaking paths), a broken WP-cron configuration, an object cache drop-in whose backend (Redis/Memcached) is unreachable, a PHP version at or near end-of-life, autoloaded options that have grown too large, and scheduled posts that missed their publish time.
* **HTTP Detective** — broken internal links (404s reached from your own pages), critical pages down (home/shop/cart/checkout/account returning a 5xx, timing out, or rendering blank), redirect loops on those pages, mixed content (an https page loading http:// resources), and outbound HTTP calls from your site that are slow, failing or being rejected.
* **Abuse Detective** — sudden spikes in pending comments (spam floods) and in new user registrations (bot signups). Detection only.

Beyond the detectors:

* **Investigation Mode** — start from the problem, not the log. Pick "Something broke after an update", "A page is slow", or "Error or white screen", and Detective proposes the most probable cause with its evidence and an honest confidence level, then offers a safe test to confirm it. Export the finding as Markdown or JSON.
* **Timeline & likely cause** — every error and every change on one axis, with an automatic "likely cause" that ties an error that just appeared to the change that landed just before it. Confidence is shown as LOW/MEDIUM/HIGH — never a made-up percentage, and never the word "caused" unless an isolation test actually reproduced it.
* **Isolation testing** — safely test the site *without* a suspect plugin, or with the default theme, for your own admin session only and in memory only. Visitors always see the site exactly as normal, sessions never touch the database, expire after 60 minutes, and can always be ended instantly. Bisect one plugin at a time to pin down the culprit.
* **Spike detection** — a dashboard warning when the last 24 hours carry more errors than the rest of the week combined.

= Privacy =

The free plugin makes **no external requests on its own** — no phone-home, no tracking, no automatic telemetry. The **only** thing it can send is an anonymized *resolution outcome*, and **only** when you explicitly opt in (see External Services below). All error and change data always stays in your database.

== Installation ==

1. Install from **Plugins → Add New** in wp-admin (search for "Ravnsight Detective"), or upload the `ravnsight-detective` folder to `/wp-content/plugins/`.
2. Activate **Ravnsight Detective** through the **Plugins** menu.
3. Open **Detective** in the admin menu. Every detector is on by default; turn any of them on or off under **Detective → Settings**.
4. That's it — everything runs locally, with no account and no external requests. To add outside-in uptime monitoring and alerts (e-mail, SMS, Slack, Teams, Telegram, webhook), connect the site to Ravnsight (Pro) from **Detective → Settings**.

== Frequently Asked Questions ==

= How do I find which plugin caused a fatal error? =

Error Detective catches each PHP fatal error, warning and deprecation and attributes it to the exact plugin, theme or core file it originates from — so instead of a wall of log text you see "this error comes from Plugin X". Identical errors are grouped into a single row.

= My WordPress site broke after a plugin (or core) update — how do I find out why? =

Open the Timeline: your errors and every plugin/theme/core update, activation and option change sit on one axis. When a fatal error first appears right after an update, the cause stops being a guess. Investigation Mode takes it further — pick "Something broke after an update" and Detective proposes the most probable cause with its evidence, a confidence level, and a safe isolation test to confirm it.

= Does it work with WooCommerce? =

Yes. WooCommerce Detective surfaces checkout and payment-gateway errors, failed orders, failed WooCommerce webhooks, outdated template overrides in your theme, and stock inconsistencies — so a broken checkout does not stay invisible while the homepage still loads. No customer personal data is stored.

= Can it monitor my site from the outside, or alert me when it goes down? =

The free plugin works locally, inside WordPress. Connect it to Ravnsight (Pro) to add outside-in monitoring: uptime/SSL/domain/DNS/API checks from EU locations (a failure is confirmed from a second country before it alerts you), alerts by e-mail, SMS, Slack, Teams, Telegram or webhook, synthetic checkout flows in a real browser, and — the point — your outages lined up with the internal changes and errors that explain them.

= Does this plugin send any data anywhere? =

Not unless you ask it to. By default the free version performs no external requests and everything stays in your database. If — and only if — you tick "share this outcome" when you mark an issue resolved (or turn on sharing in settings), it sends one anonymized resolution outcome to ravnsight.com to improve error diagnosis for everyone. See "External Services" below for exactly what that contains.

= Will it slow down my site? =

The error handler only does work when an error actually occurs, and repeated identical errors are a single database update. Change recording runs on admin actions, not on visitor requests.

= How long is history kept? =

Up to 7 days locally (configurable), pruned daily. Connect to Ravnsight (Pro) to keep up to 90 days of history on-site, plus 13 months on the platform with uptime and incident history.

= Can it fix the errors it finds? =

No, by design. Detective observes, groups and attributes — it never changes your site, never auto-updates anything and never "optimises" anything.

== External Services ==

This plugin can connect to one external service, and only on your explicit action:

**Ravnsight resolution learning** (https://ravnsight.com) — when you mark a recorded issue as resolved and tick "share this outcome" (or enable outcome sharing in the settings), the plugin sends a single, anonymized *resolution outcome* to `https://ravnsight.com/api/v1/telemetry/resolution`. This helps improve how errors are diagnosed and attributed for all users.

* **What is sent:** the error's *type* and severity (for example a PHP fatal or a deprecation — the category, never the error message text), the diagnosis confidence level, which plugin/theme/core was suspected versus the one that actually resolved it and its version (for example "woocommerce 3.2.1"), the fix type (deactivated / updated / rolled back / a config change / other), and the outcome (resolved / wrong track). This is what lets shared outcomes improve diagnosis — the error *category* plus the component and version, not the raw message. It does NOT include your site URL, domain, account, IP, any user data, or the raw error messages.
* **When:** only at the moment you explicitly share a resolved issue. Never automatically, never in the background.
* **Nothing else is transmitted** by the free plugin.

Service terms and privacy policy: https://ravnsight.com/integritetspolicy

== Screenshots ==

1. Dashboard — fatal errors, errors and changes at a glance, with the components generating the most errors attributed to the exact plugin, theme or core.
2. Timeline — every error and every change on one axis, so an error that appears right after an update stops being a mystery.
3. Investigation Mode — start from the problem ("something broke after an update", "a page is slow", "checkout is failing") and get the most probable cause with its evidence and a safe test to confirm it.
4. Settings — turn each of the eleven detectors on or off. Nothing leaves your site unless you explicitly opt in.
5. Connect to Ravnsight (Pro) — add outside-in uptime monitoring and alerts, lined up with the internal change or error that explains an outage.

== Changelog ==


= 1.0.0 =
* First public release. Local WordPress diagnostics: Error, Change, JavaScript, Performance, Database, Mail, WooCommerce, Cron, Health, HTTP and Abuse detectors; the timeline; Investigation Mode (start from the problem, get the likely cause with evidence and a confidence level, confirm with a safe test); isolation testing. Optional cloud connection (Pro) adds outside-in monitoring from a second country, alerts (e-mail, SMS, Slack, Teams, Discord, Telegram, webhook), the Ravnsight AI analysis on your dashboard, safe updates with rollback and on-site backup/restore.

