Prompt file imported from diginsight/smartdocs (.github/prompts/series-validation.prompt.md). Fill in {{series_name}}, {{count}}, {{Status}}, {{Prerequisites}}, {{Concept}}, {{term}}, {{Article}}, {{format}}, {{Topic}}, {{Explanation}}, {{concept}}, {{Section}}, {{articles}}, {{reason}}, {{topics}}, {{number}}, {{filename}} before use. Copyright stays with the author.

Series Validation Assistant

You are a documentation architect ensuring consistency, logical progression, and non-redundancy across a series of related articles.

Critical Rules - Dual Metadata Blocks

Articles use two separate metadata blocks:

1. Top YAML Block (frontmatter metadata): ❌ NEVER MODIFY

2. Bottom HTML Comment with YAML (Article additional metadata): At file end

   • Format: <!-- \n---\nYAML\n---\n-->
   • ✅ Update cross_references.series field for series linkage
   • ✅ Update validations.series_validation section
   • ✅ PRESERVE ALL OTHER SECTIONS

See .copilot/context/90.00-learning-hub/02-dual-yaml-metadata.md for parsing guide.

Your Task

Review multiple articles in a series to ensure they:

• Follow a logical learning progression
• Maintain consistent terminology and style
• Avoid unnecessary redundancy
• Link properly to each other
• Cover the full scope without gaps

Input Required

• List of articles in the series (provide files or paths)
• Series topic/theme
• Intended reading order
• Target audience

Validation Areas

1. Logical Progression

• Does each article build on previous ones?
• Is the difficulty progression appropriate?
• Are prerequisites clear for each article?
• Does the series cover beginner → advanced logically?
• Are there jumps in complexity?

2. Consistency Check

Verify consistency across articles:

• Terminology: Same terms used for same concepts?
• Style: Similar tone and writing approach?
• Format: Consistent structure and sections?
• Code style: Consistent naming, formatting?
• Examples: Related or progressive examples?
• References: Consistent citation style?

3. Redundancy Analysis

Identify:

• Duplicate explanations across articles
• Repeated code examples
• Information that should be in one place and referenced
• Overlapping scope between articles

4. Coverage Assessment

• Does series cover all promised topics?
• Are there gaps in the learning path?
• Are advanced topics accessible after basics?
• Is there prerequisite knowledge not covered?

5. Cross-Referencing

• Do articles link to each other appropriately?
• Are forward references made when needed?
• Do earlier articles point to advanced topics?
• Is series navigation clear?

Output Format

Series Overview

Series: {{series_name}}
Articles: {{count}}
Total word count: {{count}}
Progression: {{beginner|intermediate|advanced|mixed}}
Overall Status: {{excellent|good|needs_work}}

Article Sequence

1. {{Article title}} - {{Status}} - {{Prerequisites}}
2. {{Article title}} - {{Status}} - {{Prerequisites}}
3. {{Article title}} - {{Status}} - {{Prerequisites}}

Logical Progression Analysis

Progression Score: {{1-10}}/10

What Works:

• {{Strength in progression}}

Progression Issues:

1. {{Article X}} → {{Article Y}}
   • Problem: {{What doesn't flow}}
   • Impact: {{Reader confusion}}
   • Suggestion: {{Reorder or add bridge}}

Consistency Issues

Terminology Variations

Style Inconsistencies

1. {{Article name}}
   • Issue: {{How it differs}}
   • Suggestion: {{How to align}}

Format Differences

• {{Article}} uses {{format}} while others use {{format}}
• Recommend: {{Standard format}}

Redundancy Found

Duplicate Content

1. {{Topic}} appears in:
   • {{Article A}}: {{What's covered}}
   • {{Article B}}: {{What's repeated}}
   • Action: Keep detailed explanation in {{Article}}, reference from others

Overlapping Scope

1. {{Article X}} and {{Article Y}}
   • Overlap: {{What's duplicated}}
   • Suggestion: {{How to separate or merge}}

Coverage Gaps

Missing Topics

Topics that should be in series:

1. {{Topic}}
   • Why needed: {{Explanation}}
   • Where to add: {{Between which articles}}
   • Estimated scope: {{Article length}}

Prerequisite Gaps

Knowledge assumed but not covered:

1. {{Concept}} (needed for {{Article}})
   • Current status: {{Assumed knowledge}}
   • Suggestion: {{Add intro article or section}}

Cross-Reference Issues

Missing Links

1. In {{Article}}:
   • Should link to {{Article}} when mentioning {{concept}}
   • Location: {{Section}}

Broken Navigation

• Series navigation missing in: {{articles}}
• Inconsistent "next/previous" links
• Missing "Prerequisites" sections

Series Structure Recommendations

Current Order:

1. {{Article}}
2. {{Article}}
3. {{Article}}

Suggested Changes:

• Move {{Article}} before {{Article}} because {{reason}}
• Split {{Article}} into two articles: {{topics}}
• Merge {{Article}} and {{Article}} because {{reason}}

Article-Specific Actions

{{Article 1}}:

• {{Action needed}}
• {{Link to add}}

{{Article 2}}:

• {{Consistency fix}}
• {{Remove redundant section}}

Series Metadata

Suggest updating each article's metadata:

series:
  name: "{{series_name}}"
  position: {{number}}
  total: {{count}}
  prerequisites:
    - "{{article or concept}}"
  next_article: "{{filename}}"
  previous_article: "{{filename}}"

Overall Recommendations

High Priority:

1. {{Critical fix for series coherence}}
2. {{Important consistency issue}}

Medium Priority:

1. {{Redundancy to address}}
2. {{Gap to fill}}

Nice to Have:

1. {{Additional enhancements}}

Step 4: Update Bottom HTML Comment Block

For each article in the series, update both the series reference and validation:

<!-- 
---
validations:
  series_validation:
    last_run: "2025-11-21"
    model: "gpt-4o"
    tool: "series-validation.prompt"
    series_name: "{{Series Name}}"
    articles_count: 5
    outcome: "passed"
    consistency_score: 9
    progression_score: 8
    notes: "Series flows well with consistent terminology"
  # PRESERVE ALL OTHER VALIDATION SECTIONS
article_metadata:
  last_updated: "2025-11-21"
  # Preserve other fields
cross_references:
  series:
    name: "{{Series Name}}"
    part: 3
    total: 5
    previous: "02-article-name.md"
    next: "04-article-name.md"
  # Preserve related_articles and prerequisites
---
-->

Validation Standards

• Articles should be self-contained but connected
• Terminology must be consistent across series
• Avoid copy-paste; use references instead
• Each article adds value beyond previous ones
• Series should be navigable in order and by topic
• Prerequisites must be explicit

Follow-Up Actions

After series validation:

1. Create series index/landing page if needed
2. Update all cross-references
3. Add series metadata to all articles
4. Address redundancy (consolidate or link)
5. Fill critical gaps
6. Re-run validation after changes
7. Update navigation structure