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

> Discover how the Source Reviewer SubAgent in beautiful-article audits source files, generating a review report for complex content. Learn the technical details.

- Repository: [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills)
- Tags: deep-dive
- Published: 2026-08-28

---

**The Source Reviewer SubAgent performs a diff-style audit between original source files and the generated [`source/source.md`](https://github.com/ConardLi/garden-skills/blob/main/source/source.md), emitting findings to [`review/source-review.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/source/source.md) by the **source-to-markdown** pipeline implemented in [`scripts/source-to-markdown.py`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/references/source-to-markdown.md) (lines 108-116), the system upgrades to the independent SubAgent only when [`extraction-notes.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/references/harness.md)).

## Implementation Details and Code Examples

The SubAgent follows a strict contract: **input → diff → [`review/source-review.md`](https://github.com/ConardLi/garden-skills/blob/main/review/source-review.md) → main-agent fixes**.

```python

# 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:

```python

# 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`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/extraction-notes.md).
- It performs line-by-line diffs between `source/original.*` and [`source/source.md`](https://github.com/ConardLi/garden-skills/blob/main/source/source.md) to detect silent losses.
- Findings are written to [`review/source-review.md`](https://github.com/ConardLi/garden-skills/blob/main/review/source-review.md), part of the skill’s long-term memory per [`harness.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/extraction-notes.md), as defined in [`references/source-to-markdown.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/review/source-review.md). According to [`references/harness.md`](https://github.com/ConardLi/garden-skills/blob/main/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`](https://github.com/ConardLi/garden-skills/blob/main/source/source.md) based on the SubAgent’s audit report.