---
name: seo-report-formatter
description: Format raw SEO audit findings into a clean, client-ready Markdown report. Use this after running a full SEO audit, when the user wants to polish findings into a presentable document, says "format the audit report", "make a clean MD report", "client report from audit", "export SEO results to markdown", "clean up the audit output", or wants to share audit results with a client or stakeholder. Also trigger when the user has FULL-AUDIT-REPORT.md or ACTION-PLAN.md and wants a polished version.
---

# SEO Report Formatter

Transform raw SEO audit findings into a structured, client-ready Markdown report. Input can be:
- Existing `FULL-AUDIT-REPORT.md` / `ACTION-PLAN.md` files from seo-audit
- Raw text findings pasted by user
- A mix of both

Output: single file `SEO-REPORT-[domain]-[date].md` saved in current working directory.

## Process

1. **Read inputs** — check for `FULL-AUDIT-REPORT.md` and `ACTION-PLAN.md` in cwd. If missing, use whatever the user provided.
2. **Extract key data** — score, business type, critical issues, quick wins, findings per category.
3. **Render the report** using the template below.
4. **Save** to `SEO-REPORT-[domain]-[YYYY-MM-DD].md`.
5. **Confirm** to user: filename, path, issue count by priority.

## Report Template

Use this exact structure. Fill each section from the audit data. Omit sections that have no findings — don't leave empty headings.

```markdown
# SEO Audit Report — [Domain]

**Date:** [YYYY-MM-DD]  
**Business Type:** [detected type]  
**Overall SEO Health Score:** [score]/100

---

## Executive Summary

[2–4 sentence summary: what site does well, biggest blockers, overall direction.]

### Score Breakdown

| Category | Score | Status |
|---|---|---|
| Technical SEO | [n]/100 | 🔴 / 🟡 / 🟢 |
| Content Quality | [n]/100 | 🔴 / 🟡 / 🟢 |
| On-Page SEO | [n]/100 | 🔴 / 🟡 / 🟢 |
| Schema / Structured Data | [n]/100 | 🔴 / 🟡 / 🟢 |
| Performance (CWV) | [n]/100 | 🔴 / 🟡 / 🟢 |
| AI Search Readiness | [n]/100 | 🔴 / 🟡 / 🟢 |
| Images | [n]/100 | 🔴 / 🟡 / 🟢 |

### Top 5 Critical Issues

1. [issue]
2. [issue]
3. [issue]
4. [issue]
5. [issue]

### Top 5 Quick Wins

1. [win]
2. [win]
3. [win]
4. [win]
5. [win]

---

## Findings

### Technical SEO

[findings — crawlability, indexability, security, CWV]

### Content Quality

[findings — E-E-A-T, thin content, duplicates, readability]

### On-Page SEO

[findings — titles, meta descriptions, headings, internal links]

### Schema & Structured Data

[findings — current schema, validation errors, missing opportunities]

### Performance

[LCP / INP / CLS values and observations]

### Images

[alt text gaps, oversized files, format issues]

### AI Search Readiness

[citability score, structural gaps, authority signals]

---

## Action Plan

### 🔴 Critical — Fix Immediately

| # | Issue | Impact | Effort |
|---|---|---|---|
| 1 | [issue] | High | [Low/Med/High] |

### 🟠 High — Fix Within 1 Week

| # | Issue | Impact | Effort |
|---|---|---|---|
| 1 | [issue] | High | [Low/Med/High] |

### 🟡 Medium — Fix Within 1 Month

| # | Issue | Impact | Effort |
|---|---|---|---|
| 1 | [issue] | Medium | [Low/Med/High] |

### 🟢 Low — Backlog

| # | Issue | Impact | Effort |
|---|---|---|---|
| 1 | [issue] | Low | [Low/Med/High] |

---

## Notes

[Any caveats: pages not crawled, tools unavailable, data limitations.]

---

*Report generated by SEO Audit · [date]*
```

## Status indicator logic

Map scores to status emoji:
- 🟢 = 75–100 (good)
- 🟡 = 50–74 (needs work)
- 🔴 = 0–49 (critical)

If no per-category scores exist, omit the score column and use the emoji to indicate qualitative severity instead.

## Writing style

- Audience: client or stakeholder, not developer
- Plain language — no jargon without explanation
- Findings: state the problem, explain why it matters, don't prescribe technical fixes (that's ACTION-PLAN.md's job)
- Action items: imperative verb, one sentence, clear outcome ("Add meta description to 23 product pages")
- Never leave placeholder text in the output — if data is missing, omit that row/section rather than writing "[no data]"

## Effort estimation

If not provided by audit data, estimate effort as:
- **Low** — config change, single-page edit, 1–2 hours
- **Med** — template change, affects many pages, 1–3 days
- **High** — architecture change, developer required, 1+ week