wc-review

Review Comments Processor

Process inline <!-- --> review comments in a Markdown file. Understand the full document, apply each editorial instruction, and deliver the edits.

Arguments

• $1 — Path to the markdown file with review comments

Configuration:

• Obsidian vault: /home/tomic/Documents/Vault
• Obsidian port: 27125
• Guides directory: /home/tomic/Sync/clients/writing-companion.io/guides

Comment Syntax

Skip structural HTML comments (<!-- prettier-ignore -->, <!-- markdownlint-disable -->, etc.).

Instructions

1. Read the full file

Read $1 completely. Understand the document's structure, tone, and purpose before processing any comments.

2. Detect content type

Determine the article type for loading the appropriate style guide:

1. Check YAML frontmatter for a type: field
2. Check the file path for keywords: blog, newsletter, linkedin, youtube (or short forms: -yt, -li, -nl)
3. If neither works, use "default" (no style guide loaded)

If a type is detected, read the style guide from /home/tomic/Sync/clients/writing-companion.io/guides/style/{type}.md. If the file doesn't exist, proceed without it.

3. Scan for review comments

List all <!-- --> comments that contain editorial instructions. Report: "Found N review comments."

3b. Resolve range-targeted comments

For each comment matching <!-- @-{N} #"{fingerprint}" instruction -->:

1. Find the comment's byte position in the raw file text.
2. Count back N characters from the comment start (skip the newline immediately before <!--). The resulting span is the target text.
3. Verify: the extracted text should start and end with the fragments in the fingerprint (split on ... if abbreviated).
4. If the fingerprint does NOT match at the calculated position, search the surrounding ~500 characters for text matching the fingerprint fragments. Use the match as the target instead.
5. The old field in the replacement payload spans from the target start through the end of the comment markup (including the <!-- ... --> and the newline before it).
6. The new field is the rewritten target text with the comment removed.

4. Check Obsidian availability

Use Bash to check if Obsidian's buffer edit plugin is running:

curl -sf http://127.0.0.1:27125/health

If it returns 200, use Obsidian mode. Otherwise, use direct mode.

5a. Obsidian Mode

Process all comments and build a JSON payload. For each comment:

1. Identify the affected text:
   • For <!-- instruction -->: the paragraph preceding the comment
   • For <!-- "target text": instruction -->: the quoted text within the surrounding paragraph
   • For <!-- @-{N} #"..." instruction -->: the N characters preceding the comment (resolved in step 3b)
2. Process the instruction:
   • Rewrite ("rewrite", "make shorter", "more conviction"): rewrite the text following the instruction and style guide. Same idea, better words.
   • Delete ("cut", "remove", "delete"): the replacement is empty string.
   • Specific edit ("change X to Y"): apply the exact substitution.
   • Question (?): do not edit — collect answer for summary.
   • Merge ("merge with above/below"): produce two replacements — one with merged content, one deletion.
   • Move ("move to section X"): produce two replacements — one deletion, one insertion at target.
   • Split ("split into two paragraphs"): one replacement with blank line inserted.
3. The original (called old in the payload) must be byte-identical to the source text — including whitespace, line breaks, and the comment markup itself. The Obsidian plugin does verbatim search with lastIndexOf. If it doesn't match exactly, the replacement is silently skipped.
4. The replacement (called new) is the clean text with the comment removed.

Convert the absolute file path to vault-relative by stripping the vault prefix (/home/tomic/Documents/Vault/).

Send via Bash:

curl -sf -X POST http://127.0.0.1:27125/buffer/replace \
  -H "Content-Type: application/json" \
  -d '<json payload>'

Parse the response and report: "N applied, M skipped."

5b. Direct Mode (Obsidian unavailable)

Process comments and apply edits directly using the Edit tool:

1. Process comments in reverse order (bottom-to-top) to preserve line positions.
2. For each comment, use the Edit tool with the exact original text (including comment markup) as old_string and the clean replacement as new_string.
3. For questions: skip editing, just collect the answer.

Report each change made.

6. Summary

Print a numbered summary:

1. For each edit: brief description of what changed (before → after, abbreviated)
2. For each question: the question text and your answer
3. Total: N edits applied, M questions answered

Rules

• Read the full document first. Every edit must be informed by the full context.
• Same idea, better words. Rewrites preserve the author's intent. Never invent new content.
• Byte-identical originals. In Obsidian mode, the old field must exactly match the source. This is the most critical requirement.
• Process ALL comments. Do not skip any review comment.
• Preserve everything else. Text without comments must remain untouched.
• Match the author's voice. If a style guide is loaded, follow it. If not, match the existing voice in the document.
• Questions are read-only. Never edit text near a ?-prefixed comment.
• Conflicting comments. If two comments on the same paragraph conflict, process the first and report the second as skipped with explanation.