DEV Community

黎辰悦
黎辰悦

Posted on

A Reproducible Prompt Workflow for Multi-File Bug Fixing (Free Generator Included)

#ai #playwright #webdev #productivity

Multi-file bug fixes go wrong in a very predictable way: the agent starts editing too early, touches unrelated files, and you end up with a messy change you can’t review or reproduce.

This post shares a repeatable prompt workflow you can reuse for multi-file fixes:

Recon → Plan → Patch → Verify

And yes — I built a tiny free tool to generate this kind of prompt pack automatically.

Project home: https://devstral2.org

Free generator: https://devstral2.org/tools/devstral2-prompt-pack.html

Why multi-file bug fixing is harder than it looks

Multi-file bugs usually span boundaries:

  • page templates / layout wrappers
  • typography + global CSS rules
  • content rendering (Markdown/prose styles)
  • build/deploy differences and caching

Agents fail here when they "just start editing" before understanding how the UI is composed.

The workflow (Recon → Plan → Patch → Verify)

1) Recon (Repo reconnaissance)

Goal: understand the minimum set of files involved.

Ask the agent to:

  • locate the entry point(s)
  • list candidate files with 1-line reasons
  • form a root-cause hypothesis before editing anything

2) Plan (Minimal change plan)

Goal: define the smallest patch that meets acceptance criteria.

Require:

  • file list + why
  • patch steps (by file)
  • acceptance criteria + verification steps

3) Patch (Step-by-step edits)

Goal: keep diffs auditable.

Require:

  • edits grouped by file
  • “what changed” + “why”
  • avoid unrelated refactors

4) Verify (Proof it works)

Goal: provide evidence.

  • manual checks
  • quick regressions
  • (optional) tests/build commands

Real bug scenario (from devstral2.org)

While adding blog post detail pages to devstral2.org, I hit a real UI bug:

  • Bug: the blog detail content looked too gray / low contrast on the dark theme, so parts of the article were hard to read.
  • Expected behavior: the blog detail page should match the homepage’s typography/layout style (consistent font, contrast, spacing).
  • Verification: after the fix, I refreshed the page and confirmed the entire blog detail content is clear.

In practice, the minimal fix was:

make the blog detail wrapper reuse the homepage container/typography classes (instead of rewriting global CSS).

Copy-paste Prompt Pack (example)

Use this prompt pack for the same category of bug:

Prompt Pack: Multi-file bug fixing (low-contrast blog detail page)

  1. You are an AI engineer working on a dark-themed website (devstral2.org).
  2. Bug: blog post detail content is too gray/low-contrast; parts are hard to read.
  3. Goal: make the blog detail typography/layout consistent with the homepage; ensure readability.
  4. Constraints: minimal diffs; avoid broad refactors; don’t change unrelated pages; keep design consistent.

Recon (before edits):

  1. Locate where the blog detail page is rendered (template/component/html).
  2. Identify the homepage wrapper/container + typography classes.
  3. Compare blog detail wrapper vs homepage wrapper.
  4. Find which styling rule causes low contrast (color/opacity/prose/text class/CSS vars).
  5. List candidate files to change with 1-line reasons.

Plan (minimal fix):

  1. Propose the smallest patch: blog detail wrapper reuses homepage container/typography structure.
  2. Specify exact files to edit and why.
  3. Define acceptance criteria + regression checks.

Patch:

  1. Update the blog detail wrapper/container classes to match homepage.
  2. Keep changes scoped; no unrelated formatting refactors.
  3. Explain changes PR-style (what/why).

Verify:

  1. Refresh blog detail page and verify readability.
  2. Check headings/paragraphs/links (and code blocks if present).
  3. Quick regression: open homepage + at least one tools page.

Output format:

  1. Root cause hypothesis
  2. Files to change
  3. Patch steps (by file)
  4. Verification checklist

Quick acceptance checklist

  • [ ] Recon done before edits (candidate files listed)
  • [ ] Plan includes acceptance criteria
  • [ ] Changes are minimal and scoped
  • [ ] Verify includes refresh + quick regressions
  • [ ] No unrelated pages were impacted

If you try this workflow, which step helps you the most — Recon, Plan, Patch, or Verify?

Project home: https://devstral2.org

Free generator: https://devstral2.org/tools/devstral2-prompt-pack.html

Top comments (0)