A bug report needs a reproducible boundary, not a confident diagnosis

By ColunTina. Written with AI assistance to introduce Orkas. The software, reports and resulting issue below are fictional. This is an illustrative editing example, not a recorded Orkas test or a diagnosis of a real application.

“Export is broken” is enough to start a conversation, but not enough to reproduce a failure. A useful bug report separates what someone observed, the conditions they tried, and the explanation that still needs evidence. AI can help make that separation visible, provided the instruction does not ask it to fill gaps with a plausible cause.

Orkas (https://orkas.ai/?source=article_highlighter) is an open-source, local-first desktop AI workspace for macOS and Windows. Commander coordinates specialist agents around project materials and can connect research, code and report work. For a small software team, one proposed use is to organise authorised, sanitised bug notes into a reviewable issue before anyone changes code.

THREE NOTES, NOT THREE CONFIRMED CAUSES

Consider a fictional application called Field Notes. Its owner supplies these observations:

Report A: on build 0.8.2, clicking Export after opening a saved project produced an empty CSV. The reporter says the project had three visible rows. The operating system and exact click sequence were not recorded.

Report B: on build 0.8.2, a newly created project with three manually entered rows exported a CSV containing those rows. This was a different reporter. The notes do not say whether both reporters used the same device or settings.

Report C: someone suggested that cached data might be responsible. They supplied no log, experiment or reproduction steps.

These notes support a contrast between two reported situations. They do not establish that saved projects always fail, that new projects always succeed, or that caching caused anything. The two successful and unsuccessful observations must remain attributed to their separate reports.

THE REQUEST TO COMMANDER

“Use only these three fictional notes. Draft one issue with an observed problem, the nearest known comparison, a proposed reproduction procedure, explicit missing information and acceptance checks. Label the procedure as unverified. Treat the caching idea as an untested hypothesis. Do not invent a stack trace, error message, platform, affected-user count or root cause. Return a draft; do not file the issue, message reporters, access production data or modify code.”

That instruction gives the AI a concrete output and a clear limit. Project context can retain the source notes, while a specialist can help structure the issue. Neither role turns a suggestion into a measured result.

THE RESULTING ISSUE DRAFT

Title: Investigate empty CSV reported after opening a saved project in build 0.8.2

Observed: Report A describes an empty CSV after opening a saved project with three visible rows and choosing Export. The exact actions and operating system are missing. This has not been independently reproduced.

Comparison: Report B describes a CSV containing three rows from a newly created project in the same build. Device, settings and data equivalence between A and B are unknown.

Proposed reproduction, not yet run: use a disposable project containing three clearly labelled synthetic rows. Record the operating system and build. Export once from the new project and retain the CSV. Save and reopen that project, record the exact reopening steps, then export again. Compare both files with the three synthetic rows. Repeat only if needed to establish whether the difference is consistent. Keep the real reporter’s data out of the shared issue.

Information to request before diagnosis: the exact click sequence for A; the operating system; whether rows were committed or merely visible in an unsaved editor; and whether A and B used equivalent settings. Request sanitised details through the team’s authorised process, not by posting private logs publicly.

Hypothesis: a cache problem was suggested in C. It remains untested. Other explanations have not been ruled out, so the issue should not be titled “Fix the export cache”.

Acceptance checks for a later reviewed fix: document whether the proposed procedure reproduces the problem; if a change is made, export the same synthetic rows before and after reopening; inspect both resulting CSV files; record remaining limits. Passing those checks would support those tested cases, not every possible export workflow.

REVIEW THE ISSUE BEFORE ASSIGNING IT

The draft is useful because a developer can act on it without mistaking the proposed experiment for completed testing. Compare each sentence with A, B and C. In particular, retain “reported”, “unknown” and “not yet run” where they carry evidence. Remove them only after new observations justify a revision.

A later Orkas task could use the approved issue and repository context to propose code changes and a test report. Review the actual diff and test output before accepting a fix. Library sources, project memory and reusable skills can help keep the issue and its supporting notes aligned, but they do not replace verification. The core application is free; selected models and optional services may cost extra. Local-first work still sends selected material to any external model or authorised tool you choose.

A careful issue does not need a confident story about the cause. It needs enough known conditions to test, and enough honesty about what has not been observed.