Fix Bug

Fix Bug (Test-Driven)

Fix a bug using a strict TDD workflow: understand the bug, prove it with a failing test, fix the code, verify.

This skill has two modes:

• Interactive (default): ask the user whenever the bug is unclear, confirm understanding before writing any code, confirm test kind, etc.
• Autonomous: never ask the user. Explore the codebase, form hypotheses, classify the ticket into one of four outcomes (REPRODUCED / STALE / ALREADY-FIXED / UNREPRODUCIBLE), and act accordingly. For REPRODUCED: fix the proven bug(s), run a self-review pass, enumerate deferred-work follow-ups, then (if the repo's .sculptor/code.md Publishing Changes section permits it) push and open an MR/PR. For the other outcomes: report the outcome with evidence (via the testing config's ticket entry points if configured) and do NOT push. Triggered when the input begins with --autonomous (or autonomous as the first token).

Steps 1–3 below are shared by both modes. After Step 3, autonomous mode jumps to the "Autonomous Workflow" section near the end of this file. Interactive mode continues into Phase 1.

Step 1: Load config (REQUIRED — do not skip)

You MUST have all three config files before doing anything else. Do not proceed to any later step until all three files exist and you have read them.

Check for .sculptor/code.md, .sculptor/testing.md, and .sculptor/docs.md in the repo root.

• If any of the three files is missing, immediately invoke the /sculptor-workflow:setup-repo skill via the Skill tool. Do NOT ask the user whether to run it first — just run it. Do NOT attempt to fix the bug without these files. Do NOT try to infer the information yourself — the setup skill exists specifically to gather this information correctly through conversation with the user.
• Once all three files exist, read them. Their contents drive every step below:
  • .sculptor/code.md: codebase structure, branch naming, build/run commands, pre-commit verification, publishing changes, proof-of-work standards
  • .sculptor/testing.md: test framework, test strategy, bug tracking (fetch / file / comment / state-change entry points), manual testing, visual verification
  • .sculptor/docs.md: in particular the ## Code Review section, which names the skill that the post-fix review pass invokes (see Phase 4 and Phase A4.5 below). If the section is empty or absent, the review pass is skipped — see "Code review fallback" notes inline.

Step 2: Create a branch

Check the current branch with git branch --show-current.

• If the current branch is not the default branch, skip branch creation and work on the current branch.
• If the current branch is the default branch, create a new branch using the code config's Branch Naming convention. If the config has no branch naming section:
  • Interactive mode: ask with your question tool.
  • Autonomous mode: generate a reasonable slug from the bug description (lowercased, kebab-case, ticket ID prefix if present), e.g. auto/bugs/SCU-123-login-crash or auto/bugs/login-crash.

git checkout -b <branch-name>

Step 3: Fetch bug ticket context

If the testing config has a Bug Tracking section, follow its instructions. The config specifies:

• What bug ticket IDs look like (e.g. SCU-123, PROJ-42)
• Whether a ticket is always required, or only when the input matches the ticket ID format
• How to fetch the ticket's context (e.g. invoke a skill, call an API)

If the input matches the ticket ID format, fetch the ticket's title, description, and comments, and use that context as the bug description for the rest of the workflow.

If the config says a ticket is always required but no ticket ID was provided:

• Interactive mode: use your question tool to ask for the ticket ID or whether they want to proceed without one.
• Autonomous mode: proceed without a ticket. Note in the final MR/PR body that no ticket was provided.

If the testing config has no Bug Tracking section, skip this step.

If running in autonomous mode, jump now to the Autonomous Workflow section. The interactive Phase 1–4 below does not apply.

Phase 1: Understand the Bug

Before writing any code, get full clarity on what is broken.

Gather information

1. Ask the user questions with your question tool if the description is vague or incomplete. Don't guess — ask about:

   • Exact steps to reproduce
   • What the user expected to happen
   • What actually happened (the buggy behavior)
   • Error messages, logs, or screenshots
   • Whether it's intermittent or consistent
   • Edge cases or interactions with other features

