Instructions

Perform a deep analysis of documentation quality, finding issues that need attention.

Step 0: Read Context

Read .devdoc/context.json if it exists for product info and terminology.

Read docs.json to understand documentation structure.

Step 1: Scan Codebase

Analyze the source code to understand:

•Exported functions, classes, types
•API endpoints and routes
•Configuration options
•Feature flags and capabilities

Step 2: Analyze Documentation

Scan all MDX files for:

•Topics covered
•Code examples used
•Features documented
•API references

Step 3: Generate Blame Report

code

Documentation Blame Report
==========================

Generated: [date]
Files analyzed: X docs, Y source files

## 🔴 Critical Issues

### Duplicate Content (count)

Content that appears in multiple places, causing maintenance burden:

| Topic | Files | Recommendation |
|-------|-------|----------------|
| Authentication setup | auth.mdx, quickstart.mdx, api/overview.mdx | Consolidate to auth.mdx, link from others |
| Error handling | errors.mdx, troubleshooting.mdx | Merge into single page |

**Details:**
- `auth.mdx:15-45` and `quickstart.mdx:80-110` contain nearly identical OAuth setup instructions
- `errors.mdx` and `troubleshooting.mdx` both list the same error codes

### Outdated Documentation (count)

Docs that don't match current codebase:

| File | Issue | Current State |
|------|-------|---------------|
| api/users.mdx | Wrong signature | `getUser(id)` is now `getUser(id, options)` |
| config.mdx | Missing options | `timeout` and `retries` not documented |
| quickstart.mdx | Old version | References v1.x, current is v2.x |

**Details:**
- `api/users.mdx:23` shows `getUser(id: string)` but code has `getUser(id: string, options?: UserOptions)`
- `config.mdx` missing 3 new configuration options added in v2.0

### Code-Doc Discrepancies (count)

Mismatches between documented and actual behavior:

| File | Documented | Actual |
|------|------------|--------|
| api/auth.mdx | Returns `{ token }` | Returns `{ token, expiresAt }` |
| guides/setup.mdx | Requires Node 14+ | package.json requires Node 18+ |
| api/errors.mdx | Error code 401 | Code throws 403 for this case |

## 🟡 Warnings

### Undocumented Features (count)

Code exists but no documentation:

- `src/utils/retry.ts` - Retry utility with backoff (exported, no docs)
- `src/api/webhooks.ts` - Webhook handlers (3 endpoints, no docs)
- `src/config/advanced.ts` - Advanced options (12 options, not in config.mdx)

### Stale Examples (count)

Code examples that may not work:

| File | Line | Issue |
|------|------|-------|
| quickstart.mdx | 45 | Uses deprecated `init()`, should be `initialize()` |
| api/fetch.mdx | 23 | Import path changed from `pkg` to `pkg/client` |

### Inconsistent Terminology

Terms used differently across docs:

| Term | Variations Found | Recommended |
|------|------------------|-------------|
| API key | "api key", "API Key", "apiKey", "api-key" | "API key" |
| endpoint | "endpoint", "route", "URL", "path" | "endpoint" |

## 🟢 Good Practices Found

✓ All public exports have corresponding docs
✓ Code examples have language tags
✓ Consistent use of components (Note, Warning, etc.)

## Recommendations

### High Priority
1. **Consolidate auth docs** - Merge duplicate OAuth content into single source
2. **Update API signatures** - 5 files have outdated function signatures
3. **Document webhooks** - Major feature with zero documentation

### Medium Priority
4. **Version bump** - Update all version references to v2.x
5. **Standardize terminology** - Create glossary in context.json

### Low Priority
6. **Add missing options** - Document 12 config options
7. **Fix stale examples** - Update deprecated imports

Analysis Techniques

Finding Duplicates

Look for:

•Exact matches - Same paragraphs in multiple files
•Similar code blocks - Nearly identical examples
•Repeated explanations - Same concept explained multiple times
•Copy-paste patterns - Setup instructions repeated

Finding Outdated Content

Compare:

•Function signatures - Params, return types
•Import paths - Package structure changes
•Version numbers - In code vs docs
•Default values - Changed defaults
•Error messages - Updated error text

Finding Discrepancies

Check:

•Return types - What docs say vs code returns
•Required fields - Optional vs required mismatches
•Behavior descriptions - Edge cases documented incorrectly
•Prerequisites - Wrong versions, missing dependencies

Output Actions

After generating report, suggest:

"Found X issues. Would you like me to:

•Fix outdated docs - Update signatures and versions
•Consolidate duplicates - Merge redundant content
•Create missing docs - Stub pages for undocumented features
•Update terminology - Standardize across all files"

Integration with Other Skills

•After blame analysis → /update-doc to fix issues
•For new undocumented features → /create-doc
•When ready to save → /commit-doc