# Troubleshooting

Common issues, their causes, and fixes for `claude-blog`. Issues are grouped
by category and ordered from most to least common.

---

## Installation Issues

### "Command not found" after installation

**Symptom**: Running `/blog write` produces no response or a "skill not found"
error.

**Cause**: Claude Code caches skill definitions at startup. New skills are not
detected until the CLI is restarted.

**Fix**:
1. Close Claude Code completely (exit the CLI or close the terminal)
2. Reopen Claude Code
3. Try `/blog write <topic>` again

### Python script errors

**Symptom**: `/blog analyze` fails when running `analyze_blog.py`, or the
script exits with an import error.

**Cause**: Python dependencies are not installed.

**Fix**:
```bash
pip install -r requirements.txt
```

Or install the core dependencies individually:
```bash
pip install textstat beautifulsoup4 lxml jsonschema
```

### Missing textstat or beautifulsoup4

**Symptom**: `analyze_blog.py` runs but reports `ModuleNotFoundError: No module
named 'textstat'` or similar.

**Cause**: The optional Python dependencies are not installed.

**Behavior**: The analysis script is designed for **graceful degradation**.
Without optional dependencies, it falls back to basic mode:

| Dependency | When Missing | Fallback |
|-----------|-------------|----------|
| textstat | No Flesch/Gunning Fog scores | Sentence length heuristics |
| beautifulsoup4 | No HTML schema parsing | Regex-based detection |
| lxml | BeautifulSoup uses html.parser | Slower but functional |
| spacy | No NER analysis | Skipped (optional feature) |
| sentence-transformers | No semantic similarity | Skipped (optional feature) |
| scikit-learn | No topic clustering | Skipped (optional feature) |
| language-tool-python | No grammar checking | Skipped (optional feature) |

The script will produce results with reduced detail but will not crash.
Install dependencies for full functionality:

```bash
pip install -r requirements.txt  # Core deps
# Optional (install individually as needed):
pip install spacy sentence-transformers scikit-learn language-tool-python
```

### Permission denied on install.sh

**Symptom**: `./install.sh` returns "Permission denied".

**Fix**:
```bash
chmod +x install.sh
./install.sh
```

### Windows: PowerShell execution policy blocks install

**Symptom**: `install.ps1` fails with "running scripts is disabled on this
system."

**Fix**:
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-WebRequest `
  -Uri https://raw.githubusercontent.com/AgriciDaniel/claude-blog/main/install.ps1 `
  -OutFile install.ps1
Get-FileHash ./install.ps1 -Algorithm SHA256
pwsh -File ./install.ps1
```

Inspect the downloaded file and compare its digest with the release
documentation before running it.

---

## Content Quality Issues

### Low quality scores (below 60)

**Symptom**: `/blog analyze` returns a score below 60 ("Poor" rating).

**Common Causes and Fixes**:

| Issue | Impact | Fix |
|-------|--------|-----|
| Important claims lack clarity or support | Readiness and content points vary | State the point early and add verified evidence where needed; no fixed length |
| Fabricated statistics | Critical integrity issue | Remove or replace with verified support |
| Missing images | Context-dependent | Add an image only when it improves understanding |
| Missing charts | Context-dependent | Add a chart only when data relationships need one |
| No FAQ section | No score penalty | Add Q&A only when genuine reader questions warrant it |
| Difficult paragraph pacing | Advisory only | Split or combine passages when comprehension improves |
| Missing `lastUpdated` | No automatic penalty | Add it only after a substantive update and keep it truthful |
| Excessive self-promotion | Editorial issue | Remove promotion that distracts from the reader task |

**Quick fix workflow**:
```
1. /blog analyze <file>           # Get the score and issues
2. /blog rewrite <file>           # Auto-fix most issues
3. /blog analyze <file>           # Verify improvement
```

### Important section point not detected

**Symptom**: Score report says an important section lacks a clear, supported
point even though the section contains data.

**Cause**: A material claim needs source support close enough for readers to
identify what the source substantiates. Put evidence where it best supports
comprehension; it may appear in the first or a later paragraph.

**Supported placement example**:
```markdown
## How Does AI Search Impact Blog Traffic?