2. Read the relevant source code to understand how the feature currently works. Trace the code path to build a mental model of where the bug likely lives.

3. Reproduce the bug (if the testing config has a Manual Testing section). Follow the config's instructions to launch the app and visually confirm the bug. Take screenshots at each step — you will show them to the user in the confirmation step. If there are no manual testing instructions, skip visual reproduction.

Decide what kind of test to write

Follow the testing config's Test Strategy section. The test strategy is mandatory policy, not a suggestion — you MUST follow its rules about what kind of test to write.

Getting user confirmation (MANDATORY — you MUST stop here and wait)

Write out your understanding as a summary:

• What the current (buggy) behavior is, with repro steps
• What the desired (correct) behavior should be
• Whether this is behavioral or purely visual
• If behavioral: the test kind (e.g. e2e, backend unit, frontend unit) and the test file path where you plan to write the test, with a brief explanation of why you chose that kind and location based on the testing config's Test Strategy. Be explicit — do not leave the test kind implicit in the file path.

The summary MUST appear as a plain chat message before you call the question tool. Your internal reasoning is invisible to the user, and the question panel only shows short question text — so a diagnosis that lives only in your thinking or inside the question tool's input was never shown to the user, and asking "does the diagnosis match?" leaves them with nothing to confirm. Skipping the written summary and jumping straight to the question tool is a known failure mode for this phase — do not do it.

If you reproduced the bug visually: include the screenshots inline with <img> tags. Walk the user through each screenshot, explaining what you did and what you observed.

You MUST ask with your question tool here — mcp__sculptor__ask_user_question if it's available, otherwise the built-in AskUserQuestion — do NOT ask via a plain text message. (The written summary above is still a plain text message; only the ask itself goes through the tool, which triggers a UI notification that grabs the user's attention.) Ask:

"Does this match your understanding? Is the test location correct? Please confirm so I can proceed."

Then STOP. Do not proceed to Phase 2. Do not write any code. Wait for the user's explicit response.

Phase 2: Write a Failing Test

Write a test that asserts the desired (correct) behavior. Since the bug hasn't been fixed yet, this test should fail.

Lock in the Phase 1 commitment (MANDATORY — do not skip)

Before writing anything, restate the commitment from Phase 1 verbatim:

"In Phase 1 I confirmed I would write a <test kind> test at <test file path>. I will write that exact test now."

The test kind and file path are locked. You MUST NOT re-read the testing config's Test Strategy and re-derive the decision. The user already confirmed it. Re-opening the decision here is the most common failure mode for this skill — do not do it.

If you hit an obstacle that seems to require deviating

If, while writing the test, you believe you need to change the test kind (e.g. fall back from an end-to-end test to a unit test), you MUST stop and ask with your question tool before writing anything different. In the question:

• Name the specific obstacle you hit (e.g. "the bug only reproduces when <X>, and the end-to-end test framework cannot do <Y>"). "Difficult," "slow," "flaky," or "inconvenient" are NOT valid obstacles — re-read the testing config's definition of when fallback is allowed.
• State the new test kind and path you are proposing.
• Wait for explicit user approval before writing the different test.

Do NOT decide to deviate on your own. Do NOT silently write a different kind of test than what was confirmed.

Writing the test

Follow the testing config's instructions for:

• Which test framework to use (for the locked-in test kind)
• What conventions to follow (naming, fixtures, setup)
• Whether to invoke a skill or write directly

If the config references a skill for writing tests of the locked-in kind, invoke that skill. If not, read an existing test file in the repo as a reference and follow its patterns.

Test design:

• The test should exercise the exact scenario described by the user.
• Write assertions that would pass once the bug is fixed and fail with the current buggy code.
• Keep the test focused — test only the buggy behavior, not unrelated functionality.

Confirm the test fails

