Skip to main content
Watchfire
Task template

Investigate and report (no code changes)

Diagnosis only — the artifact is a Markdown report, not a patch.

Sometimes you need to know what's wrong before you decide how to fix it. Without an explicit 'no code changes' rule, the agent will produce a half-baked fix and call it diagnosis. This template makes the artifact a structured Markdown report and makes a clean `git diff --stat` a literal acceptance criterion.

When to reach for this template.

  • You're not yet sure whether the bug needs a fix, a refactor, or a product decision.
  • You want the diagnosis written down before anyone touches the code.
  • The next step depends on what the agent finds — and you'd rather scope the fix as a follow-up task.
  • You want file:line references you can hand to the next agent (or human).

The template.

Drop this into .watchfire/tasks/<n>.yaml, edit the prompt and acceptance_criteria to match your repo, and let the daemon run it.

task_id: invest07
task_number: 7
title: "Diagnose intermittent 500s on POST /api/orders since deploy abc123"
prompt: |
  Since commit `abc123` we see intermittent 500s
  on POST /api/orders, roughly 1 in 30 requests.
  The Sentry trace points at
  `services/orders.ts:142`. Reproduce locally if
  you can, identify the root cause, and write
  your findings to `INVESTIGATION.md` at the
  repo root.

  This is a diagnosis task, not a fix task. Do
  NOT change any code outside of
  `INVESTIGATION.md`. The follow-up fix will be
  a separate task once we agree on the proposed
  approach.

  `INVESTIGATION.md` must include sections:
  - _Symptom_ — what users see.
  - _Reproduction_ — exact commands that
    reproduce locally (or "could not reproduce"
    with what you tried).
  - _Root cause_ — the actual mechanism, with
    file:line references.
  - _Proposed fix_ — the smallest plausible
    change, as a bulleted spec for a future task.
  - _Open questions_ — anything you couldn't
    resolve without product input.
acceptance_criteria: |
  - `INVESTIGATION.md` exists at the repo root
    with the five sections above.
  - The Root cause section names at least one
    specific `file:line` location.
  - No code changes outside `INVESTIGATION.md`
    (verify with `git diff --stat`).
  - The file is valid Markdown (renders cleanly
    in GitHub preview).
  - `npm run lint` passes (no incidental
    formatting changes).
status: ready

Common pitfalls.

The shapes of failure most often seen on this kind of task — and the way this template hedges against each.

  • Forgetting to forbid code changes. Agents default to fixing things; without an explicit 'no diff outside the report file' criterion, you get an investigation and a half-finished fix.
  • Vague output shape. 'Write up what you found' gives you a wall of prose; a numbered section list gives you a report you can act on.
  • Letting the report paraphrase instead of cite. Require `file:line` references for every claim about behaviour.
  • Skipping the 'could not reproduce' branch. Without it, the agent will invent a repro that doesn't exist rather than admit the bug is non-deterministic.

Pair it with a playbook.

These use-case playbooks lean on tasks shaped like this one.

Build your own.

This template is a starting point. Fill in a form to draft your own task in the playground — or read the full task schema to learn every field the daemon understands.

Ready to go

Get started with Watchfire

Install in seconds. Define tasks. Let agents ship code for you.

Download for macOS

Available for macOS, Linux, and Windows

install
# Install via Homebrew (macOS)
$brew tap watchfire-io/tap
$brew install --cask watchfire-io/tap/watchfire
# Set up your project and go
$watchfire init
$watchfire task add "Build the login page"
$watchfire start --all

Includes GUI, CLI, and daemon. Also available via Homebrew.