Research and Report a Bug

Turn unexpected product behavior into a grounded issue the team can act on.

Research enough context to avoid a thin or duplicate report, but do not require every possible system before producing useful work.

1. Understand the problem and desired action

Establish:

• symptom;
• expected behavior;
• user impact;
• environment;
• account or role;
• version;
• frequency;
• timing;
• affected scope;
• existing reproduction evidence.

Infer reliable details from:

• screenshots;
• URLs;
• messages;
• recordings;
• logs;
• product context

instead of forcing the reporter to repeat them.

Clarify whether the user wants:

• research;
• draft issue;
• issue creation;
• research followed by code work.

Identify the team's actual:

• ticketing system;
• project;
• issue type;
• template;
• severity scale;
• labels;
• ownership conventions.

Do not assume a specific vendor.

2. Gather context that can change the report

Use approved sources selectively.

Team Communication

Inspect relevant Slack, Teams, or equivalent discussion for:

• customer impact;
• timing;
• previous investigation;
• ownership.

Repository Context

Inspect GitHub or the approved code source for:

• relevant repositories;
• code context;
• recent changes;
• pull requests;
• release history;
• existing issues.

Ticketing System

Check:

• duplicates;
• related work;
• templates;
• severity definitions;
• current status.

Operational Evidence

Use when relevant:

• logs;
• monitoring;
• analytics;
• support records;
• screenshots;
• recordings.

Product

Reproduce safely where practical.

Match carefully:

• people;
• accounts;
• repositories;
• builds;
• tickets.

Preserve useful links and identifiers.

Keep secrets, tokens, private messages, and customer-sensitive data out of the issue.

Summarize or redact evidence when needed.

3. Reproduce and narrow the behavior

Prefer:

• staging;
• preview;
• dedicated test account

for authenticated or stateful reproduction.

On public production surfaces, stay read-only unless active scoped permission covers the exact state-changing behavior.

Record:

• minimal steps;
• expected result;
• observed result;
• environment;
• version;
• account role;
• test data;
• frequency;
• screenshots;
• console evidence;
• network evidence.

Recheck failures when safe.

Keep distinct:

• confirmed behavior;
• suspected regression range;
• likely component;
• root-cause hypothesis.

Do not present a hypothesis as confirmed cause.

If reproduction is impossible, construct the strongest available evidence chain and state the limitation.

4. Search for duplicates

Search the actual issue system and relevant repository issues using:

• symptom;
• error text;
• flow;
• component;
• version;
• synonyms.

Compare:

• behavior;
• environment;
• scope;
• status.

If a matching issue exists:

• return the match;
• identify new evidence worth adding.

Updating, commenting, or reopening remains a separate external action.

Do not file duplicates simply to complete the workflow.

5. Prepare the issue

Use the team's accepted issue format.

Include where useful:

• clear title;
• user impact;
• environment;
• version;
• role;
• scope;
• frequency;
• minimal reproduction;
• expected behavior;
• observed behavior;
• screenshots;
• logs;
• console/network evidence;
• source links;
• severity/priority using team definitions;
• duplicate search;
• related work;
• suspected component or regression range as inference;
• verification notes;
• uncertainty;
• privacy-safe evidence gaps;
• cleanup state.

Keep proposed solutions separate from confirmed cause.

6. File only within current permission

Follow active scoped permission for:

• ticketing account;
• project;
• issue type;
• fields;
• destination;
• action.

If creation is authorized:

1. create the issue;
2. verify identifier;
3. verify URL;
4. verify fields;
5. verify attachments.

Otherwise provide a reviewable draft or request the missing approval.

Stop when:

• identity changes;
• repository changes;
• environment changes;
• account changes;
• project changes;
• scope changes;
• impact changes;
• sensitive-data handling changes.

Batch findings remain reviewable until filing scope is clear.

7. Preserve evidence for implementation

If the user also requests a fix, continue through the available engineering workflow under normal repository, validation, and permission boundaries.

Keep the issue evidence connected to:

• implementation;
• testing;
• verification.