How the Source Reviewer SubAgent Works in beautiful-article: A Technical Deep Dive

The Source Reviewer SubAgent performs a diff-style audit between original source files and the generated source/source.md, emitting findings to review/source-review.md only when complex or low-confidence materials require verification.

The Source Reviewer SubAgent is a specialized fidelity gatekeeper within the beautiful-article skill in the ConardLi/garden-skills repository. Unlike the main Agent’s inline validation, this SubAgent operates independently to catch silent data loss in complex documents. It executes only when the source-to-markdown pipeline flags uncertainty, ensuring that PDFs, DOCX files, and other intricate sources transform accurately before styling begins.

Architectural Flow of the Source Reviewer SubAgent

Source Ingestion and Normalization

All raw inputs—URLs, PDFs, DOCX files, Markdown, and screenshots—are first normalized into a single Markdown file at source/source.md by the source-to-markdown pipeline implemented in scripts/source-to-markdown.py.

Phase 1 Self-Check

Before invoking the SubAgent, the main Agent runs an inline checklist defined in references/source-to-markdown.md. This 5-point verification examines completeness, structure, key carriers (tables, code, formulas, citations), noise levels, and uncertain items. This step does not create a review file and serves as a lightweight first filter.

Trigger Conditions for SubAgent Activation

According to references/source-to-markdown.md (lines 108-116), the system upgrades to the independent SubAgent only when extraction-notes.md records a low-confidence or complex flag. This conditional invocation ensures the SubAgent runs only when the cost of cold-start latency is justified by the risk of extraction errors.

Diff Execution and Result Persistence

Once triggered, the SubAgent reads both source/original.* and the generated source/source.md. It performs a line-by-line diff to identify missing tables, paragraphs, footnotes, code blocks, images, structural collapses, or encoding corruption. Rather than rewriting content, the SubAgent emits only differences and required fixes to review/source-review.md, which the harness documentation identifies as part of the skill’s long-term memory (lines 24-27 in references/harness.md).

Why the Source Reviewer SubAgent Exists

Silent Loss Detection

Certain fidelity losses—such as a table silently reduced to a single line—cannot be detected by scanning the generated Markdown alone. By diff-ing against the original files, the SubAgent catches these "silent" omissions that the Phase 1 self-check might miss (as noted in source-to-markdown.md, lines 99-107).

Performance Guardrails

The SubAgent acts as a performance guardrail by executing only for complex sources. Simpler inputs skip this step, keeping the pipeline fast while reserving intensive review for documents where extraction uncertainty is high.

Deterministic Memory

The review output persists as part of the skill’s long-term state. By writing findings to review/source-review.md, the system enables reproducibility across long sessions and allows the main Agent to reference previous audit results (lines 14-27 in references/harness.md).

Implementation Details and Code Examples

The SubAgent follows a strict contract: input → diff → review/source-review.md → main-agent fixes.

# Conceptual implementation: Main Agent deciding to launch the SubAgent

if "low-confidence" in extraction_notes:
    subagent = SourceReviewerAgent(
        original_path="source/original.pdf",
        generated_path="source/source.md"
    )
    review = subagent.run_diff()
    write_file("review/source-review.md", review)

After the SubAgent completes, the main Agent consumes the review file:

# Consuming the review in subsequent phases

review = read_file("review/source-review.md")
if "FAIL" in review:
    apply_fixes(review)  # Main Agent patches source/source.md

The actual orchestration is handled by the skill’s internal harness, but these snippets demonstrate the essential data flow. The SubAgent never modifies source/source.md directly; it only provides the audit trail that gates progression to styling and layout phases.

Summary

• The Source Reviewer SubAgent activates only for complex or low-confidence sources flagged in extraction-notes.md.
• It performs line-by-line diffs between source/original.* and source/source.md to detect silent losses.
• Findings are written to review/source-review.md, part of the skill’s long-term memory per harness.md.
• The main Agent must apply fixes before proceeding; the SubAgent serves as a read-only fidelity gatekeeper.
• This architecture balances accuracy with performance by skipping heavy review for simple sources.

Frequently Asked Questions

When is the Source Reviewer SubAgent triggered?

The SubAgent triggers only when the ingestion pipeline marks a source as complex or low-confidence in extraction-notes.md, as defined in references/source-to-markdown.md (lines 108-116). Simple sources undergo only the inline 5-point self-check.

What file does the Source Reviewer SubAgent generate?

All findings are written to review/source-review.md. According to references/harness.md (lines 24-27), this file is part of the skill’s persistent long-term memory, enabling reproducible audits across sessions.

How does the SubAgent differ from the main Agent's self-check?

The main Agent runs a lightweight 5-item inline checklist during Phase 1 that does not persist output. The Source Reviewer SubAgent is an independent process that performs detailed diffs against original files and writes structured findings to disk, acting as a heavy-duty gate for complex materials.

Can the Source Reviewer SubAgent modify the article directly?

No. The SubAgent is strictly read-only regarding content modification. It identifies omissions and errors but emits only repair instructions; the main Agent must execute the actual fixes to source/source.md based on the SubAgent’s audit report.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}