# FAQ Manual Review Workflow

**Last Updated:** 2026-01-15

Step-by-step workflow for manually reviewing and fixing FAQ quality issues post by post.

## Overview

This workflow guides you through reviewing each blog post individually to:

- Check topic relevance
- Remove off-topic FAQs
- Fix repetitive patterns
- Remove duplicates
- Reorder FAQs logically

## Prerequisites

Before starting, ensure you have:

- [ ] All analysis scripts installed and executable
- [ ] Access to blog post JSON files
- [ ] Understanding of quality standards (see `FAQ_QUALITY_STANDARDS.md`)

## Step-by-Step Workflow

### Step 1: Run Comprehensive Analysis

For each post you want to review:

```bash
php v2/scripts/blog/comprehensive-faq-analysis.php --post=slug --category=category
```

This will show you:

- Topic relevance scores for each FAQ
- Pattern violations
- Duplicate pairs
- Ordering issues
- Brand questions on non-brand posts
- Nonsensical questions

### Step 2: Review Analysis Output

Review the analysis report and identify:

1. **Off-topic FAQs** (relevance < 0.3)

   - Note which FAQs need to be removed
   - Consider if they can be replaced with topic-relevant FAQs

2. **Pattern Violations**

   - High-severity violations (must remove)
   - Medium-severity violations (review and fix)

3. **Duplicates**

   - Identify duplicate pairs
   - Decide which FAQ to keep (better answer quality)

4. **Ordering Issues**

   - Review suggested ordering
   - Plan new order following logical flow

5. **Brand Questions**

   - Identify brand questions on non-brand posts
   - Remove unless naturally relevant

6. **Nonsensical Questions**
   - Identify malformed questions
   - Fix or remove

### Step 3: Use Review Workflow Tool

```bash
php v2/scripts/blog/review-faq-quality-post-by-post.php --post=slug --category=category
```

This interactive tool displays:

- Post info (title, slug, primary keyword)
- All FAQs with quality indicators
- Highlighted issues
- Suggested fixes

### Step 4: Fix Issues

**Option A: Automated Fixes (with manual review)**

```bash
# Dry-run first to preview changes
php v2/scripts/blog/fix-faq-quality-issues.php --post=slug --category=category --dry-run

# Apply fixes with backup
php v2/scripts/blog/fix-faq-quality-issues.php --post=slug --category=category --backup
```

**Option B: Manual Edit**

1. Open post JSON file: `v2/data/blog/posts/{category}/{slug}.json`
2. Edit `faqs` array:
   - Remove off-topic FAQs
   - Remove pattern violations
   - Remove duplicates (keep best)
   - Fix malformed questions
   - Reorder FAQs logically
3. Save file

### Step 5: Validate Changes

After making changes, validate:

```bash
# Comprehensive analysis
php v2/scripts/blog/comprehensive-faq-analysis.php --post=slug --category=category

# Topic relevance
php v2/scripts/blog/validate-faq-topic-relevance.php --post=slug --category=category

# Pattern detection
php v2/scripts/blog/detect-faq-patterns.php --post=slug --category=category

# Ordering
php v2/scripts/blog/analyze-faq-ordering.php --post=slug --category=category

# Uniqueness
php v2/scripts/blog/check-faq-uniqueness.php --post=slug --category=category

# Schema validation
php v2/scripts/blog/validate-faq-schema.php --post=slug --category=category
```

### Step 6: Document Review

Update progress tracking:

- Note issues found
- Note fixes applied
- Update quality scores
- Document any learnings

## Prioritization

### High Priority (Fix First)

1. Posts with quality score < 60
2. Posts with off-topic FAQs
3. Posts with pattern violations
4. Posts with duplicates

### Medium Priority

1. Posts with ordering issues
2. Posts with quality score 60-75

### Low Priority

1. Posts with quality score 75-89
2. Posts with minor issues

## Quality Checklist Per Post

- [ ] All FAQs relevant to post topic (relevance ≥ 0.3)
- [ ] No pattern violations (high severity)
- [ ] No duplicate questions (similarity < 0.7)
- [ ] No brand questions on non-brand posts
- [ ] Logical ordering (definitions before how-to)
- [ ] 10-15 FAQs per post
- [ ] Answers 40-80 words
- [ ] Primary keyword in 3-5 FAQs
- [ ] Du tone consistent
- [ ] Schema validates correctly

## Common Fixes

### Fix Off-Topic FAQs

1. Identify FAQs with relevance < 0.3
2. Remove from `faqs` array
3. Replace with topic-relevant FAQs if needed (use GSC queries, PAA questions)

### Fix Pattern Violations

1. Identify pattern violations
2. Remove high-severity violations
3. Fix malformed questions (remove fragments, fix grammar)

### Fix Duplicates

1. Identify duplicate pairs (similarity ≥ 0.7)
2. Compare answers (keep better quality)
3. Remove duplicate from `faqs` array

### Fix Ordering

1. Review current order
2. Reorder following logical flow:
   - Definitions first
   - How-to second
   - Requirements/details third
   - Edge cases last
3. Prioritize high-volume queries (from GSC)

## Tools Reference

**Analysis:**

- `comprehensive-faq-analysis.php` - Complete quality analysis
- `validate-faq-topic-relevance.php` - Topic relevance check
- `detect-faq-patterns.php` - Pattern detection
- `analyze-faq-ordering.php` - Ordering analysis

**Review:**

- `review-faq-quality-post-by-post.php` - Interactive review

**Fix:**

- `fix-faq-quality-issues.php` - Automated fixes

**Validation:**

- `validate-faq-schema.php` - Schema validation
- `check-faq-uniqueness.php` - Uniqueness check

## Example Review Session

```bash
# 1. Run analysis
php v2/scripts/blog/comprehensive-faq-analysis.php --post=ueberstunden-erfassen --category=ratgeber

# 2. Review output - identify issues:
#    - 3 off-topic FAQs (relevance < 0.3)
#    - 2 pattern violations
#    - 1 duplicate pair

# 3. Preview fixes
php v2/scripts/blog/fix-faq-quality-issues.php --post=ueberstunden-erfassen --category=ratgeber --dry-run

# 4. Apply fixes
php v2/scripts/blog/fix-faq-quality-issues.php --post=ueberstunden-erfassen --category=ratgeber --backup

# 5. Validate
php v2/scripts/blog/comprehensive-faq-analysis.php --post=ueberstunden-erfassen --category=ratgeber
php v2/scripts/blog/validate-faq-schema.php --post=ueberstunden-erfassen --category=ratgeber
```

## Related Documentation

- `FAQ_QUALITY_IMPROVEMENT_GUIDE.md` - How to fix specific issues
- `FAQ_QUALITY_STANDARDS.md` - Quality thresholds and standards
- `FAQ_MANUAL_REVIEW_CHECKLIST.md` - Detailed checklist