pre-publish-checker

# Pre-Publish Checker Skill

## Overview

This skill performs rigorous pre-publication validation for Hugo blog posts using a **Sequential Validation** workflow: assess structure, validate fields, check assets, and report results. It embeds Hugo-specific rules and SEO best practices to catch publication blockers before they reach production.

The skill is **non-destructive** (modifies files only with explicit user request), **complete** (shows all validation results—always shows complete output), and **severity-aware** (distinguishes BLOCKER from SUGGESTION throughout the workflow).

---

## Instructions

### Usage

```
/pre-publish [path-to-post]
/pre-publish content/posts/2025-01-my-post.md
/pre-publish --check-external content/posts/2025-01-my-post.md
```

If no path provided, prompt user to specify the post file.

### Phase 1: ASSESS

**Goal**: Parse post structure and extract all validatable elements.

**Step 1: Read the target markdown file**

Verify the file exists. If not, list available posts and ask user to confirm.

**Step 2: Extract front matter**

Hugo supports both TOML and YAML front matter. Detect delimiter type:
- TOML: enclosed in `+++` delimiters
- YAML: enclosed in `---` delimiters

Parse all fields into structured data.

**Step 3: Extract body content**

Everything after front matter closing delimiter. Inventory:
- Word count (prose only, exclude code fences)
- Header hierarchy (H2, H3 levels)
- Internal links, external links, image references
- TODO/FIXME markers and placeholder patterns

**Gate**: File parsed successfully. Front matter extracted. Body content inventoried. Proceed only when gate passes.

### Phase 2: VALIDATE

**Goal**: Run all validation checks with correct severity classification.

**Step 1: Front matter validation**

| Field | Requirement | Severity | Reasoning |
|-------|-------------|----------|-----------|
| title | Present, non-empty | BLOCKER | Hugo build fails without title |
| date | Present, valid format | BLOCKER | Publishing requires valid timestamp |
| draft | Must be `false` | BLOCKER | Hugo excludes draft posts; this is a non-negotiable check |
| description | Present, 150-160 chars | SUGGESTION | SEO optimization; user may omit intentionally |
| tags | Present, 3-5 items | SUGGESTION | Recommendation for taxonomy consistency; not required |
| categories | Present, 1-2 items | SUGGESTION | Recommendation for site organization; not required |

Always validate draft field first. Treat as highest-priority blocker—draft posts are excluded from production builds entirely.

**Step 2: SEO validation**

| Check | Optimal Range | Severity | Reasoning |
|-------|---------------|----------|-----------|
| Title length | 50-60 characters | SUGGESTION | Search engine display optimization |
| Description length | 150-160 characters | SUGGESTION | Meta description window sizing |
| Slug format | URL-friendly, no special chars | SUGGESTION | Internal naming convention |

Derive slug from filename: `2025-01-my-post.md` becomes `my-post`.

**Step 3: Content quality validation**

| Check | Requirement | Severity | Reasoning |
|-------|-------------|----------|-----------|
| Word count | Minimum 500 words | SUGGESTION | Depth indicator; user retains discretion |
| Reading time | Calculate at 200 WPM | INFO | Report only, not a blocker |
| Header structure | H2/H3 present, logical hierarchy | SUGGESTION | Readability and scannability |
| Opening paragraph | No preamble phrases | SUGGESTION | Content quality; user may override |

Preamble detection phrases: "In this post, I will...", "Today I'm going to...", "Let me explain...", "Welcome to...", "First of all...", "Before we begin..."

**Step 4: Link validation**

- **Internal links**: Pattern `](/posts/...)` or `](/images/...)`. Verify target exists. Severity: BLOCKER if missing (broken links prevent navigation).
- **External links**: Pattern `](https://...)`. Skip by default. Severity: WARNING if unreachable (when enabled). Rationale: External validation adds network latency and rate-limiting concerns; skip unless user opts in with `--check-external`.
- **Image links**: Pattern `![alt](path)` or Hugo shortcodes. Verify file exists in static/. Severity: BLOCKER if missing (reader sees broken image).

**Step 5: Image validation**

| Check | Requirement | Severity | Reasoning |
|-------|-------------|----------|-----------|
| Alt text | All images must have non-empty alt | SUGGESTION | Accessibility best practice |
| File existence | All referenced images exist in static/ | BLOCKER | Missing images break page rendering |
| Path format | Correct Hugo static path convention | SUGGESTION | Consistency with site standards |

Hugo image path patterns: `/images/filename.png` (absolute from static/), `images/filename.png` (relative), `{{< figure src="..." >}}` (shortcode).

**Step 6: Draft status validation**

