Why this exists
The idea came out of a discussion among PageMotor developers: as AI agents do more of the debugging, could their findings feed a shared pool instead of evaporating? The instinct was a watercooler, a place for agents to talk. The thing that actually works is quieter than that.
Chat silts up
Free-text output from an agent is cheap to generate and expensive to triage. A channel full of it fills faster than any human, or any AI, can drain it.
Prose cannot be counted
Three people hitting one bug produce three well-written paragraphs in three threads. Nothing connects them, so the one fact that drives triage, how many, is destroyed on arrival.
Nobody signs chatter
A finding is only as useful as its provenance. Which install, which environment, which version, filed by whom? A chat message carries none of that reliably.
The fix for all three is the same move: stop exchanging conversation and start exchanging a structured report. A fixed set of fields another machine can validate, deduplicate and count. When two installs file the same finding, it should read as one finding seen twice, not two unrelated posts.
The count is the point. Triage is mostly the question “how many people does this actually hit, and where?”. A sightings count across different environments answers it in one glance. No volume of well-written prose reports can produce that number.
Does this actually run anywhere?
Yes. A working pilot exists: reports are filed as cryptographically signed events into a private channel, an indexer validates and fingerprints each one, and a board shows one row per finding with a sightings count on it. The pilot is deliberately closed while it is proven out, and it is not official PageMotor infrastructure. What is public, and useful today without any access to anything, is the report shape itself and the filing discipline around it. That is what the rest of this guide covers.
The report shape
One report is one finding, expressed as one JSON object. The spec name is pm-field-report/1. Eleven fields, three of which do the heavy lifting.
| Field | What goes in it | |
|---|---|---|
spec | required | Always pm-field-report/1. Lets a reader reject shapes it does not understand. |
category | required | One of bug, docs-gap, environment, idea. A fixed list, so filtering means something. |
severity | required | One of blocker, major, minor, note. Resist inflation: a report that cries blocker for a cosmetic nit costs you credibility on every future filing. |
title | required | One line that names the mechanism, not the symptom. The title drives deduplication, so two people describing the same fault need to converge on the same words. “Options set to zero are dropped on save” is findable next year. “Settings broke after upgrade” names your Tuesday. |
pm_core | required | The PageMotor core version the finding was reproduced on, exactly as your admin screen reports it. Every finding is anchored to a core version; it is the axis every useful question runs along. |
php | optional | PHP version, e.g. from php -v. |
plugins | optional | An object of the plugins that matter to the finding: {"slug": "version"}. Not your whole install, just the cast of this story. |
environment | optional | One line: web server, database engine, OS. This is what turns a second sighting into information, same bug on a different stack. |
repro | required* | An array of steps, not a paragraph. If a finding has no repro it is a hunch, and hunches are what silt a channel up. (*Required for bug; for an idea it may be empty.) |
expected | optional | What should have happened. |
observed | required | What did happen. The one field that must always carry weight. |
evidence | optional | The two to five lines that prove it. Not the log. The excerpt that would convince a sceptical colleague. |
A complete example
{
"spec": "pm-field-report/1",
"category": "bug",
"severity": "minor",
"title": "Options set to zero are silently dropped on save",
"pm_core": "X.Y", // the version from your admin screen
"php": "8.3.6",
"plugins": { "example-plugin": "1.2.0" },
"environment": "nginx 1.24, MySQL 8, Ubuntu 24.04",
"repro": [
"Set any numeric plugin option to 0",
"Save the settings page",
"Reload it"
],
"expected": "The option shows 0",
"observed": "The option has reverted to its default; zero was never stored",
"evidence": "Reproduced three times on a clean install; a non-zero value round-trips fine"
}How reports become findings
Every report gets a fingerprint:
sha256( category + "|" + normalised_title )Normalising strips punctuation, lowercases, and collapses runs of spaces. Reports sharing a fingerprint are one finding with several sightings. That is the entire dedupe mechanism, and it is deliberately dumb: an exact rule you can predict beats a clever one you cannot, which matters when an agent is deciding whether to file.
Note what is deliberately absent: the core version. An earlier version of this hashed the version in too, which meant the same fault reported on two different releases became two findings rather than one seen twice. That defeats the only question worth asking. The version is a property of a sighting, so it stays on the report as a filterable facet and out of what makes a finding that finding.
The honest weakness: reword the same finding and the fingerprint changes, silently, splitting one finding into two. Nothing warns you. This is why title discipline matters, and you can watch it happen yourself in the Try it live tab.
Filing one
The shape is a quarter of the job. The discipline around it is the rest, and it holds whatever the transport is: a shared channel, a forum post with a tag, or an email into a parser. Six steps, two of which are non-negotiable.
- Assemble from what was actually proved
A report describes something reproduced, not suspected. If your agent could not make the fault happen on demand, the filing is a hunch and it stays home.
- Scrub it
Everything below happens on your machine, before anything is sent anywhere. Hostnames become roles (“customer site”, “test rig”). Absolute paths become tails relative to the docroot. Keys, tokens, passwords, auth headers and credentials in URLs come out. Email addresses that are not yours come out. Evidence is cut to the few lines that prove the point.
- Check for a twin
Search wherever reports live before filing. Finding a twin is not a reason to stop: an independent sighting is the most valuable thing you can file. But it should be a choice, and your title should match the existing finding word for word so the two group.
- The human gate
Your agent shows you the exact, final payload and asks one question: send this, yes or no. A general “yes, debug this” from an hour ago does not count. No answer, no send. What the world learns about your server is your decision, never your agent’s.
- File it
On the pilot this means the payload is signed with the filing machine’s own key and published, so the report carries provable authorship. Without pilot access, the same payload posted to the PageMotor developers’ forum in a code block, under an agreed tag, is machine-readable to anyone who cares to parse it. The shape is portable on purpose.
- Confirm
Note what came back: an id, a fingerprint, any twins it grouped with. If a server-side secret scan rejects the payload, that is a bug in your scrub, not an obstacle. Fix the scrub; do not argue with the backstop.
Why the gate is absolute. A signed, published report cannot be quietly unsent, and debug output is exactly where credentials go to hide. One leaked secret inside a stack trace would end any shared reporting effort overnight. The scrub protects your sites; the gate protects everyone’s trust in the pool.
Hand this to your agent
A transport-neutral instruction block you can drop into any agent’s custom instructions or skill file. It encodes the whole contract above:
When I ask you to file a PM field report:
1. Build a JSON object with spec "pm-field-report/1" and fields:
category (bug|docs-gap|environment|idea), severity
(blocker|major|minor|note), title, pm_core, php, plugins,
environment, repro[], expected, observed, evidence.
2. Only describe what this session actually reproduced.
3. Title names the MECHANISM, not the symptom. Before writing one,
search existing reports; if a twin exists, reuse its title verbatim.
4. Scrub before showing me anything: hostnames to roles, absolute
paths to tails, strip keys/tokens/passwords/auth headers,
credentials in URLs, and email addresses that are not mine.
Evidence is 2 to 5 lines maximum.
5. Show me the exact final payload and ask: "File this report,
yes or no?" Then STOP. Do not send without an explicit yes
given after seeing the payload. Never treat earlier general
consent as approval.
6. One finding per report. Two findings, two reports, two approvals.Reading them
A pool of structured reports is only worth its keep if it answers questions faster than reading threads would. These are the questions it exists to answer.
“Is this just me?”
The first question anyone asks mid-debugging. With fingerprint grouping it is one lookup: a matching finding with sightings on other environments means it is not your server, and each sighting’s environment line tells you what the fault does and does not depend on.
“What is the new core doing to people?”
Every report is anchored to a core version, so release week reads as a filter, not a trawl. Findings sorted by sightings under the new version are a triage list that wrote itself.
“Which docs gaps keep recurring?”
The docs-gap category is quietly the highest-value one. Every entry is a place where a real person, or their agent, went looking for an answer that was not there. That is a documentation to-do list ranked by evidence.
“Same bug, or new bug?”
Two reports, one fingerprint: same finding, more evidence. Two reports, two fingerprints, similar words: possibly a rewording split. Titles that name mechanisms keep this honest; sloppy titles quietly undercount real problems.
Reading a sightings count responsibly
A count of one means little on its own: one environment, one config, one possible local quirk. The signal starts at two, because two independent machines rarely share the same local accident. And a difference between sightings is often worth more than the count itself. One sighting on MySQL and one on MariaDB tells you the database engine is not the variable. That elimination is free; nobody had to run the experiment on purpose.
Agents are readers too. The shape exists so a machine can consume it: validate, dedupe, count, summarise. An agent that checks the pool before debugging starts an hour ahead. An agent that checks it before filing keeps the pool clean. Both directions matter equally.
Try it live
Two working tools, both running entirely in this page. Nothing you type here is sent anywhere, stored anywhere, or seen by anyone.
The report builder
Fill the fields; the payload and its fingerprint assemble live. Then press Reword the title and watch the fingerprint abandon the grouping, which is the one weakness worth understanding before you file anything.
Use the version your admin screen shows.
Payload
Fingerprint
The scrub checker
Paste a candidate evidence excerpt. The same pattern families a filing pipeline should refuse are checked here, client-side: hard stops for secret shapes, warnings for things that identify you or your client.
FAQ
Is this official PageMotor infrastructure?
No. The report shape is a community convention, and the running pilot is one developer’s independent build, deliberately closed while it is proven out. Nothing here speaks for PageMotor, and nothing should depend on the pilot. Whether something like it should exist officially, and where it should live, is a decision for PageMotor, not for this guide.
Why not just use chat channels for this?
Because conversation cannot be counted. A channel of free-text agent output fills faster than anyone can triage it, and the one number that matters, how many installs a finding actually hits, never emerges from prose. Channels are excellent for humans talking. Reports are for machines counting. The two do not substitute for each other.
Why are pilot reports signed?
Provenance. A signed event proves which machine filed a report, cannot be forged in someone else’s name, and lets access be revoked per key rather than by rotating a secret that everyone shares. A report whose authorship is provable is worth strictly more than the same words without it.
Can my agent file automatically, without asking me?
It must not, and a pipeline worth trusting will treat any automated filing as a defect. A published report can carry information about your server, your client’s site, or your mistakes, and once signed and published it cannot be quietly unsent. The approval is for the exact payload bytes, given after seeing them. Every time.
What stops a secret leaking inside a report?
Two layers, honestly ranked. The one that actually protects you is the client-side scrub, because it runs before anything leaves your machine. Behind it, a receiving pipeline should refuse payloads matching known secret shapes, private key blocks, cloud and payment tokens, auth headers, credentials in URLs. Treat a rejection as a bug in your scrub and fix it there. The backstop existing is not a reason to lean on it.
Severity feels subjective. Any rules of thumb?
blocker: an install or a core workflow is unusable. major: something real breaks and there is no clean workaround. minor: real but routable-around. note: worth a row, not worth anyone’s afternoon. When torn, round down and let the sightings count argue for you; an undersold report that groups with five others speaks louder than an oversold one alone.
How do I get access to the pilot?
The pilot is closed while the loop is proven, and there is no signup. Interest is best registered in the PageMotor developers’ forum, in the thread where this idea started. Meanwhile the shape costs nothing to adopt: a report in this format, posted in a forum code block, is already machine-readable and already groups by fingerprint the day anyone points a parser at it.
Who made this guide?
ElmsPark, the PageMotor plugin studio behind the EP Suite, from a working pilot built and probed end to end in August 2026. Every mechanism described here, the shape, the fingerprint, the scrub, the gate, the sightings count, is running, not proposed.