Field reports your agent can act on

The report shape

One report is one observation about one finding, expressed as one JSON object. The spec name is pm-field-report/1. Twelve fields, four of which do the heavy lifting.

A complete example

{
  "spec":     "pm-field-report/1",
  "event":    "sighting",      // or confirmation / resolution
  "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.

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.

1. 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.

2. 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.

3. Check for a twin, then decide which event this is

   Search wherever reports live before filing. If there is no twin, you are filing a sighting. If there is one and you are a different install, an independent sighting is the most valuable thing you can file. If there is one and you are the same install re-testing it, that is a confirmation rather than a second sighting, and filing it as a sighting would inflate the count.

   Either way your title must match the existing finding word for word, because that is what attaches your report to it rather than starting a new one.

   “Same install” means the same server, not the same key and not the same site. Several PageMotor sites on one server are one install: file one report per issue however many of them show it, and say in the evidence how many do. If a person and their agent hold separate keys, which is the arrangement we recommend, they are two reporters but still one install. A sighting from the second key on a finding the first key already filed reads as two independent occurrences of the fault when there has only ever been one. The sighting count is the single number this whole exercise exists to produce, so that is the one place a well-meant duplicate does real damage:

   second key files a sighting     → sightings: 2, confirmations: 0   ⇐ wrong
   second key files a confirmation → sightings: 1, confirmations: 1   ⇐ right

   The rule is per install and per finding, which is narrower than it first sounds. It does not retire your second key from ever filing a sighting: a fault this machine has never observed before is a legitimate first sighting under either key, because it is a first observation rather than a re-test. Changing key does not reset the machine’s history, and it does not forbid sightings either. What it forbids is one install counting itself twice for the same fault.

4. 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.

5. 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.

6. 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.

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:

0. Decide which of three things this is. A SIGHTING is a new occurrence
   on an install that has not reported it. A CONFIRMATION is "I re-tested
   an existing finding and it is still present" - same machine is fine,
   it re-dates without counting. A RESOLUTION is "fixed in version X".
   Only a sighting moves the count, so filing a re-test as a sighting
   corrupts the one number triage runs on.
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.

Three events, and only one of them counts

A finding accumulates observations over time, and they are not all the same kind of thing. Collapsing them into one number is the mistake that makes a pool lie to you.

The middle one is the one people leave out, and its absence is worse than it sounds. Without it, re-testing an old finding and discovering it is still broken has nowhere to go. Filing it again would be wrong, because it is not an independent occurrence and would inflate the count. So the correct action becomes doing nothing, and silence is indistinguishable from the fault having quietly gone away.

A confirmation dated after a resolution means the fault came back. That reads as reopened, which is not a special case so much as the consequence of believing the most recent observation.

Severity belongs to the observation

Severity is a property of what someone saw, not of the finding for all time, so the most recent observation wins. It is the same rule as reopened: believe what was seen last.

A fault first filed minor and later confirmed major by someone who found a worse interaction is now major. The board shows that it moved and who moved it, so the change reads as a decision someone made rather than a value that quietly got overwritten by whoever filed last.

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.

Asking your own agent session directly

A script you run and paste the output back from is one step better than a forum thread. An agent that can just ask is another step better than that. An MCP server exposes the pool as a handful of tools, list_findings, search_findings, get_finding, pool_health, so your session queries it in the same conversation as everything else, no script in the loop.

Same identity as filing, pure standard library, read-only by construction: it has no path to publish, only to query. It is also the only client-side view of finding state that exists. --search in the poster prints one line per event, so it shows you the raw stream; the collapsed view, whether a finding is open, resolved or reopened, its sighting count and whether its severity has moved, is computed here. If you hold a key and a relay but not the board, this is what turns events into findings.

Download field-reports-mcp.py

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.

FAQ