# Improvements and finding work

Improvements brings control snags, JavaScript errors, and recorded funnel drop-offs into one review. Each finding has an observation, a count with its actual unit, the page context, an investigation step, and source moments when the caller can watch recordings.

The dashboard and API keep current evidence separate from team decisions. A deployed fix is a team report. The linked before-and-after comparison supplies the measured result, including insufficient evidence and its own scope limits.

## Evidence and coverage

- Control findings read at most 20 recently active cohorts and inspect element candidates for the ten busiest of those cohorts. They use retained counters for repeated clicks, clicks with no observed response, and error clicks. Bounded selector candidates can omit additional events, so counts are labeled as lower bounds. These are signal events, not distinct people or failed business transactions. The counters have no date axis, so the feed accepts no date filter.
- JavaScript errors cover up to 14 UTC days, limited by recording retention. Counts are page views with the error, grouped by fingerprint and the stored joint page context. The error report supplies its stack and original source location when source maps exist.
- Funnel findings read the first three configured funnels, with at most the newest 100 entering visits per funnel over 14 days, limited by retention and each goal definition. Entry cohorts stay separate. Historical entries without a page revision remain an explicit unknown bucket. A missing recorded next goal does not establish abandonment or a defect.
- Page group, content version, revision, variant, and device class remain part of a finding’s identity. Raw release identity is retained when the evidence source has it. A new goal definition gets a different funnel identity.
- Sources alternate in the list. Larger observed counts come first within a source; counts with different units and windows do not form a universal priority score.
- Unavailable sources remain unavailable. Partial coverage, read limits, disabled capture, and missing replay examples do not become invented zeros. Identified test, automated, and internal visits follow the existing exclusion rules; historical records cannot prove every such visit was recognized.
- Recording links require current replay permission and a retained recording. Reading aggregate findings does not require replay access. Work metadata contains bounded source identifiers rather than a copy of recorded page content.

The feed shows at most 20 control findings, 12 error findings, and 12 funnel transitions. Replay checks cover the first four findings of each kind, with at most two examples each. A missing example means none was found in that bounded sample, rather than proof that no matching visit exists.

Opening an error or funnel from a finding preserves its evidence window and exact page context. Error API requests accept a JSON-serialized `context`, and funnel statistics accept `entryContext`; both use the finding’s `source.context`. Funnel requests also carry `expectedGoals` from `source.goalDefinitions`, so a changed goal definition returns a conflict instead of silently changing the report. Historical unknown dimensions remain unknown rather than matching every known version. A person can explicitly clear this scope to investigate a broader report. Funnel context cannot specify a raw release because those entries do not retain it.

## Working on a finding

Anyone with report access can review current findings and saved work. Annotation permission is required to save decisions or list eligible assignees. Assignment does not grant access. The picker returns current site member identifiers, names, and roles without email addresses.

A finding can be open, in progress, snoozed, dismissed, or reported fixed. Expired snoozes return to attention without a scheduled job. Dismissed findings remain available and can be reopened. A release or revision’s dismissal does not hide a different source identity.

Save a GitHub issue or pull request URL as a reference. Hoot Lens does not create an issue, fetch the URL, or infer its merge or deployment state from that link. Only canonical HTTPS github.com issue and pull request links without credentials, parameters, or fragments are accepted.

Record a fix only after it is live. Attach a real existing change or record a new deployed change in the same atomic operation as the work update. A repeated identical operation does not create another change marker. Control and error changes must apply to the source page or the whole site. Funnel entry context does not identify the location of a fix, so a new funnel fix is recorded with site-wide scope; a linked change retains its actual page scope.

The comparison is the existing page-level before-and-after report. It can include other page versions, variants, and devices within its stated scope. It is not an exact-cohort experiment and does not establish that the fix caused a difference. Measurement-only changes cannot be recorded as page fixes. If a linked change is deleted, work history remains while the comparison becomes unavailable.

## API and MCP

| Request | Permission | Result |
| --- | --- | --- |
| `GET /v1/projects/:projectId/improvements` | read | Current bounded feed and coverage |
| `GET /v1/projects/:projectId/finding-work` | read | Up to 500 saved findings with short history previews |
| `GET /v1/projects/:projectId/finding-work/:findingId` | read | One saved finding and retained history |
| `GET /v1/projects/:projectId/finding-work/assignees` | annotate | Eligible current teammates, without emails |
| `PUT /v1/projects/:projectId/finding-work/:findingId` | annotate | Atomic decision, history, and optional deployed change |

An update supplies `expectedRevision`, `operationId`, and a validated `action`. Use revision 0 before the first saved action. Retain the exact request when retrying an uncertain response. A changed revision returns a conflict; reload current work and reconsider the action rather than overwriting another person’s decision. The first action must identify a finding from current server evidence. Later actions can manage retained work after recording retention expires.

MCP exposes the same behavior through `review_improvements`, `list_finding_work`, `get_finding_work`, `list_finding_assignees`, and `update_finding_work`. Tools do not grant permission to change work merely by reading it. A person must explicitly authorize a write, and the current role and credential scopes are enforced by the API on every request.

## Retention and limits

Saved work is durable project metadata, like logged changes, and can outlive recording retention. It retains no replay events, recorded labels, or raw error messages. Keep visitor details out of reasons and deployment notes. Each site can track 500 findings; each finding keeps the latest 100 decisions and operation receipts. The current revision reveals the total number of saved actions, while older detailed history can be unavailable.

The public anonymous MCP demo can review its synthetic findings. It cannot read team work records, assign work, or save decisions.