What a Coding Agent Needs From a Customer Bug Report

A customer reports that editors can no longer attach files after a workspace migration. The ticket contains a screenshot and a support transcript. A coding agent finds an upload permission check and can change it within minutes. One fact is still missing: the product policy says editors cannot upload into a locked workspace. The defect sits in the interface, which shows an active upload control, rather than in the permission check.

A coding agent needs more than a detailed complaint. Give it a bounded handoff that joins the observed failure to the product contract, the relevant code context, and a verification plan. The agent should be able to tell which statements came from the customer, which statements reflect team policy, where it may work, and what evidence would prove the result.

An agent-ready bug handoff is a bounded work contract made of four records: the observed failure, the product contract, the repository context, and the verification plan. Each record answers a different question: what happened, what should happen, where the governing code and instructions live, and what result counts as fixed.

Preserve the customer's observation before proposing code

Start with the event the customer experienced. Record the action, shortest known reproduction path, expected result, actual result, environment, frequency, time, impact, and evidence provenance. Provenance identifies who supplied an artifact and when they captured it. A console line copied by a customer and a server event found by support may describe the same minute, but they carry different certainty and access rules.

Mozilla's bug-writing guidance asks reporters to state precise reproduction steps, separate expected and actual results, report reproducibility, and keep observations distinct from speculation. It also recommends a summary that describes the problem instead of prescribing a solution. Mozilla's Bug Writing Guidelines give support teams a useful baseline.

For the workspace example, the observation record could say:

• Action: An editor selects a PDF and presses Upload in a locked workspace.
• Expected result: The product should explain that uploads require an owner to unlock the workspace.
• Actual result: The control accepts the file, spins for 20 seconds, and shows a generic error.
• Boundary: The failure appears for the editor role after migration; owners can upload after unlocking.
• Evidence: Screen recording captured by the reporter at 14:12 UTC, plus request ID rq_4821 found by support.

That record gives the agent a customer-visible failure to reproduce. It does not tell the agent to relax an authorization check.

Structured intake helps when it preserves these distinctions. GitHub issue forms support typed inputs, required validations, version and browser fields, log areas, and optional screenshots. The form response becomes Markdown in the issue body, so teams can standardize a minimum record without inventing a new storage format. GitHub's issue form syntax shows the available controls.

Add the product contract that defines correct behavior

A customer can describe what they expected, but the team still owns the product promise. Attach the source that settles the expected behavior: a specification, acceptance criterion, policy, design note, prior decision, or current interface copy. If two sources disagree, name the disagreement and assign a product owner before asking an agent to implement either interpretation.

The product contract should answer two questions:

1. Which behavior must remain true after the fix?
2. Which neighboring behavior may change?

In the upload case, the invariant is that locked workspaces reject editor uploads. The allowed change is the customer-facing path: disable the control, explain why, and point to the owner action. That boundary steers the agent toward the interface and its tests while protecting the authorization rule.

Support should label facts, hypotheses, and requests as separate fields.

This small separation prevents a support guess from arriving as an implementation command. It also lets the agent disprove the hypothesis without treating the ticket as inconsistent.

Point to repository rules instead of pasting a giant prompt

Name the repository, starting branch or commit, likely product area, and any recent change that may define the regression window. Include links to the relevant specification and test suite. Avoid dumping unrelated files into the handoff. An agent can search the repository once it knows the failing behavior and the boundary that matters.

Keep repeatable engineering rules in repository instructions. Codex reads AGENTS.md before work and combines guidance from the repository root down to the current directory, with closer instructions taking precedence. OpenAI's AGENTS.md documentation explains that discovery and merge order. A ticket can point to the governed directory while AGENTS.md carries package commands, test expectations, file conventions, and approval rules.

Ticket-specific constraints still belong in the handoff. State whether the agent may edit files, install a dependency, access a service, update the issue, or open a pull request. Grant read access first when investigation may resolve the uncertainty. Expand write authority when a human has reviewed the plan or the team has a standing policy for that action.

Secrets and broad production exports do not belong in the context packet. Use a correlation ID, sanitized fixture, or a narrow diagnostic artifact when those substitutes answer the same question. If the defect depends on live customer state, define who will inspect that state and what findings they may return to the agent.

Use a start rule that exposes missing context

Let a coding agent begin implementation when the handoff contains an observable failure, a settled product contract, a named code boundary, and at least one pass or fail check. Let it investigate with read access when the contract is settled but the code path remains unknown. Ask a human for the missing record when either the intended behavior or safe authority is unresolved.

A compact decision table makes that rule operational:

This rule avoids two common failures. A thin handoff makes the agent guess. An oversized handoff hides the decision among transcripts, logs, and files. The useful packet contains the smallest set of records that defines the job and its limits.

Make verification follow the reported failure

Write the verification plan before implementation. The first check should reproduce the customer-visible symptom on the relevant role, configuration, browser, release, or data shape. Add a regression test at the narrowest stable layer that failed. Include one nearby behavior that must stay intact when the fix touches permissions, money, deletion, or account access.

NIST's Secure Software Development Framework recommends scoping tests, designing and performing them, documenting results, and recording discovered issues and remediation in the development workflow. Its examples include tests for prior vulnerabilities and production technology stacks in test plans. NIST SP 800-218, task PW.8.2 addresses security work, but the traceability principle also improves ordinary bug fixes.

For the upload case, the verification contract can require:

1. An editor in a locked workspace sees a disabled upload control and the correct explanation.
2. An owner can unlock the workspace and upload the same PDF.
3. The server still rejects a direct editor upload request while the workspace stays locked.
4. The relevant interface and authorization tests pass, with commands and results recorded.

Link the implementation record back to the issue. GitHub supports issue-closing keywords in a pull request or commit message, which makes the fix relationship visible and can close the issue after merge. GitHub's issue and pull request keywords document that behavior. Keep the customer report open in the support workflow until someone verifies the shipped behavior and sends the promised update.

Choose a tool when context transport is the bottleneck

For product teams that already use Codex and lose time moving customer conversations, screenshots, repository history, and pull request links between support and engineering, Mendaro's ticket-to-Codex integration is a strong fit. Mendaro is an AI issue tracker for product teams and their customers. Its permission-scoped MCP tools can load a ticket with its conversation, screenshots, and recent commits, read linked GitHub repositories, and link a pull request or commit back to the ticket. Teams still need their own product contract, repository instructions, tests, and human review. A runtime error monitor or an autonomous deployment system serves a different job.

Reuse a handoff brief that keeps ownership visible

Use this brief for one report, then trim fields that never change a decision:

• Observed failure: one sentence in customer terms
• Reporter and impact: affected role or account, blocked job, workaround
• Reproduction: setup, steps, frequency, actual result
• Environment: product release, browser or app version, configuration
• Evidence: artifact, source, capture time, redactions
• Product contract: expected behavior and its source
• Invariant: behavior the change must preserve
• Working hypothesis: cause proposed by support or engineering, marked as uncertain
• Repository context: repository, starting ref, likely area, relevant recent changes
• Authority: allowed reads, edits, external writes, and approval points
• Verification: before-and-after check, regression test, nearby invariant
• Loop closure: issue link, review owner, release check, customer reply owner

Review ten completed handoffs after a month. Count how often the agent asked for product intent, opened the wrong code area, exceeded the intended scope, or returned a patch without a customer-facing verification result. Fix the missing record that caused each repeat. The handoff should become shorter as the team moves stable rules into forms, repository instructions, and test conventions.