Run the test using the testing config's test runner command (or skill). Verify it fails because of the bug.

• If the test passes: it does not capture the bug — revise the assertions.
• If the test fails for an unrelated reason (setup, infrastructure): fix the test setup. If the config references a debugging skill, use it.

Once the test fails as expected, commit the test file with a message like: Add failing test for <bug description>.

Phase 3: Implement the Fix

Now implement the code change to make the test pass.

STRICT RULE: Do NOT modify the test

It is NOT ALLOWED to change the test file created in Phase 2. The test is the specification — the code must be changed to make the test pass, not the other way around.

Implementation workflow

1. Implement the fix: make the minimal code change needed.
2. Run the test: use the testing config's test runner.
3. If the test still fails: investigate and iterate on the implementation. If the config has a test debugging skill, use it.
4. Repeat steps 1-3 until the test passes.

After the test passes

Run the code config's pre-commit verification commands. Fix any issues introduced. Commit the implementation.

Phase 4: Verification

Visual verification (if manual testing is available)

If the testing config has a Manual Testing section:

1. Follow the config's instructions to launch the app.
2. Re-run the original repro steps and take screenshots.
3. If the config has Visual Verification instructions (e.g. annotating screenshots), follow them.
4. Show the "after" screenshots to the user alongside the "before" screenshots from Phase 1.

Verification mode (read the testing config)

The testing config (.sculptor/testing.md) may specify rules about how to verify particular classes of bugs — for example, which test harness mode to use, whether real external services are required, or which kind of evidence is mandatory. Re-read the testing config's Test Strategy and Manual Testing sections now and apply any verification rules that match this bug's class. Verification policy lives in the repo's config, not in this skill.

