Claude-Code-Workflow/.claude/skills/software-manual/specs/quality-standards.md

# Quality Standards

Quality gates and standards for software manual generation.

## Quality Dimensions

### 1. Completeness (25%)

All required sections present and adequately covered.

| Requirement | Weight | Criteria |
|-------------|--------|----------|
| Overview section | 5 | Product intro, features, quick start |
| UI Guide | 5 | All major screens documented |
| API Reference | 5 | All public APIs documented |
| Configuration | 4 | All config options explained |
| Troubleshooting | 3 | Common issues addressed |
| Examples | 3 | Multi-level examples provided |

**Scoring**:
- 100%: All sections present with adequate depth
- 80%: All sections present, some lacking depth
- 60%: Missing 1-2 sections
- 40%: Missing 3+ sections
- 0%: Critical sections missing (overview, UI guide)

### 2. Consistency (25%)

Terminology, style, and structure uniform across sections.

| Aspect | Check |
|--------|-------|
| Terminology | Same term for same concept throughout |
| Formatting | Consistent heading levels, code block styles |
| Tone | Consistent formality level |
| Cross-references | All internal links valid |
| Screenshot naming | Follow `ss-{feature}-{action}` pattern |

**Scoring**:
- 100%: Zero inconsistencies
- 80%: 1-3 minor inconsistencies
- 60%: 4-6 inconsistencies
- 40%: 7-10 inconsistencies
- 0%: Pervasive inconsistencies

### 3. Depth (25%)

Content provides sufficient detail for target audience.

| Level | Criteria |
|-------|----------|
| Shallow | Basic descriptions only |
| Standard | Descriptions + usage examples |
| Deep | Descriptions + examples + edge cases + best practices |

**Per-Section Depth Check**:
- [ ] Explains "what" (definition)
- [ ] Explains "why" (rationale)
- [ ] Explains "how" (procedure)
- [ ] Provides examples
- [ ] Covers edge cases
- [ ] Includes tips/best practices

**Scoring**:
- 100%: Deep coverage on all critical sections
- 80%: Standard coverage on all sections
- 60%: Shallow coverage on some sections
- 40%: Missing depth in critical areas
- 0%: Superficial throughout

### 4. Readability (25%)

Clear, user-friendly writing that's easy to follow.

| Metric | Target |
|--------|--------|
| Sentence length | Average < 20 words |
| Paragraph length | Average < 5 sentences |
| Heading hierarchy | Proper H1 > H2 > H3 nesting |
| Code blocks | Language specified |
| Lists | Used for 3+ items |
| Screenshots | Placed near relevant text |

**Structural Elements**:
- [ ] Clear section headers
- [ ] Numbered steps for procedures
- [ ] Bullet lists for options/features
- [ ] Tables for comparisons
- [ ] Code blocks with syntax highlighting
- [ ] Screenshots with captions

**Scoring**:
- 100%: All readability criteria met
- 80%: Minor structural issues
- 60%: Some sections hard to follow
- 40%: Significant readability problems
- 0%: Unclear, poorly structured

## Overall Quality Score

```
Overall = (Completeness × 0.25) + (Consistency × 0.25) +
          (Depth × 0.25) + (Readability × 0.25)
```

**Quality Gates**:

| Gate | Threshold | Action |
|------|-----------|--------|
| Pass | ≥ 80% | Proceed to HTML generation |
| Review | 60-79% | Address warnings, proceed with caution |
| Fail | < 60% | Must address errors before continuing |

## Issue Classification

### Errors (Must Fix)

- Missing required sections
- Invalid cross-references
- Broken screenshot markers
- Code blocks without language
- Incomplete procedures (missing steps)

### Warnings (Should Fix)

- Terminology inconsistencies
- Sections lacking depth
- Missing examples
- Long paragraphs (> 7 sentences)
- Screenshots missing captions

### Info (Nice to Have)

- Optimization suggestions
- Additional example opportunities
- Alternative explanations
- Enhancement ideas

## Quality Checklist

### Pre-Generation

- [ ] All agents completed successfully
- [ ] No errors in consolidation report
- [ ] Overall score ≥ 60%

### Post-Generation

- [ ] HTML renders correctly
- [ ] Search returns relevant results
- [ ] All screenshots display
- [ ] Theme toggle works
- [ ] Print preview looks good

### Final Review

- [ ] User previewed and approved
- [ ] File size reasonable (< 10MB)
- [ ] No console errors in browser
- [ ] Accessible (keyboard navigation works)

## Automated Checks

```javascript
function runQualityChecks(workDir) {
  const results = {
    completeness: checkCompleteness(workDir),
    consistency: checkConsistency(workDir),
    depth: checkDepth(workDir),
    readability: checkReadability(workDir)
  };

  results.overall = (
    results.completeness * 0.25 +
    results.consistency * 0.25 +
    results.depth * 0.25 +
    results.readability * 0.25
  );

  return results;
}

function checkCompleteness(workDir) {
  const requiredSections = [
    'section-overview.md',
    'section-ui-guide.md',
    'section-api-reference.md',
    'section-configuration.md',
    'section-troubleshooting.md',
    'section-examples.md'
  ];

  const existing = Glob(`${workDir}/sections/section-*.md`);
  const found = requiredSections.filter(s =>
    existing.some(e => e.endsWith(s))
  );

  return (found.length / requiredSections.length) * 100;
}

function checkConsistency(workDir) {
  // Check terminology, cross-references, naming conventions
  const issues = [];

  // ... implementation ...

  return Math.max(0, 100 - issues.length * 10);
}

function checkDepth(workDir) {
  // Check content length, examples, edge cases
  const sections = Glob(`${workDir}/sections/section-*.md`);
  let totalScore = 0;

  for (const section of sections) {
    const content = Read(section);
    let sectionScore = 0;

    if (content.length > 500) sectionScore += 20;
    if (content.includes('```')) sectionScore += 20;
    if (content.includes('Example')) sectionScore += 20;
    if (content.match(/\d+\./g)?.length > 3) sectionScore += 20;
    if (content.includes('Note:') || content.includes('Tip:')) sectionScore += 20;

    totalScore += sectionScore;
  }

  return totalScore / sections.length;
}

function checkReadability(workDir) {
  // Check structure, formatting, organization
  const sections = Glob(`${workDir}/sections/section-*.md`);
  let issues = 0;

  for (const section of sections) {
    const content = Read(section);

    // Check heading hierarchy
    if (!content.startsWith('# ')) issues++;

    // Check code block languages
    const codeBlocks = content.match(/```\w*/g);
    if (codeBlocks?.some(b => b === '```')) issues++;

    // Check paragraph length
    const paragraphs = content.split('\n\n');
    if (paragraphs.some(p => p.split('. ').length > 7)) issues++;
  }

  return Math.max(0, 100 - issues * 10);
}
```