# Diagnose SEO Human Guide

## What This Is For
Structured diagnostic framework for crawl issues, canonicalization errors, indexation problems, and rendering failures. It gives the agent a clearer input/output frame for search and SEO workflows: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Diagnose SEO agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for diagnose SEO.
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Diagnose SEO guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- **Crawlability** — Can search engines find and access the pages?
- **Indexability** — Are the pages allowed to be indexed?
- **Renderability** — Can search engines see the full content?
- **Signals** — Are the right signals (titles, structured data, links) in place?
- Fetch `[domain]/robots.txt` and review the rules
- Look for overly broad `Disallow` rules blocking important paths
- Verify `Sitemap:` directive points to the correct sitemap URL
- Check for different rules per user-agent (Googlebot vs others)
- `Disallow: /` blocking the entire site (often left from staging)
- Blocking CSS/JS files that Googlebot needs for rendering
- Blocking API or AJAX endpoints that load dynamic content
- Staging robots.txt accidentally deployed to production

## Decision Points And Nuance
The original skill emphasizes: Diagnostic Approach, Layer 1: Crawlability, robots.txt, XML Sitemap, Site Architecture, Server Response, Layer 2: Indexability, Meta Robots / X-Robots-Tag, Canonical Tags, Duplicate Content.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- Look for overly broad `Disallow` rules blocking important paths
- Does it list all important pages?
- Do all important pages return HTTP 200?
- Are important elements (titles, headings, product details) in the DOM on first render?
- Under 60 characters (to avoid truncation in SERPs)
- Every important page has a meta description
- | Indexability | Missing canonical tags | Warning | 15 pages | Add self-referencing canonicals |
- [Warning fix] — affects [n] pages, reduces [signal quality]

## Copy-And-Paste Prompt
```text
Use the Diagnose SEO human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the calm-north/seojuice-skills skill entry for `diagnose-seo`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Diagnose SEO

Structured diagnostic framework for crawl issues, canonicalization errors,
indexation problems, and rendering failures.

## Diagnostic Approach

Technical SEO problems fall into four categories. Diagnose in this order — each
layer depends on the previous one working correctly:

1. **Crawlability** — Can search engines find and access the pages?
2. **Indexability** — Are the pages allowed to be indexed?
3. **Renderability** — Can search engines see the full content?
4. **Signals** — Are the right signals (titles, structured data, links) in place?

## Layer 1: Crawlability

Check these in order:

### robots.txt
- Fetch `[domain]/robots.txt` and review the rules
- Look for overly broad `Disallow` rules blocking important paths
- Verify `Sitemap:` directive points to the correct sitemap URL
- Check for different rules per user-agent (Googlebot vs others)

**Common mistakes:**
- `Disallow: /` blocking the entire site (often left from staging)
- Blocking CSS/JS files that Googlebot needs for rendering
- Blocking API or AJAX endpoints that load dynamic content
- Staging robots.txt accidentally deployed to production

### XML Sitemap
- Fetch the sitemap URL(s) and check:
  - Does it return 200? Is it valid XML?
  - Does it list all important pages?
  - Does it exclude pages that shouldn't be indexed (404s, redirects, noindex pages)?
  - Are `<lastmod>` dates accurate and recent?
  - For large sites: is there a sitemap index?

### Site Architecture
- Pages should be reachable within 3 clicks from the homepage
- Check for orphan pages (no internal links pointing to them)
- Check for redirect chains (page A → B → C — should be A → C)
- Check for redirect loops

### Server Response
- Do all important pages return HTTP 200?
- Check for unexpected 301/302 redirects
- Check for soft 404s (page returns 200 but shows "not found" content)
- Verify HTTPS is enforced (HTTP should 301 to HTTPS)

## Layer 2: Indexability

### Meta Robots / X-Robots-Tag
- Check for `<meta name="robots" content="noindex">` on pages that should be indexed
- Check HTTP headers for `X-Robots-Tag: noindex`
- Common cause: CMS accidentally applying noindex to pagination, tag pages, or new pages

### Canonical Tags
- Every page should have a `<link rel="canonical">` pointing to itself (self-referencing canonical)
- Check for canonical tags pointing to wrong pages (common in paginated content, filtered URLs)
- Check for conflicting signals: canonical says page A, but noindex is set, or the page redirects

**Canonical diagnosis checklist:**
- [ ] Does the canonical URL match the actual URL?
- [ ] Is the canonical URL accessible (returns 200)?
- [ ] Does the canonical URL have the same content?
- [ ] Is there only one canonical tag on the page?

### Duplicate Content
- Check for the same content accessible at multiple URLs:
  - With and without trailing slash (`/page` vs `/page/`)
  - With and without `www` (`example.com` vs `www.example.com`)
  - HTTP vs HTTPS
  - URL parameters creating duplicate pages (`?sort=price`, `?page=1`)
- Each duplicate set needs one canonical URL; all others should redirect or use canonical tags

## Layer 3: Renderability

### JavaScript Rendering