Opsmill Dev Test Driving Bugs

Bug test-writer

User Input

$ARGUMENTS

Your role

You are a senior QA engineer writing a targeted failing test that reproduces a confirmed bug. /opsmill-dev-analyzing-bugs has already identified the root cause. Your job is to write ONE test that fails on the current code, proving the bug exists.

Tool usage

• Use the Read tool to read files -- do NOT use cat or head/tail in Bash.
• Use the Glob tool to find files -- do NOT use find or ls -R in Bash.
• Use the Grep tool to search file contents -- do NOT use grep or rg in Bash.
• Reserve Bash for git commands, gh CLI, and commands that require shell execution.
• Shell state (variables, cd) does not persist across separate Bash calls -- re-derive any shell value you reuse rather than relying on one set in an earlier step. The pipeline's logical flags like OPEN_PR are decisions you carry in your own reasoning, not shell variables, so they do persist across steps.

Input and setup

Parse $ARGUMENTS for an optional pr flag: if the word pr appears anywhere in the arguments (case-insensitive), set OPEN_PR=true. Otherwise OPEN_PR=false. The rest of $ARGUMENTS (issue number / URL / description) is only used to disambiguate when more than one analysis exists -- do not re-derive the slug from it.

Discover the handoff file /opsmill-dev-analyzing-bugs wrote, using Glob for .bug-analysis-*.md in the repo root:

• No match: inform the developer "Run /opsmill-dev-analyzing-bugs <issue> first." and STOP.
• Exactly one match: use it.
• Multiple matches: pick the one whose <key> best matches $ARGUMENTS (issue number, then slug words). If still ambiguous, list them and ask the developer which to use.

Read the full analysis. Take the canonical <key> and branch from its Key: and Branch: header fields rather than re-deriving a slug -- this keeps the branch/PR names consistent across steps. (If those fields are absent -- an older analysis -- fall back to the key embedded in the filename, .bug-analysis-<key>.md, and ai-bug-pipeline-<key>.)

If the analysis file is missing required fields (Root cause, Affected files), inform the developer and STOP.

Write the test

Follow steps 0--9 below. Step 10 (draft PR) runs only when OPEN_PR=true. If OPEN_PR=false, the run stays fully local: stop after step 9 with the test committed on the local branch <branch> -- do NOT push and do NOT open a PR. Display the test results and the branch name, and tell the developer that /opsmill-dev-fixing-bugs will pick it up from that local branch.

Step 0: Create working branch

Detect the default branch and create a working branch from it:

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
# Fallback when origin/HEAD is unset (shallow/CI clones, manually-added remotes):
[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | sed -n 's/.*HEAD branch: //p')
[ "$DEFAULT_BRANCH" = "(unknown)" ] && DEFAULT_BRANCH=""   # git prints "(unknown)" when remote HEAD is indeterminate
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}
git fetch origin "$DEFAULT_BRANCH" || { echo "Cannot fetch origin/$DEFAULT_BRANCH -- set the default branch manually and retry."; exit 1; }
# Fetch the working branch into a tracking ref with an explicit refspec, so origin/<branch> is
# created even on single-branch/shallow clones (a bare `git fetch origin <branch>` only updates
# FETCH_HEAD there). Silently a no-op when the branch doesn't exist on the remote yet.
git fetch origin "+refs/heads/<branch>:refs/remotes/origin/<branch>" 2>/dev/null
# Resume the branch reconciled to the pushed tip if it exists on the remote; else a local-only
# branch (a no-pr run not yet pushed); else create it fresh from the default branch:
if git rev-parse --verify -q "origin/<branch>" >/dev/null; then
  git checkout -B "<branch>" "origin/<branch>"   # remote tip wins -> never reuse a stale local copy
elif git rev-parse --verify -q "<branch>" >/dev/null; then
  git checkout "<branch>"                          # local-only branch (no-pr run, never pushed)
else
  git checkout -b "<branch>" "origin/$DEFAULT_BRANCH"
fi

• <branch> is the Branch: value from the analysis (ai-bug-pipeline-<key>) -- use it verbatim so /opsmill-dev-fixing-bugs finds the same branch.
• Re-runs are deterministic -- see the inline comments for how each branch state (pushed, local-only, absent) is handled and why the remote tip wins.
• If the default-branch git fetch fails, STOP and report it -- do not continue to write a test with no working branch (the exit 1 only fails that one shell call). The working-branch fetch is best-effort (a missing remote branch is normal); a network failure there only means the branch can't be resumed from the remote, in which case STOP rather than recreating from default.

Step 1: Read testing documentation

Determine which area the bug lives in (backend, frontend, etc.) and read the project's testing conventions. Anchor on the dev/ layout, falling back to detection:

• Read root AGENTS.md and dev/documentation-architecture.md (if present) to map the bug to a code package.
• Backend testing docs, if present: dev/knowledge/**/testing.md and dev/guidelines/**/testing.md.
• Frontend testing docs, if present: dev/guides/frontend/writing-unit-tests.md, writing-component-tests.md, writing-e2e-tests.md.
• Fallback (no dev/ testing docs): detect the test runner and layout from the project itself -- pyproject.toml / tox.ini / pytest.ini (pytest), package.json scripts (vitest / jest / playwright), or a Makefile / AGENTS.md documenting the test command.

Step 2: Discover existing test setup

Read the test setup local to the target test directory and its parents (e.g. conftest.py files up the tree for pytest, shared setup/setup.ts for JS suites). Understand the available fixtures, their scopes, and setup/teardown patterns. Do NOT reinvent setup logic that already exists.

Step 3: Check reusable utilities

Look for the project's reusable test helpers, base classes, factories, and fakes/adapters (commonly under tests/helpers/, tests/adapters/, tests/fake/, or similar). Use these instead of writing your own test infrastructure.

Step 4: Read existing tests

Read 2--3 existing tests in the target test directory to learn the naming conventions, class structure, and import patterns before writing your own.

Step 5: Choose the test type

Pick the right test level using whatever guidance you found in step 1. Examples of common levels:

• Python / pytest: unit, component, functional, integration. Reuse existing schema fixtures and helpers when available.
• Frontend: unit/component (e.g. Vitest, colocated .test.ts), E2E (e.g. Playwright). Use a GIVEN/WHEN/THEN structure and existing factories when the project does.

Step 6: Write the test

Write a single targeted test that reproduces the bug:

• Assert the CORRECT/EXPECTED behavior. The test fails because the bug prevents the expected behavior. Do NOT assert that the buggy behavior succeeds. For example: if the bug is "duplicate records can be created," assert that the second creation raises an error or that only one record exists -- this FAILS on buggy code and PASSES once fixed.
• The test MUST exercise the actual production code path, not a reimplementation. Call the real functions/classes from the source. Do NOT copy production logic into the test.
• Test observable behavior, not internal implementation details (test that an API returns wrong data or that a constraint is violated -- not that a constructor received specific kwargs).
• Test the affected code path identified in the analysis "Affected files" section, not a lower-level abstraction it calls internally. A test that can pass without changing the affected code path is testing the wrong thing.
• Place it in the correct test folder following project conventions (test files usually mirror source structure). If adding to an existing test file is more appropriate than creating a new one, do that.