Markdown troubleshooting guide template: follow the symptom

A troubleshooting guide starts with something that has gone wrong. The reader chooses a symptom, looks at a file or runs a named test, then takes the branch that matches the result. This Markdown troubleshooting guide template gives that diagnosis a repeatable shape without requiring everyone to take the same route.

An empty block comes first, followed by a filled guide for a fictional Doe Holdings project. Both use paragraphs beneath headings. The choice happens in the wording: if this appears, try this remedy; if something else appears, take the other branch.

A diagnosis begins with a symptom

Name what the reader can see before proposing a cause. "The passage is absent" is a symptom. "The file was never saved" is one possible explanation, which needs evidence before it earns a place in the remedy.

A linear task leads toward one known end. A defect report gives another person enough detail to repeat a fault. Here the reader is trying to distinguish causes and choose what to do next. A postmortem looks backward after an event; this guide stays beside the reader while the cause is still uncertain.

For background on the file you are opening, read about the .md format explains the file you will be reading. The diagnostic branches below concern the project that owns that file.

The troubleshooting guide template

Replace the angle-bracket text with observations and actions specific to your project. Repeat a symptom section only when it begins with a different visible problem. Give each possible result its own remedy and a way to tell whether that remedy worked.

# Troubleshooting: <project and visible problem>

## Scope and stopping point

This guide applies to <project copy and conditions>. A normal result looks like <observable behavior>. Stop before <action outside the reader's authority>. If no symptom below matches, ask <Doe placeholder name> with <evidence needed to investigate>.

## Symptom: <first visible problem>

Read <named file and passage> or run <exact diagnostic action>. Compare what appears with <expected text or behavior>.

If the observed result is <result A>, use <remedy A>. Repeat <same observation>. If <expected behavior> appears, this branch has resolved the symptom. If it does not, stop and give <Doe placeholder name> the before and after results.

If the observed result is <result B>, use <remedy B>. Repeat <same observation>. If <expected behavior> appears, this branch has resolved the symptom. Otherwise, stop and give <Doe placeholder name> the before and after results.

If neither result appears, do not choose the nearest one. Record the exact result and ask <Doe placeholder name> before changing anything else.

## Symptom: <second visible problem>

Read <named file and passage> or run <exact diagnostic action>.

If <result C> appears, use <remedy C> and repeat <same observation>. If the symptom persists, stop and ask <Doe placeholder name> with both results.

If <result D> appears, use <remedy D> and repeat <same observation>. If the symptom persists, stop and ask <Doe placeholder name> with both results.

For any other result, stop and ask <Doe placeholder name> with the exact text observed.

## Observations from one attempt

On <date>, <Doe placeholder name> used <project copy>, chose <symptom> and read or ran <diagnostic action>. The result was <exact observation>. After <remedy, or no change>, the same observation showed <result>. The unresolved question for <Doe placeholder name> is <question, or none>.

The scope paragraph limits where a diagnosis applies. The symptom heading is the entry point, and the result paragraphs supply the forks. A remedy is incomplete without a second observation: changing a file alone does not establish that the original problem went away.

The stop paragraph matters when the guide runs out of evidence. An unexpected result is a reason to involve the named person, rather than force the result into a branch that does not fit.

A filled guide for Doe Holdings

In this invented diagnosis, Jane Doe names the person and Doe Holdings names the company; both names are placeholders. Nothing described here happened: the project, files and observations were invented for this sample. Jane Doe keeps a short equipment-care guide called equipment-care.md; another person sees a saved copy in a reading pane.

# Troubleshooting: Doe Holdings equipment-care guide

## Scope and stopping point

This guide concerns equipment-care.md in the Doe Holdings project folder. The reading pane should show the saved text, with separate paragraphs where the file has blank lines. Jane Doe owns the wording. Stop before changing an instruction about equipment use. If neither symptom matches, ask Jane Doe with the file path and the text visible in the pane.

## Symptom: a passage is absent from the reading pane

Read the path shown for the open file and compare it with the project folder's equipment-care.md. Look for the sentence "Leave the cart beside the storage door."

If the paths differ, the pane is showing another copy. Open equipment-care.md from the project folder and look for that sentence again. If it appears, the missing-passage symptom is resolved. If it remains absent, stop and give Jane Doe both paths and the text visible in the pane.

If the paths match, read the saved equipment-care.md in the editor and look for the same sentence. If the sentence is there, close and reopen the reading pane for that file, then look again. If it appears, the symptom is resolved. If it remains absent, stop and give Jane Doe the path and the sentence as seen in the editor.

If the paths match but the saved file lacks the sentence, do not add it from memory. Ask Jane Doe whether the passage belongs in this copy. If Jane Doe supplies the wording, save that wording in equipment-care.md and reopen the pane. If the passage is still absent, stop and give Jane Doe the saved text and the pane's text. If Jane Doe confirms the passage does not belong, leave the file unchanged; the expectation was incorrect.

If the path cannot be read or the file cannot be opened, stop and ask Jane Doe with the exact text that appeared instead.

## Symptom: two paragraphs appear joined

Read the saved equipment-care.md around "Return the cart." and "Store the key." Look at the line between those sentences.

If there is no empty line between the paragraphs, insert one empty line, save and reopen the reading pane. If the sentences now begin separate paragraphs, the symptom is resolved. If they remain joined, stop and give Jane Doe the saved passage and what the pane shows.

If an empty line already separates the paragraphs, leave the wording alone. Reopen the pane for the same file and compare again. If the paragraphs appear separately, the symptom is resolved. If they remain joined, ask Jane Doe with the file path, the saved passage including its empty line and the pane's text.

If either sentence is absent, this branch does not fit. Use the missing-passage branch if a known passage is absent, or ask Jane Doe whether these are the right paragraphs before editing.

## Observations from one attempt

On 2026-10-23, Jane Doe used equipment-care.md in the Doe Holdings project folder. Two paragraphs appeared joined. Jane Doe read the saved passage and found no empty line between "Return the cart." and "Store the key." After Jane Doe inserted an empty line, saved and reopened the pane, the two sentences began separate paragraphs. No question remained from that attempt.

The first symptom separates a different file path, a stale view and absent wording. Those observations call for different actions. The second symptom turns on a blank line, with an escalation route for a pane that still shows joined paragraphs after reopening.

For the syntax behind that second branch, see how blank lines separate Markdown paragraphs. Keep the project-specific observation in the guide, so the reader does not have to infer which passage the remedy applies to.

Keep the diagnosis and its observed results with the project

Store the reusable guide at troubleshooting/equipment-care.md inside the project folder. Keep dated accounts of attempts nearby, such as troubleshooting/2026-10-23-equipment-care-attempt.md. The stable guide name describes the symptom area; the dated file preserves what happened on one occasion. For naming choices as files accumulate, consult Markdown naming conventions for files.

An account of an attempt needs the file path, the chosen symptom, the exact result, the remedy tried and the observation afterward. Record "no change" when no remedy was safe. Include the unresolved question when handing the diagnosis to Jane Doe or another named owner.

Revise a branch when an observed case establishes a missing condition. Preserve the earlier attempt so a later reader can see why the wording changed. One successful remedy on one copy is evidence for that case; it does not establish a cause for every matching symptom.

Where Sashmark fits

Sashmark has reading and editing as its purpose: a desktop app for Markdown written by your AI agents. With Sashmark in development, nothing is ready for you to try. A troubleshooting guide can sit among the project files you intend to read there.