Document Quality Standards

Document Quality Standards

Patterns that complement the official document-skills plugin. Apply these alongside xlsx, pdf, docx, and pptx skills.

Visual-First Verification

Core principle: Text extraction misses critical details. Always verify visually.

"Only do python printing as a last resort because you will miss important details with text extraction (e.g. figures, tables, diagrams)."

The Render-Inspect-Fix Loop

For ANY document operation (create, edit, convert):

1. Generate/modify document
2. Convert to PNG:
   pdftoppm -png -r 150 document.pdf output
3. Visually inspect the PNG at 100% zoom
4. Fix any issues found
5. REPEAT until clean

Never deliver a document without PNG verification. This catches:

• Clipped or overlapping text
• Broken tables
• Missing figures
• Formatting inconsistencies
• Orphans/widows
• Unreadable characters

Quick Conversion Commands

# DOCX → PDF → PNG
soffice --headless --convert-to pdf document.docx
pdftoppm -png -r 150 document.pdf page

# PDF → PNG directly
pdftoppm -png -r 150 document.pdf page

# PPTX → PDF → PNG
soffice --headless --convert-to pdf presentation.pptx
pdftoppm -png -r 150 presentation.pdf slide

Typography Hygiene

Hyphen Safety

Never use non-breaking hyphens (U+2011). They cause rendering failures in many viewers.

# WRONG - may render as boxes or break layouts
text = "co‑author"  # U+2011 non-breaking hyphen

# CORRECT - always use ASCII hyphen
text = "co-author"  # U+002D standard hyphen-minus

Detection and fix:

# Find problematic hyphens
import re
if '\u2011' in text:
    text = text.replace('\u2011', '-')

# Also watch for other non-ASCII dashes
text = text.replace('\u2013', '-')  # en-dash
text = text.replace('\u2014', '-')  # em-dash (if hyphen intended)

Citation Format

All citations must be human-readable in standard scholarly format:

• No internal tool tokens (e.g., 【4:2†source】)
• No malformed references
• Include: Author, Title, Source, Date, URL (if applicable)

# WRONG
See source 【4:2†source】 for details.

# CORRECT
See Smith (2024), "Document Standards," Journal of Tech, p. 45.

Spreadsheet Formula Patterns

Complements the xlsx skill's color conventions with additional patterns.

Extended Color Codes

Beyond the standard 5 colors (blue inputs, black formulas, green cross-sheet, red external, yellow assumptions):

Formula Simplicity

Use helper cells instead of complex nested formulas.

# WRONG - hard to debug, audit, or modify
=IF(AND(B5>100,C5<50),B5*1.1*IF(D5="A",1.2,1),B5*0.9)

# CORRECT - use helper columns
E5: =B5>100           (Threshold check)
F5: =C5<50            (Secondary check)
G5: =IF(D5="A",1.2,1) (Category multiplier)
H5: =IF(AND(E5,F5),B5*1.1*G5,B5*0.9)  (Final calculation)

Benefits:

• Each step is auditable
• Errors are easier to trace
• Business logic is visible
• Modifications are safer

Avoid Dynamic Array Functions

For maximum compatibility, avoid:

• FILTER() - not supported in older Excel
• XLOOKUP() - Excel 365+ only
• SORT() - dynamic array function
• SEQUENCE() - dynamic array function
• UNIQUE() - dynamic array function

Use classic equivalents:

• FILTER() → INDEX/MATCH with helper columns
• XLOOKUP() → INDEX/MATCH
• SORT() → manual sorting or helper columns
• SEQUENCE() → manually entered row numbers

Finance-Specific Formatting

Additional to xlsx skill standards:

# Hide gridlines for cleaner appearance
sheet.sheet_view.showGridLines = False

# Add borders above totals (not around every cell)
from openpyxl.styles import Border, Side
thin_top = Border(top=Side(style='thin'))
total_cell.border = thin_top

# Cite sources in cell comments, not adjacent cells
from openpyxl.comments import Comment
cell.comment = Comment("Source: 10-K FY2024, p.45", "Analyst")

Quality Checklist

Before delivering any document:

• PNG verification completed at 100% zoom
• No clipped or overlapping text
• Tables render correctly
• Figures/images display properly
• No U+2011 or problematic Unicode
• Citations are human-readable
• Formulas use helper cells where complex
• No Excel formula errors (#REF!, #DIV/0!, etc.)
• Professional, client-ready appearance

Integration with Official Skills

This skill adds patterns on top of the document-skills plugin:

Always read both this skill AND the relevant official skill when working with documents.