MarkBack

Appearance

MarkBack Format ​

MarkBack stores content and feedback together in a compact, human-writable record. The canonical, authoritative spec is rendered on-site in MarkBack V2 Specification.

Record Anatomy ​

A record contains:

  • Optional headers (@id, @reply-to, @by, @tag, @input, @file)
  • Optional inline content
  • A required feedback line starting with <<<

Content vs feedback

Everything before <<< is content (or references). Everything after <<< is feedback.

Feedback rules

Feedback is single-line by default. For multi-line feedback, use the fenced form: <<< """ opens the block, and a line containing only """ closes it.

Optional ID behavior

@id is optional. If missing, the record can still be used, but linters warn because the record has no explicit identifier.

Annotated Examples ​

Single Record (Inline Content) ​

mb
@id prompt-001

Write a haiku about programming.
<<< quality=good; creativity=high
  • Blank line is required before inline content.
  • Feedback is a single line after <<< .

Multi-Record File ​

mb
%markback 2

@id item-001

First piece of content here.
<<< positive
---
@id item-002

Second piece of content.
Multiple lines are fine.
<<< negative; reason=unclear
---
Third item has no ID.
<<< neutral
  • Records are separated by --- on its own line.
  • The third record is valid without @id.

Sidecar Mode ​

content.txt

text
The actual content goes here.

content.txt.mb

mb
@id content-001
<<< approved; reviewer=alice
  • Sidecar files contain only headers and feedback.
  • @file is implicit (the content file).

External Content Reference ​

mb
@id asset-123
@file ./assets/prompt.txt
<<< approved; topic=summary
  • @file references external content.
  • In V2, @file and inline content can coexist (@file is provenance, inline content is snapshot).

Generated Content with Input ​

mb
@id generated-image-001
@input ./prompts/beach-sunset.txt
@file ./images/generated-beach.jpg
<<< accurate; matches prompt well; quality=high
  • @input references the input that produced the content (e.g., a prompt).
  • Useful for LLM-generated images, text, or other derived content.

Attributed Feedback ​

mb
@id review-001
@by alice

Write a function to calculate factorial.
<<< approved; clarity=high
  • @by attributes the feedback to a specific reviewer or annotator.
  • Useful for multi-reviewer workflows and audit trails.

Tags ​

mb
@id item-001
@tag training positive-examples batch-2024-03
@file ./data/example.txt
<<< approved
  • @tag assigns space-separated tags for categorization.
  • Multiple @tag lines in the same record are merged.

Threaded Replies ​

mb
@id c1
@file ./login.py:42 <<< this branch never fires

@id c2
@reply-to c1
@file ./login.py:42 <<< it does -- covered by test_login_edge()
  • @reply-to references the @id of another record in the same file.
  • Threading is reconstructed by walking @reply-to chains.

Multi-Line Feedback ​

mb
@id c1
@file ./login.py:42
<<< """
This branch looks dead, but I want to double-check before
suggesting removal -- can you point me at any tests that
exercise it?
"""
  • Use <<< """ to open a fenced block and """ on its own line to close it.
  • Single-line feedback remains the default for short annotations.

Multi-Segment Sections ​

mb
@file ./essay.txt

the lazy fox
<<< awkward

weak ending
<<< needs punch

dragging middle paragraph
<<< trim this
  • Multiple records share the same @file without repeating it.
  • A --- separator ends the section.

Compact Label Lists ​

For many external files, use compact, single-line records:

mb
@file ./images/cat.jpg <<< positive; animal=cat
@file ./images/dog.jpg <<< positive; animal=dog
@file ./images/blurry.jpg <<< rejected; too blurry to classify
  • No --- separators are needed between compact records.

Sweep Pattern ​

Declare coverage so absence of a record is meaningful:

mb
%markback 2
%scope correctness style
%covers ./gen/batch3/*.txt

@file ./gen/batch3/file2.txt <<< style; tone is off

Files matching %covers with no record are implicitly clean for all %scope items.