Reports and evidence#

A bug report describes a problem, reproduction steps, expected and actual behavior, and supporting evidence. It can remain local and incomplete; an external ticket or executable reproduction is not a prerequisite for recording an observation.

Instructions versus observations#

Reproduction steps tell someone how to encounter a problem. Recorded interactions describe actions actually taken during an attempt, including detours and unfinished sequences. Keep both when they differ. Promotion from a result preserves actual interactions rather than pretending the planned test was the observed journey.

An expectation states either an established requirement or a proposed one. A hypothesis is an explicitly unverified explanation. Neither becomes an observation because it appears in a report.

Evidence and attachments#

Evidence may be structured diagnostic JSON, an attachment descriptor, or an explicit unavailability reason. Steps and interactions link to evidence by identity. Parsers reject dangling references. An attachment descriptor does not itself contain the file bytes; the host supplies those when exporting.

Screenshots and recordings should support a specific observation. The portable capture entry defines types but does not operate a browser or collect files. Prototype evidence is illustrative.

Identity and revisions#

A report's stable identity survives edits. A revision identifies one version of its content and retains a detached source snapshot. Edits create new values; they do not rewrite prior reports. Removing evidence also removes direct links to it. Editing or sanitizing content invalidates applicable verification claims.

Reproduction readiness#

Executable reproduction records a runner, script, hook names, required inputs, missing prerequisites and optional verification. Readiness can be incomplete, runnable but unverified, or verified to reproduce the problem. Imported scripts are data, not permission to execute them.

A regression test is a separate check of an established expectation on buggy/fixed states. The readiness helper assesses supplied validation; it does not manufacture evidence or generate tests.

Follow first bug report, export review, and format reference. The root glossary is the shared vocabulary.