--- title: "Prioritize blocking findings in agent Markdown review" slug: prioritize-blocking-findings-in-agent-markdown-review excerpt: "Judge known findings against the document's intended use, keep blocking defects apart from optional changes, and bound the revision you request." quickAnswer: "Begin by stating the document's intended use. For each known finding, describe what leaving it unresolved would prevent or misdirect. Treat a defect as blocking when that consequence prevents the intended use. Keep preferences that leave the use intact optional. Ask the author for the particular repair needed, and say which suggestions can wait." keyTakeaways: - "The intended use gives a finding its consequence." - "A blocking defect prevents the document from serving that use." - "An optional change can remain open without preventing that use." - "A bounded request names the needed repair and leaves other work deferred." publishedDate: 2026-10-25 dateModified: 2026-10-25 author: Bobby Huang cluster: A role: post status: published faq: - q: "Does every finding prevent use?" a: "No. Describe what happens if each finding stays unresolved. A preference can be worth keeping while leaving the document usable for its stated purpose." - q: "Can a short phrase be a blocking defect?" a: "Yes. Its length does not settle what it changes for the reader. A few words can misdirect the very choice the document needs to support." - q: "How narrow should the revision request be?" a: "Name the passage needing repair, the consequence to remove, and the use the revised passage needs to support. Leave unrelated suggestions outside that request." related: - what-is-a-md-file --- You have already found problems in an agent's Markdown document. One passage leaves the reader unable to choose. Another could be shorter. Calling both blocking asks the author to treat a preference as a condition of using the document. Make the distinction through consequences. What does the document need to let someone do, and what would each unresolved finding do to that use? The answer determines which repairs belong in the revision request and which suggestions can wait. All Doe people, documents and passages here are invented. Consider the passages as writing; take no action on their imagined work. For an explanation of the extension, read [the .md introduction](what-is-a-md-file.md). ## Give the document a particular use "Make this good enough" leaves the author guessing what good enough permits. Name the reader's task instead. A document meant to support a particular choice needs the information for that choice; a preference about its phrasing needs a separate reason to block it. Consider this invented paragraph about findings already known: > Jane Doe needs Doe-room.md to choose a room for a quiet conversation. Its room descriptions omit whether noise carries through the doors, leaving her unable to choose for that purpose; this omission is blocking. A sentence also calls a room suitable despite describing noise carrying through its door, which could direct her toward a room unsuited to her purpose; this contradiction is blocking. The opening repeats the purpose in different words, but the repetition leaves her choice unaffected; shortening it is optional. The use comes first: choosing a room for a quiet conversation. Keep that purpose in view while considering the omission, the contradiction and the repetition. Their shared presence in one document does not give them the same consequence. For your document, be equally particular about the intended use. If it remains unclear, settle that before calling a finding blocking. Otherwise, you may request a repair for a task the document was never meant to support. ## Describe what leaving the defect open would do In Doe-room.md, the missing account of noise through the doors leaves Jane Doe unable to choose for a quiet conversation. The suitability sentence could then direct her toward a room unsuited to that purpose. Those are different ways for writing to fail its intended use: withholding needed information and steering someone away from the stated purpose. Describe the consequence rather than relying on how forcefully the finding was written. Calling a passage poor leaves two possibilities unresolved: missing information necessary for use, or phrasing you dislike. State what the reader would be unable to decide, or what mistaken choice the passage could encourage. Keep that explanation within what you know. If a consequence is uncertain, ask the narrow question that would settle whether use is prevented. Do not turn an imagined consequence into a required repair simply because it sounds serious. The passages here stay as quoted prose. For a different way to enclose literal text, see [the Markdown code-block article](markdown-code-blocks.md). ## Keep a useful suggestion optional The repeated opening in the invented paragraph leaves Jane Doe's choice unaffected. Shortening it may still be desirable, but the stated use supplies no reason to hold the document for that change. Optional does not mean the finding was mistaken. It means leaving it open does not prevent this use. Keep that distinction explicit so an author can make the needed repairs without treating every preference as compulsory. Nor does a defect become optional because it occupies little space. A short sentence can direct a reader toward an unsuitable choice, while a longer repetition can leave the choice intact. Judge what remains possible with the defect still present. You can defer a suggestion without asking the author to forget it. Say that it lies outside the needed revision. Avoid attaching it to the request with wording that quietly makes it another condition for accepting the document. ## Bound the request around the blocking consequences For the same invented document, Jane Doe writes this request to its author: > Before I use Doe-room.md to choose a room for a quiet conversation, add the missing account of noise carrying through the doors and reconcile the suitability sentence with the noise it describes. Leave shortening the repeated opening for a separate revision; it is optional for this use. The request follows the findings in their original order: the missing account, the conflicting suitability sentence, then the repeated opening. It asks for repairs to the blocking passages and explicitly defers the optional shortening. It does not write the new room descriptions for the author. Bound your own request by the consequence that needs to disappear. Point to the passage, name what it needs to resolve, and state the intended use. A broad demand to rewrite everything gives no such limit and can bury the needed repair beneath unrelated changes. When referring to a document, keep its name attached to the request. For choosing names, consult [the Markdown naming article](markdown-file-naming.md); here, the name identifies the document whose use is being held. Stop expanding the request once it accounts for the known defects that prevent the stated use. The deferred suggestions can remain worthwhile. Their presence does not make them conditions of this revision. ## Where Sashmark fits Markdown reading alongside editing is planned in Sashmark's desktop v1, which is still in development. No AI will run within the app.