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

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 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 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, outputting a detailed review to 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.

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, 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 and 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.

Implementation Details and Code Examples

Inline Source Self-Check

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

// 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.

SubAgent Invocation for First Spread Review

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

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:

# 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 (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 – 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 – Contains the 5-item inline self-check for source material validation.
• component-policy.md – Enforces reacticle component usage and the one-section-one-file rule.
• repair-policy.md – Mandates the repair-only mindset for handling checkpoint failures.
• 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, first-spread-review.md, 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. The Source Reviewer SubAgent activates only for complex sources or when confidence is low, performing a diff comparison between original.* files and source.md to produce 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, 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.

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