Ask an agent to explain a Markdown file without revising it

You have a Markdown file written by an agent. You can read its sentences, but the subject is unfamiliar. A passage names an idea you cannot yet picture, and the following paragraph assumes that idea makes sense to you.

Before requesting simpler prose in the document, decide what you need from the conversation. You may want someone to teach the subject while leaving the document exactly as you received it. The explanation belongs elsewhere; the file remains the text you intend to read.

The imagined reader is Jane Doe; her Doe river passage is invented too. The passages describe a reading situation only. For readers new to .md, this file-type introduction explains the ending.

Identify the document you want to keep intact

Begin with the particular file already in front of you. Naming it gives the discussion a definite document, even if the conversation contains other writing. Include its folder if several documents have that name.

Here is the invented passage Jane Doe is reading in Doe-river.md:

The Doe river has braided channels. Water divides around gravel patches and joins again farther downstream.

She identifies Doe-river.md as the document for discussion and states that its wording should stay as it is. She has not requested a new document or changes to this one.

Keep that intention explicit in your own request. A wish to understand the subject leaves the desired form of the answer unstated. Say that the existing document is to remain intact before describing what needs explaining.

Describe the idea that interrupts your reading

Point to the concept, then describe your difficulty in ordinary words. You need not know its specialist vocabulary before asking about it. Naming the passage and describing the part you cannot picture gives the teaching a starting point.

For Jane Doe, braided channels is the unfamiliar idea. She can picture water dividing around gravel, but she cannot picture how divided channels join again downstream. That is the question she describes after identifying Doe-river.md and stating that it should stay intact.

A broad request about the entire file would leave this difficulty unspoken. Asking for shorter sentences would request a different kind of work. What Jane Doe wants to understand is the dividing and rejoining of the river channels described in the passage.

Your description can acknowledge the part you grasp without pretending the rest is clear. An unfamiliar subject does not make its paragraph defective.

Request teaching in a separate response

Specify where the explanation should appear. Ask for teaching in the conversation, apart from the Markdown document, with no edits to that document. Describe the desired explanation in prose rather than writing replacement paragraphs for the file.

Jane Doe requests an explanation of the dividing and rejoining channels in a separate response. She includes no change to Doe-river.md in that request. Her question concerns the river's channels, with the document retained as received.

Keep the request focused on that idea. You could ask for an explanation that begins with the part you already grasp and proceeds to the part you find unfamiliar. That describes how you want the teaching arranged without specifying new wording for the document.

The quoted river passage above is ordinary prose. The code-block guide describes another enclosure for text; no executable material belongs in this request.

Read the teaching apart from the document

When you have an explanation to read, keep it in its separate response. Read it as teaching about the subject. Resist inserting useful sentences into the document merely because they make sense to you now.

Jane Doe reads the explanation in the separate response and leaves it there. She does not paste it into Doe-river.md. The river paragraph and the teaching remain separate texts.

That separation matters when you return. You want to encounter the document's own wording with the subject explained, rather than encounter a new paragraph in place of the one that prompted your question.

If the explanation leaves the same concept unclear, describe the remaining difficulty in the conversation. Keep that further teaching outside the document too. There is still no need to turn an unfinished explanation into an editing request.

Confirm the file stayed intact, then read on

Before continuing, establish for yourself that the document is unchanged. Compare all its text against what you had before asking. A statement asking for no edits expresses your intention; it cannot establish the file's condition afterward.

Jane Doe compares Doe-river.md with its earlier text and finds it unchanged. Only then does she reread the river paragraph and continue into the prose that follows, keeping the separate explanation outside the file.

Keep the same document in view when returning. The choice of a Markdown file name deserves thought; in this situation, use the name to return to the intended document.

If the comparison shows altered text, the unchanged-file condition is unmet. Settle that before treating your next read as a return to the original document. The purpose of requesting teaching was to bring an explanation to your reading while retaining the file you received.

Where Sashmark fits

For desktop use, Sashmark has Markdown reading plus editing planned for v1 and remains in development. Its app includes no AI.