Self-review pass (REQUIRED — implementation isn't done until reviewed)

Run the code-review skill named in .sculptor/docs.md's ## Code Review section against the diff produced by this fix.

• If the section is missing or empty: skip the review pass entirely (same fallback as /sculptor-workflow:review). Continue to "Final checks" below.

• If the section names a skill (e.g. Skill: /code-review-checklist): invoke that skill with:

  • Working directory: the repo root.
  • Diff range: <base branch>...HEAD, where <base branch> is the up-to-date remote-tracking base ref (e.g. origin/main) — NOT local main, which may be stale and silently widen the diff to include commits already merged upstream. The three-dot syntax scopes the review to this branch's own commits (it diffs against the merge base automatically).
  • Stated goal: a short summary of the bug and the intended behaviour (the same content you've been building in Phase 1).

  Read every finding. Use your judgement to decide which findings to act on (there's no severity rule — trust yourself). For each finding you decide to act on, fix it in a follow-up commit. Single pass — do not re-run the review after fixing. Print the remaining findings (those you declined to act on) at the end of Phase 4 so the user can see them.

The implementation is not considered complete until this review pass has run.

Final checks

1. Ensure all pre-commit verification commands from the code config pass.
2. Ensure all unit tests pass (if the code config specifies a unit test command).
3. Confirm the implementation is committed.

Summary Checklist

All bug fixes

• All three config files (.sculptor/code.md, .sculptor/testing.md, .sculptor/docs.md) loaded (or created via setup)
• Bug understood: current behavior, expected behavior, and repro steps
• User confirmed understanding before any code was written
• Failing test written and committed (for behavioral bugs)
• Test confirmed to fail before the fix
• Fix implemented — test now passes
• Test file was NOT modified during the fix
• Pre-commit verification commands pass
• Fix committed
• Phase 4 self-review pass ran (or was skipped only because .sculptor/docs.md has no ## Code Review section); findings the agent declined to act on were printed to the user

Visual verification (if manual testing available)

• Bug reproduced with screenshots before the fix
• Screenshots taken after the fix showing correct behavior
• Before/after screenshots shown to the user
• Any verification rules in the testing config that apply to this bug's class were followed

Autonomous Workflow

Enter this workflow only when the input began with --autonomous (or autonomous as the first token). Steps 1–3 above have already run.

Forbidden in autonomous mode

• No asking the user. Not for clarification, not for confirmation, not for fallback approval, not ever.
• No waiting on the user. Don't ask "should I proceed?" — proceed.
• No fabricated bugs. If you cannot reproduce any plausible interpretation of the user's description with a real failing test, classify the outcome as STALE, ALREADY-FIXED, or UNREPRODUCIBLE per the "Ticket outcomes" section below and take the corresponding branch. Do not invent a bug to fix. Trying to fix every ticket at all costs is the failure mode that pattern was added to prevent.
• No editing the test after the fix begins. Same STRICT rule as Phase 3 in the interactive workflow.
• No skipping the test-strategy criteria. The .sculptor/testing.md rules for when a non-end-to-end test is allowed still apply. In autonomous mode you make that decision yourself (no user gate), but the criteria are unchanged. Document the test-kind choice for each bug in the final MR/PR body so a reviewer can sanity-check it.
• No thin MR/PR bodies. "Fixed the bug" with no detail is forbidden. The body is the reviewer's only context — see the "Required output" block below.
• No skipping evidence capture on cost or convenience grounds. Running the testing config's Manual Testing flow twice (once in A2 to reproduce, once in A4 to verify the fix) is a fixed cost of this workflow, not optional. "Too slow," "too expensive," "the failing test output already proves it," "the fix is obvious," and "I'll add screenshots later" are NOT valid reasons. For any bug you reproduce through the UI in A2, before and after screenshots are mandatory artifacts in the MR/PR body and cannot be replaced by test output.

Required output: a comprehensive MR/PR body

The success bar for autonomous mode is a reviewer can approve the MR/PR without re-running the repro themselves. That requires:

• A detailed prose description of the repro (exact steps, environment, expected vs actual), the hypothesis, and the fix (what changed and why).
• Proof of work matching the standard in .sculptor/code.md's ## Proof of Work section — typically before/after screenshots for UI-visible bugs, failing-then-passing test output for the rest. Capture this evidence as you go in Phases A2 and A4 (instructions inline below). Do not try to reconstruct screenshots at the end.

Treat A1–A4 as actively building the MR/PR body. Keep an "evidence log" in your working notes — for each hypothesis: the repro attempt, screenshots taken (with file paths), the test file path, what the test output looked like before the fix and after.

Ticket outcomes (read before A1 — this is the decision tree)

Autonomous mode MUST recognize that not every ticket is a "fix this code" ticket. After Phase A1 + A2 (investigate, form hypotheses, attempt repro), the agent classifies the ticket into exactly one of four outcomes:

1. REPRODUCED — at least one hypothesis was reproduced with a real failing test. Proceed to A3 → A4 → A4.5 → A5 (the existing flow).
2. STALE — the described symptom does not manifest on the current main. The bug appears to have resolved itself (perhaps via an unrelated commit). Skip the fix flow. Take the "STALE" branch under Phase A5.
3. ALREADY-FIXED — investigation surfaces an existing commit or MR on main that already addresses the bug. Skip the fix flow. Take the "ALREADY-FIXED" branch under Phase A5.
4. UNREPRODUCIBLE — the description is too ambiguous to form a grounded hypothesis, or every hypothesis the agent formed was discarded after attempting repro. Skip the fix flow. Take the "UNREPRODUCIBLE" branch under Phase A5.

Crucial rule: if the outcome is anything other than REPRODUCED, the agent MUST NOT push a branch, open an MR, or commit a speculative fix. Do not invent a bug to fix. Trying to fix the bug at all costs — when the right answer is to say "this is stale" or "I can't reproduce this" — is the failure mode this section exists to prevent.

Trust the outcome decision. A clean STALE / ALREADY-FIXED / UNREPRODUCIBLE outcome is a successful run, not a failed one.

Phase A1: Investigate and form hypotheses

1. Re-read the bug input (plus ticket context, if any was fetched in Step 3).

2. Check whether the bug is already fixed. Search git log --oneline -200 and grep the codebase for recent changes that could plausibly address the bug (commits mentioning the same files, symptoms, or ticket ID). If you find one, plan to verify in A2 — if the symptom no longer reproduces on main, the outcome is ALREADY-FIXED.

3. Explore the codebase to find the code path(s) the description could plausibly refer to. Use Grep, Glob, and Read. If the testing config has a Manual Testing section, follow its instructions to poke at the live UI to narrow down where the bug surfaces.

4. List concrete hypotheses. Each hypothesis must name:

   • The specific user-visible behavior that would be wrong
   • The code path / file / function likely responsible
   • How a test could distinguish "bug present" from "bug fixed"

5. Cap the list. Carry at most 3 hypotheses forward. If you have more, keep the 3 best-supported by code evidence and drop the rest.

   If the description is so vague that you can't form even one grounded hypothesis: the outcome is UNREPRODUCIBLE. Stop here, skip A2–A4, and take the UNREPRODUCIBLE branch under Phase A5.

Save your hypothesis list (titles + one-line summaries) — you'll quote it in the final MR/PR body, or in the ticket comment if the outcome is not REPRODUCED.

Phase A2: Reproduce each hypothesis with a real test

For each hypothesis, in order:

1. Try to reproduce the bug through the UI by following the testing config's Manual Testing section (if present). Drive the UI to the buggy state, then take a before-screenshot and save it under the workspace attachments directory (e.g. attachments/screenshots/bug-<slug>-before.png). This screenshot is a required artifact in the final MR/PR body — capturing it now is not optional, and the failing-test output you save in step 3 does not substitute for it. Record the exact repro steps you used — every click, input, and navigation — in your evidence log; they go into the MR/PR body verbatim. If the bug does not reproduce, discard the hypothesis and note in the evidence log what you tried and what you observed instead. Move on.
2. Write a failing test that asserts the desired behavior, following the testing config's Test Strategy:
   • Default to an end-to-end test. If the testing config's Test Writing section references a skill, invoke it; otherwise read an existing end-to-end test in the repo and follow its patterns.
   • Fall back to a unit test only if the test strategy's "impossible" criteria genuinely apply. In autonomous mode you do not have a user gate, but you MUST cite the specific criterion in the MR/PR body. "Difficult" or "inconvenient" is not a valid reason — discard the hypothesis instead.
3. Run the test following the testing config's Test Framework section (use whatever runner or skill it references for running e2e tests) and confirm it fails for the right reason. Save the failing test output (stdout + stderr, or at least the failing assertion and traceback) to your evidence log — it goes in the MR/PR body. If the test passes, it does not capture a real bug — discard the hypothesis.
4. If the test fails for an unrelated reason (setup / infrastructure): fix the setup. If the testing config has a Test Debugging section, follow it. Do not give up on a hypothesis just because the test harness misbehaved.

At the end of Phase A2 you have a set (possibly empty, possibly one, possibly several) of proven bugs, each with a failing test, a before-screenshot (if UI-visible), and saved failing-test output.

Outcome decision after A2:

• Proven bug set non-empty → outcome is REPRODUCED. Proceed to A3.
• Proven bug set empty AND you found evidence on main that an existing commit/MR addresses the bug → outcome is ALREADY-FIXED. Skip A3–A4.5; take the ALREADY-FIXED branch under Phase A5.
• Proven bug set empty AND the symptom does not manifest at all on main (no existing fix found either) → outcome is STALE. Skip A3–A4.5; take the STALE branch under Phase A5.
• Proven bug set empty AND the description was too vague to drive reproduction → outcome is UNREPRODUCIBLE. Skip A3–A4.5; take the UNREPRODUCIBLE branch under Phase A5.

Do not push, commit fixes, or open an MR in any non-REPRODUCED outcome. Do not invent a bug to fix.