Commentary
Open appTry Commentary
Markdown review guide

Review the document first. Inspect the diff when it answers a specific question.

A Markdown pull request is both source code and a reader-facing artifact. Start by understanding the complete document, then use the diff to answer precise questions about what changed.

  • Rendered document
  • Section comments
  • Source diff
  • GitHub authority
Open the Markdown sampleOpen a GitHub review
human review workflow
Human approval
Implementation plan review
## Rollout and rollback

Deploy progressively, monitor the acceptance signal, and stop when the agreed threshold is crossed.

Structured revision context ready
Reference workflow

Turn human attention into a repeatable stage.

The artifact, feedback, revision, and approval state stay explicit from start to finish.

  1. 01

    Open the public or authenticated pull-request URL in Commentary.

    Start from an explicit artifact and named owner.

  2. 02

    Read the rendered document from beginning to end.

    Keep the current state and unresolved context visible.

  3. 03

    Attach comments to the relevant section or selected text.

    Keep the current state and unresolved context visible.

  4. 04

    Use Raw or Changes when source-level evidence matters.

    Keep the current state and unresolved context visible.

  5. 05

    Include subject-matter reviewers without requiring diff fluency.

    Keep the current state and unresolved context visible.

  6. 06

    Return unresolved context to the author or agent.

    Keep the current state and unresolved context visible.

  7. 07

    Submit provider feedback through the authenticated Git workflow.

    The next stage begins only after verification.

Why Markdown-heavy diffs are hard

Reflowed paragraphs, moved sections, generated tables, and broad rewrites can make a coherent document look like unrelated changed lines. Reviewers spend energy reconstructing the final reading experience.

When the raw diff remains essential

Use the diff for exact deletions, changed links, hidden front matter, formatting syntax, and suspiciously broad source transformations. Document and diff views complement each other.

How rendered review changes behavior

Reviewers comment on claims, instructions, structure, and reader outcomes. Section-level comments keep those decisions meaningful even when an agent rewrites surrounding lines.

Continue the workflow

Use the next page that matches the artifact or boundary you need to review.

Markdown Review

See the complete product workflow.

Read next

Diffs Are Not Documents

The case for complementary review surfaces.

Read next

Security and access

Understand provider, preview, token, and human approval boundaries.

Review boundaries
Human review, made explicit

Put the workflow into practice.

Review Markdown-heavy pull requests as readable documents while keeping GitHub authoritative and source diffs available.

Open the Markdown sampleOpen a GitHub review