AI Overviews initially caused a 61% decline in organic CTR across 3,119 queries
in a 2025 Seer Interactive study
([Seer Interactive](https://seerinteractive.com), 2025). Later 2026 reporting
showed partial CTR rebound in some query sets, so treat this as historical
context rather than a universal current rate.
```

**Unsupported attribution example**:
```markdown
## How Does AI Search Impact Blog Traffic?

The landscape of search is changing rapidly. Many marketers are concerned
about the future of organic traffic.

According to Seer Interactive, CTR declined 61%.
```

The problem in the second example is not paragraph position. The material
measurement lacks a usable citation and enough study context to verify it.

### Statistics flagged as "fabricated"

**Symptom**: Quality report flags statistics as fabricated or unsourced.

**Cause**: The scoring system looks for inline attribution within 200
characters of a number. Missing or malformed citations trigger this flag.

**Correct attribution format**:
```markdown
initial 61% decline in organic CTR ([Seer Interactive](https://seerinteractive.com), 2025)
```

**Formats that may not be detected**:
```markdown
According to a recent study, CTR declined 61%.     # No source name or link
CTR declined 61% (source: Seer Interactive)         # No URL
CTR declined 61%. Source: Seer Interactive [1]       # Footnote style
```

---

## Template Issues

### Template not loading

**Symptom**: `/blog write` does not follow the expected template structure
for the content type.

**Causes and fixes**:

1. **Templates not installed**: Verify the templates directory exists:
   ```bash
   ls ~/.claude/skills/blog/templates/
   ```
   If empty or missing, re-run `./install.sh`.

2. **Wrong install path**: Templates must be in
   `~/.claude/skills/blog/templates/`, not in the repository's
   `skills/blog/templates/` directory.

3. **Template file corrupted**: Re-copy from the repository:
   ```bash
   cp skills/blog/templates/*.md ~/.claude/skills/blog/templates/
   ```

### Wrong template selected

**Symptom**: `/blog write` picks a how-to template when you wanted a listicle.

**Fix**: Specify the content type explicitly:
```
/blog write listicle: "10 Best Monitoring Tools for 2026"
/blog write --type comparison "Datadog vs Grafana"
```

Or state the type in natural language:
```
/blog write a comparison post about Datadog vs Grafana
```

---

## Agent Issues

### Agent not spawning

**Symptom**: The sub-skill does not delegate to a subagent (blog-researcher,
blog-writer, etc.), and instead tries to do everything inline.

**Causes**:

1. **Agent file not installed**: Check that agent files exist:
   ```bash
   ls ~/.claude/agents/blog-*.md
   ```
   Expected: `blog-researcher.md`, `blog-writer.md`, `blog-seo.md`,
   `blog-reviewer.md`, `blog-translator.md`

2. **Unsupported skill frontmatter**: `allowed-tools` is not a valid
   `SKILL.md` field and does not enable delegation. Check the sub-skill file:
   ```bash
   head -20 ~/.claude/skills/blog-write/SKILL.md
   ```
   Valid skill fields include `name`, `description`, `user-invokable`,
   `argument-hint`, `license`, `compatibility`, `metadata`, and
   `disable-model-invocation`. Agent tools live in
   `~/.claude/agents/blog-*.md`.

3. **Claude Code version**: Agent spawning via `Task` requires a recent
   version of Claude Code. Update to the latest version.

### Agent produces low-quality output

**Symptom**: The blog-writer agent produces content that does not follow
answer-first formatting or other rules.

**Fix**: This typically means the agent did not load the relevant reference
files. Run the command again: the orchestrator should load references
before spawning the agent. If the issue persists:

1. Verify reference files exist:
   ```bash
   ls ~/.claude/skills/blog/references/
   ```
2. Re-install references:
   ```bash
   cp skills/blog/references/*.md ~/.claude/skills/blog/references/
   ```

---

## Schema and SEO Issues

### Schema detection failing

**Symptom**: `/blog seo-check` or `/blog analyze` reports "No schema detected"
even though the post has JSON-LD markup.

**Causes**:

1. **Schema injected via JavaScript**: AI crawlers (GPTBot, ClaudeBot,
   PerplexityBot) and the analysis script cannot see schema that is
   injected client-side via JavaScript. Schema must be present in the HTML
   source (server-rendered).

   **How to check**: Disable JavaScript in your browser and view source.
   If the `<script type="application/ld+json">` block is missing, your
   schema is JS-injected.

   **Fix**: Move schema to server-rendered HTML:
   - Next.js: Use `generateMetadata()` or `<script>` in `layout.tsx`
   - Hugo: Add to template `<head>` partial
   - WordPress: Use a plugin that renders in PHP, not JS

2. **Schema in wrong format**: The analyzer looks for
   `<script type="application/ld+json">` blocks. Other formats (Microdata,
   RDFa) may not be detected.

3. **MDX FAQSchema component**: If using a React component like
   `<FAQSchema>`, ensure it renders the JSON-LD in the HTML output, not
   just the visual FAQ.

### JSON-LD validation errors

**Symptom**: `/blog schema` generates markup that fails validation.

**Fix**: Test the generated JSON-LD at:
- https://validator.schema.org/
- https://search.google.com/test/rich-results

Common issues:
- Missing `@context` or `@type` fields
- `dateModified` not matching `lastUpdated` in frontmatter
- Image URL not accessible (returns 404)
- Author `@type` should be `Person`, not `Organization`

---

## Platform-Specific Issues

### MDX compilation errors after blog write/rewrite

**Symptom**: The generated MDX file fails to compile in Next.js.

**Common causes**:

| Error | Cause | Fix |
|-------|-------|-----|
| `stroke-width` is not valid | HTML attributes in JSX | Convert to camelCase: `strokeWidth` |
| `class` is not valid | HTML `class` in JSX | Use `className` |
| `style="..."` syntax error | String style in JSX | Use object: `style={{...}}` |
| Unexpected `{` | Curly braces in markdown text | Escape: `\{` |
| `<` in text content | Angle brackets in prose | Use `&lt;` or wrap in backticks |

**Prevention**: When the platform is detected as MDX/Next.js, the sub-skills
automatically use JSX-compatible syntax. If errors persist, specify the
platform explicitly:

```
/blog write "topic" --format mdx
```

### Hugo front matter format mismatch

**Symptom**: Hugo does not recognize the YAML frontmatter fields.

**Fix**: Hugo uses TOML frontmatter by default (`+++` delimiters). If your
Hugo site uses YAML (`---` delimiters), add to `hugo.toml`:
```toml
[markup.frontmatter]
  date = ["date"]
  lastmod = ["lastUpdated", "lastmod"]
```

---

## Performance Issues

### Commands running slowly

**Symptom**: `/blog write` or `/blog brief` takes a long time to complete.

**Causes**:
- **Research phase**: WebSearch calls for statistics and images can take
  30-60 seconds depending on the topic
- **Chart generation**: Each `blog-chart` invocation adds 10-20 seconds
- **Large context**: Loading many reference files increases processing time

**Mitigation**:
- Provide a brief first (`/blog brief`) to pre-do research, then use
  `/blog write` with the brief (skips research phase)
- For analysis, use `analyze_blog.py` directly for faster automated metrics

### analyze_blog.py batch mode slow on large directories

**Symptom**: `--batch` mode takes a long time on directories with many files.

**Fix**: The script processes files sequentially. For large directories,
analyze subsets:
```bash
python3 analyze_blog.py posts/2026/ --batch    # Only 2026 posts
python3 analyze_blog.py posts/drafts/ --batch  # Only drafts
```

---

## Getting Help

If your issue is not listed here:

1. **Check the version**: Ensure you have the latest `claude-blog` installed:
   ```bash
   cd claude-blog && git pull && ./install.sh
   ```

2. **Verify file integrity**: Compare installed files with the repository:
   ```bash
   diff ~/.claude/skills/blog/SKILL.md skills/blog/SKILL.md
   ```

3. **Reset installation**: Remove and reinstall:
   ```bash
   ./uninstall.sh && ./install.sh
   ```

4. **Open an issue**: https://github.com/AgriciDaniel/claude-blog/issues