Bug report template in Markdown: steps someone can repeat

A bug report template helps you write a problem down in one short Markdown file, so someone else can see the problem for themselves. The file lists what you did, step by step, what you expected, and what happened instead, so the person looking into the bug can make it happen on their own computer.

Here you get the template, the role of each part, a filled-in sample from an invented company, and tips on writing steps. Whatever editor you write plain text in will do, and nothing needs installing.

Why write a bug report

A bug report is a single .md file describing one problem well enough for another person to repeat it. You write it before the fix, for whoever will look into the bug. So the person looking into the bug has what they need, this template asks for the steps, the input and what you saw.

The template here belongs to this post, so drop or rename any part that doesn't suit your bugs.

A bug report comes before the fix and aims to make the problem happen again, while a postmortem comes after the fix and looks back at the event, its causes and the work that follows.

The bug report template

Copy the block into an empty .md file and write over each placeholder with details from your bug. Each part sits under its own heading, and the part called Where it happened holds short labeled lines.

# Bug: a few words that name the problem

## Summary

One sentence: what you did and what went wrong.

## Steps to reproduce

1. The first action, starting from a known state.
2. The next action.
3. The action where the problem shows up.

## Expected

What you thought would happen after the last step.

## Actual

What happened instead, as it appeared.

## Where it happened

Computer and system: the computer and its current system
Version or date: the copy of what you ran, by version or date
Input: the file or data you used

## Error text

Paste any error message here, word for word.

## Notes

What you already tried, any guess about the cause, and who ran
the steps, on which computer, and what each run showed.

What each part holds:

• Title. The first line, "Bug:" plus a few words that name the problem, such as "reminder date is one day early".
• Summary. One sentence on what you did and what went wrong.
• Steps to reproduce. Numbered actions, in order, from a known starting point to the moment the problem shows up.
• Expected. What you thought would happen after the last step.
• Actual. What happened instead. Write the output or message as it appeared, with no guess about the cause.
• Where it happened. Short labeled lines for the computer and system, the version or date of what you ran, and the input you used.
• Error text. Any error message, copied word for word. In the file, pasted error text goes in a code block.
• Notes. What you already tried, any guess about the cause, and a line for each run of the steps.

The steps are a numbered list. If yours restart at 1 or split around a pasted block, the numbered list guide explains what makes a list count from 1 again and how to indent content under a step. For the error text, the guide to code blocks covers writing a fenced block and naming its language.

Sample bug from Doe Holdings

This copy of the template has one bug written in. The names in it are invented: Doe Holdings, Jane Doe, John Doe. The bug is made up as well.

# Bug: reminder date is one day early

## Summary

Jane Doe ran the reminder script for a task due on 2026-10-22,
and the date in the output was 2026-10-21.

## Steps to reproduce

1. Open tasks.md in the Doe Holdings shared folder.
2. Add the line "Pay office rent, due 2026-10-22".
3. Save tasks.md.
4. Run the reminder script on the work laptop with tasks.md as input.

## Expected

Output: Pay office rent, remind on 2026-10-22

## Actual

Output: Pay office rent, remind on 2026-10-21

## Where it happened

Computer and system: the work laptop, its current system
Version or date: the copy of the script from 2026-10-20
Input: tasks.md with the one line from step 2

## Error text

None. No error message appeared.

## Notes

Jane Doe ran the steps three times on 2026-10-21 on the work
laptop and saw 2026-10-21 on all three runs. John Doe ran the same steps
on his own laptop the same day and saw 2026-10-22.

Read the Expected and Actual lines together. Both start with "Output:", so the date is the one part that differs. The Notes add one more clue: on John Doe's laptop, the same steps gave the due date itself.

Writing steps someone can repeat

The goal of this template is steps that someone else can follow cold and still reach the same problem. These tips come from the template and the sample:

• Start from a known state. Step 1 of the sample opens one named file, tasks.md, so the person repeating the steps starts where Jane Doe started.
• Put one action in each step. Each numbered step in the sample does one thing: open, add, save, run.
• Write inputs out in full. Step 2 quotes the exact line Jane Doe typed, and the Input label names the file.
• Match Expected and Actual. The sample writes both as "Output:" lines, so the gap between them sits in one place.
• Record each run. For a bug that happens on some runs and not others, this template puts the runs in Notes: who ran the steps, on which computer, and what they saw. The sample's Notes list Jane Doe's three runs and John Doe's one run.
• Keep guesses in Notes. The template's Actual part holds only what happened, and the sample's Actual line is the output and nothing else.

Naming bug files and keeping them

As this post sets it up, bug files live in a bugs/ folder in your project, one file per bug, named by the date you found it and a short phrase, for example bugs/2026-10-21-reminder-date-one-day-early.md. In the sample, that date matches the day of Jane Doe's runs in Notes.

On the name itself, the guide to naming Markdown files has sections on lowercase names, hyphens in place of spaces and dates that lead with the year. Once the bug is fixed, leave the file where it is, under the same name.

If the fix calls for a longer account of what went wrong and why, start from the postmortem template.

Where Sashmark fits

Sashmark will be both a reader and an editor for Markdown on desktop computers, meant for people whose Markdown comes from AI agents. Today there's nothing out to try, because Sashmark is in development. A bugs folder that holds one report file per problem is among the file collections Sashmark is planned for.

See the planned features, the help pages and the roadmap for where each part stands.

Visit sashmark.com.