# Quality Assurance Strategy for the Beautiful-Article Skill: A Complete Technical Guide

> Discover the quality assurance strategy for the beautiful-article skill. Learn how this technical guide details a rigorous pipeline combining agent self-checks and SubAgent reviews for exceptional article quality.

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

---

**The beautiful-article skill enforces a rigorously staged quality assurance pipeline that combines inline self-checks by the main agent with dedicated SubAgent reviewers, ensuring every generated article meets strict standards for structural completeness, visual coherence, and technical buildability.**

The **beautiful-article** skill in the [ConardLi/garden-skills](https://github.com/ConardLi/garden-skills) repository implements a comprehensive quality assurance strategy designed to produce publication-ready technical articles. This strategy operates across six distinct phases, utilizing both automated self-verification and specialized SubAgent reviewers to enforce five core principles that govern content extraction, component usage, and styling consistency.

## Six-Phase QA Pipeline Overview

The quality assurance strategy for the beautiful-article skill divides the article generation workflow into discrete checkpoints, each with specific validation methods and output artifacts.

### Phase 1 – Source Verification

Every article begins with source material validation. The main agent performs a **5-item inline self-check** directly against the extracted content in [`source.md`](https://github.com/ConardLi/garden-skills/blob/main/source.md) to verify completeness, structural integrity, key media preservation, noise removal, and uncertainty documentation.

For complex or low-confidence sources, the skill invokes a **Source Reviewer SubAgent** that performs a diff check between the `original.*` files and [`source.md`](https://github.com/ConardLi/garden-skills/blob/main/source.md), outputting a detailed review to [`review/source-review.md`](https://github.com/ConardLi/garden-skills/blob/main/review/source-review.md).

### Phase 2 – Plan Validation

Before construction begins, the main agent validates its own article plan against five criteria without invoking a SubAgent. This **inline self-check** confirms brief-outline consistency, justified content pruning, balanced component usage, proper Raw/Image purpose definition, and correct section numbering.

### Phase 4 – First Spread Review

After generating the cover, hero section, and initial content, the **First Spread Reviewer SubAgent** examines the article's opening elements. This dedicated agent checks cover adherence, hero image relevance, first-section flow, theme fidelity, and build success, writing findings to [`review/first-spread-review.md`](https://github.com/ConardLi/garden-skills/blob/main/review/first-spread-review.md).

### Phase 5 – Section-by-Section Review

Each subsequent section undergoes individual review by a **Section Reviewer SubAgent**. Unlike previous phases, this validation returns only pass/fail messages (no file output), enforcing outline coverage, content retention ratios, narrative continuity, semantic component usage, and correct section numbering.

### Phase 6 – Final Multi-Agent Review

The terminal checkpoint deploys three specialized SubAgents simultaneously:
- **Editorial Reviewer** audits prose quality and argument structure
- **Visual Reviewer** validates design consistency and theme adherence  
- **Technical Reviewer** confirms build integrity and component correctness

These agents collaborate to produce [`review/final-review.md`](https://github.com/ConardLi/garden-skills/blob/main/review/final-review.md), documenting any remaining defects before publication.

## Core QA Principles

The quality assurance strategy for the beautiful-article skill enforces five fundamental principles across all phases, documented in [`references/component-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/references/component-policy.md) and [`references/repair-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/references/repair-policy.md):

- **No silent decisions** – Every critical choice regarding article type, theme, width, image mode, and cover design requires explicit item-by-item confirmation.
- **Prose-first component usage** – Articles must use semantic `reacticle` components; raw HTML is permitted only where absolutely necessary.
- **One-section-one-file rule** – Each section lives in its own `.tsx` file, enabling parallel SubAgent processing and preventing accidental section merging.
- **Theme-driven styling** – All visual styling derives from theme tokens (`--ra-*`); custom CSS is strictly disallowed.
- **Repair-only mindset** – After any checkpoint failure, the main agent must fix reported issues before proceeding, as mandated in [`references/repair-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/references/repair-policy.md).

## Implementation Details and Code Examples

### Inline Source Self-Check

Following extraction, the main agent executes validation logic similar to this pattern:

```typescript
// Executed after source extraction in references/source-to-markdown.md
const checklist = [
  "Is the content complete?",
  "Are headings preserved?",
  "Are tables, code, formulas intact?",
  "Is extraneous noise removed?",
  "Are image placeholders recorded?"
];

for (const item of checklist) {
  const passed = await selfCheck(item, sourceMd);
  if (!passed) await fixSourceIssue(item);
}

```

This corresponds to the **5-item checklist** documented at lines 92-104 of [`references/source-to-markdown.md`](https://github.com/ConardLi/garden-skills/blob/main/references/source-to-markdown.md).

### SubAgent Invocation for First Spread Review

When reaching Phase 4, the main agent triggers the First Spread Reviewer using:

```bash
subagent run \
  --prompt "@skills/beautiful-article/references/first-spread-review.md" \
  --inputs article/Article.tsx article/sections/01-*.tsx \
          plan/plan.md theme-profiles/tufte.md \
  --output review/first-spread-review.md

```

### Final Review Execution

The three-agent final review executes via:

```bash

# Editorial Reviewer example

subagent run \
  --prompt "@skills/beautiful-article/references/final-review.md#Editorial Reviewer" \
  --inputs plan/plan.md source/source.md article/**/*.tsx \
  --output review/final-review.md

```

These commands reference the checkpoint definitions in [`references/review-checklist.md`](https://github.com/ConardLi/garden-skills/blob/main/references/review-checklist.md) (lines 40-52 for First Spread, lines 95-112 for Final Review).

## Key Configuration Files

The quality assurance strategy relies on several reference files within `skills/beautiful-article/references/`:

- **[`review-checklist.md`](https://github.com/ConardLi/garden-skills/blob/main/review-checklist.md)** – Defines all checkpoint criteria, SubAgent assignments, and review file specifications (lines 10-13 for Source Review, lines 67-79 for Section Review).
- **[`source-to-markdown.md`](https://github.com/ConardLi/garden-skills/blob/main/source-to-markdown.md)** – Contains the 5-item inline self-check for source material validation.
- **[`component-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/component-policy.md)** – Enforces `reacticle` component usage and the one-section-one-file rule.
- **[`repair-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/repair-policy.md)** – Mandates the repair-only mindset for handling checkpoint failures.
- **[`SKILL.md`](https://github.com/ConardLi/garden-skills/blob/main/SKILL.md)** – Provides the high-level orchestration logic that sequences these QA phases.

## Summary

- The beautiful-article skill implements **six distinct QA phases**, from source verification through final multi-agent review.
- **Dual validation modes** combine inline self-checks (Phases 1-2) with dedicated SubAgent reviewers (Phases 1 alternate, 4, 5, and 6).
- **Five core principles** enforce explicit decision-making, semantic component usage, file organization, theme consistency, and mandatory repair workflows.
- **Review artifacts** ([`source-review.md`](https://github.com/ConardLi/garden-skills/blob/main/source-review.md), [`first-spread-review.md`](https://github.com/ConardLi/garden-skills/blob/main/first-spread-review.md), [`final-review.md`](https://github.com/ConardLi/garden-skills/blob/main/final-review.md)) provide auditable checkpoints at critical workflow stages.
- All policies are codified in specific reference files within `skills/beautiful-article/references/`, ensuring reproducible quality standards.

## Frequently Asked Questions

### What triggers the Source Reviewer SubAgent versus the inline self-check?

The main agent uses the **inline 5-item self-check** for standard source extractions, as defined in [`references/source-to-markdown.md`](https://github.com/ConardLi/garden-skills/blob/main/references/source-to-markdown.md). The **Source Reviewer SubAgent** activates only for complex sources or when confidence is low, performing a diff comparison between `original.*` files and [`source.md`](https://github.com/ConardLi/garden-skills/blob/main/source.md) to produce [`review/source-review.md`](https://github.com/ConardLi/garden-skills/blob/main/review/source-review.md).

### How does the skill prevent style inconsistencies across sections?

The **theme-driven styling** principle requires all visual properties to use theme tokens (`--ra-*`), with explicit prohibition of custom CSS. During Phase 6, the **Visual Reviewer SubAgent** specifically audits adherence to these tokens across all section files.

### What happens if a Section Reviewer returns a failure?

According to the **repair-only mindset** defined in [`references/repair-policy.md`](https://github.com/ConardLi/garden-skills/blob/main/references/repair-policy.md), the main agent must halt progression and fix the reported failures before continuing. Unlike earlier phases that produce review files, Phase 5 Section Reviewers return immediate pass/fail messages, requiring synchronous resolution.

### Why does Phase 5 use message-based feedback instead of review files?

The **Section Reviewer** employs lightweight pass/fail messages to enable rapid iteration during parallel section generation. Since sections are developed sequentially or in parallel across separate `.tsx` files (per the one-section-one-file rule), message-based feedback prevents review directory bloat while maintaining strict quality gates for outline coverage and component usage.