| Check | Requirement | Severity | Reasoning |
|-------|-------------|----------|-----------|
| draft field | Must be `false` | BLOCKER | Hugo build filter; non-negotiable |
| TODO comments | None present | WARNING | Development artifact—likely unintentional in published post |
| FIXME comments | None present | WARNING | Development artifact—likely unintentional in published post |
| Placeholder text | None present | BLOCKER | Content is incomplete if placeholders remain |

Placeholder patterns: `[insert X here]`, `[TBD]`, `[TODO]`, `XXX`, `PLACEHOLDER`, `Lorem ipsum`.

**Gate**: All validation checks executed. Each check produced a status (PASS, FAIL, WARN, SKIP, INFO). Proceed only when gate passes.

### Phase 3: SUGGEST TAXONOMY

**Goal**: Provide actionable taxonomy suggestions when tags or categories are missing.

**Step 1: Build taxonomy index**

Read existing posts to collect all tags and categories currently in use. Rationale: Always read existing posts before suggesting. Inventing generic tags like "programming" or "tech" without checking the site creates inconsistent taxonomy and fragments content organization.

**Step 2: Analyze content**

Match current post content against existing taxonomy terms. Prefer established terms over inventing new ones.

**Step 3: Generate suggestions**

Suggest 3-5 tags and 1-2 categories. Distribute suggestions evenly across the taxonomy rather than over-suggesting popular tags; distribute evenly across the taxonomy. Report suggestions even if tags/categories are already present—they validate against site conventions.

**Gate**: Taxonomy suggestions generated from existing site data (not invented). Proceed only when gate passes.

### Phase 4: REPORT

**Goal**: Generate structured validation report with clear outcome.

Format the report as:

```
===============================================================
 PRE-PUBLISH CHECK: [file path]
===============================================================

 FRONT MATTER:
   [status] field: "value" (details)

 SEO:
   [status] check: result (optimal range)

 CONTENT:
   [status] metric: value

 LINKS:
   [status] type: count valid/invalid

 IMAGES:
   [status] check: result

 DRAFT STATUS:
   [status] check: result

===============================================================
 RESULT: [READY FOR PUBLISH | NOT READY - N blockers]
===============================================================
```

**Status icons**: `[PASS]`, `[WARN]`, `[FAIL]`, `[SKIP]`, `[INFO]`

**Result classification**:
- READY FOR PUBLISH: Zero blockers (suggestions and warnings are acceptable)
- NOT READY: One or more blockers present; list all blockers after result

Ensure accurate blocker count. Count blockers and suggestions independently in the final result—count them independently.

**Gate**: Report generated with accurate blocker count. Result matches blocker tally.

---

## Examples

### Example 1: Clean Post
User says: "Check my kubernetes post before I publish"
Actions:
1. Parse front matter and body content (ASSESS)
2. Validate all fields, links, images, draft status (VALIDATE)
3. All tags present, skip taxonomy (SUGGEST)
4. Report: READY FOR PUBLISH with all PASS (REPORT)
Result: Structured report, zero blockers, post cleared for publication

### Example 2: Post With Blockers
User says: "Is my draft ready?"
Actions:
1. Parse front matter — draft: true detected (ASSESS)
2. Validate — draft blocker, missing image, TODO found (VALIDATE)
3. Tags missing — suggest from existing taxonomy (SUGGEST)
4. Report: NOT READY - 3 blockers listed (REPORT)
Result: Structured report with blocker list and suggestions

---

## Error Handling

### Error: "File Not Found"
Cause: Wrong path, running from wrong directory, or file moved
Solution:
1. Verify the path is correct and absolute
2. List available posts with `ls content/posts/`
3. Check if running from repository root
4. Ask user to confirm the correct file path

### Error: "Cannot Parse Front Matter"
Cause: Syntax errors in TOML/YAML, mismatched delimiters, invalid date
Solution:
1. Check for matching delimiters (`+++` or `---`)
2. Validate TOML/YAML syntax (unclosed quotes, bad indentation)
3. Verify date format matches Hugo expectations
4. Report the parse error location and suggest correction

### Error: "Image Path Cannot Be Verified"
Cause: Non-standard path format, Hugo shortcode variant, or missing static/ directory
Solution:
1. Normalize path (strip leading `/`, resolve relative paths)
2. Check both `static/` and `assets/` directories
3. Handle Hugo shortcode `figure` and `img` variants
4. Report as SKIP with explanation if path format is unrecognizable

---

## References

- `${CLAUDE_SKILL_DIR}/references/seo-guidelines.md`: SEO length requirements and best practices
- `${CLAUDE_SKILL_DIR}/references/hugo-frontmatter.md`: Hugo front matter fields and formats
- `${CLAUDE_SKILL_DIR}/references/checklist.md`: Complete validation checklist reference