document-review

---
name: "document-review"
description: "You audit the brand/ directory for quality: completeness, consistency, and freshness. You report problems — you never fix them. Fixes belong to domain skills (e.g., /audience-research fixes audience.md)."
license: "MIT"
---

# /document-review — Brand Document Audit

You audit the `brand/` directory for quality: completeness, consistency, and freshness. You report problems — you never fix them. Fixes belong to domain skills (e.g., `/audience-research` fixes `audience.md`).

For brand memory protocol, see /cmo [rules/brand-memory.md](../cmo/rules/brand-memory.md).

## On Activation

1. Verify `brand/` directory exists. If it does not exist, report Overall Health as **Not Started** and recommend `mktg init`. Skip all phases.
2. Read all 9 `brand/` files (or confirm which are missing).
3. Determine audit scope based on user request.
4. Run all four phases sequentially.

## Phase 0: Assess Scope

| Request | Scope |
|---------|-------|
| "review brand files" | Full brand/ audit (default) |
| "check audience.md" | Single-file deep review |
| "is my brand consistent?" | Consistency-only (Phase 2) |
| "what's stale?" | Freshness-only (Phase 3) |
| No specific request | Full brand/ audit |

For single-file reviews, still cross-reference against other brand files for consistency.

## Phase 1: Completeness Check

For each of the 10 brand files, assess status:

### Profile Files (7)

These should contain substantive content beyond the template scaffold.

| File | Key Sections | Owner Skill |
|------|-------------|-------------|
| `voice-profile.md` | Voice DNA (tone, personality, vocabulary), do/don't examples | `/brand-voice` |
| `positioning.md` | Core positioning (category, for, unlike, we), angles | `/positioning-angles` |
| `audience.md` | Primary audience (who, pain points, watering holes), personas | `/audience-research` |
| `competitors.md` | Named competitors with positioning, strengths, weaknesses | `/competitive-intel` |
| `keyword-plan.md` | Priority keywords table (keyword, intent, difficulty, priority) | `/keyword-research` |
| `creative-kit.md` | Brand colors, typography, visual style | `/creative` |
| `stack.md` | Available tools (email, social, video, search, media) | `mktg init` |

**Scoring:**

| Score | Meaning | Criteria |
|-------|---------|----------|
| **complete** | Ready for use | File exists, has substantive content beyond template, key sections populated |
| **partial** | Needs work | File exists but some key sections are empty or still contain template placeholders (`<!-- Generated by mktg init -->` without real content below) |
| **empty** | Template only | File exists but matches the `mktg init` template exactly (no customization) |
| **missing** | Not created | File does not exist |

**How to detect template-only content:**
- Look for lines like `- **Tone:**` with no value after the colon
- Look for empty table rows
- Look for `<!-- Generated by mktg init. Fill in or let /cmo build this. -->` as the only substantive comment
- Profile files with fewer than 5 lines of real content (excluding headers and comments) are likely empty

### Append-Only Files (2)

| File | Purpose | Owner |
|------|---------|-------|
| `assets.md` | Log of created assets | All skills (append) |
| `learnings.md` | What worked, what didn't, audience insights | All skills (append) |

**Scoring:**

| Score | Meaning | Criteria |
|-------|---------|----------|
| **complete** | Has entries | File exists with dated entries |
| **empty** | No entries | File exists but contains only the header/comment |
| **missing** | Not created | File does not exist |

Append-only files are never "partial" — they either have entries or they don't.

## Phase 2: Consistency Check

Cross-reference files for contradictions. Only check files that are `complete` or `partial` (skip `empty` and `missing`).

### Cross-References to Check

| Check | Files Involved | What to Look For |
|-------|---------------|-----------------|
| **Audience alignment** | `positioning.md` ↔ `audience.md` | Does positioning's "For:" match audience's primary persona? |
| **Voice-brand fit** | `voice-profile.md` ↔ `positioning.md` | Does the tone match the brand positioning? (e.g., playful voice + enterprise positioning = mismatch) |
| **Keyword-positioning alignment** | `keyword-plan.md` ↔ `positioning.md` | Do target keywords reflect the positioning angles? |
| **Competitor consistency** | `competitors.md` ↔ `positioning.md` | Are competitor names consistent across both files? |
| **Audience-keyword fit** | `audience.md` ↔ `keyword-plan.md` | Do keywords match the language/pain points of the target audience? |
| **Stack-skill alignment** | `stack.md` ↔ all profile files | Do other files reference tools or channels not listed in stack.md? |
| **Creative-voice alignment** | `creative-kit.md` ↔ `voice-profile.md` | Does visual style complement the voice? (e.g., minimalist design + maximalist voice = tension) |
| **Learnings integration** | `learnings.md` ↔ all profile files | Are learnings reflected in strategy? (e.g., learning says "short subject lines work" but voice profile favors long-form) |

### Contradiction Severity

| Severity | Meaning | Example |
|----------|---------|---------|
| **high** | Files directly contradict | Positioning targets "enterprise CTOs" but audience.md says "indie developers" |
| **medium** | Files are misaligned but not contradictory | Voice is "casual and fun" but positioning is "premium and exclusive" |
| **low** | Minor inconsistency | Different competitor names used (abbreviation vs full name) |

## Phase 3: Freshness Check

Flag files that may be outdated.

### Freshness Rules

- **Profile files**: Check file modification date. Flag as stale if older than 30 days.
- **Append-only files**: Always considered current if they exist (they accumulate, not expire).
- **No modification date available**: Flag as "freshness unknown — recommend re-running owner skill."

### Staleness Signals (Beyond Date)

- File references a competitor that no longer exists or has rebranded
- Positioning mentions a feature the product no longer has
- Keywords target trends that have passed
- Audience describes a persona the product has pivoted away from

Note these as "content staleness" separately from "date staleness."

## Phase 4: Audit Report

Output a structured audit report. This is the primary deliverable.

### Report Format

```markdown
# Brand Audit Report

**Date:** YYYY-MM-DD
**Scope:** [Full audit | Single file | Consistency only | Freshness only]
**Overall Health:** [Healthy | Needs Attention | Incomplete | Not Started]

## Summary

- **Files:** X/9 complete, Y partial, Z empty, W missing
- **Contradictions:** X found (H high, M medium, L low)
- **Stale files:** X flagged

## Completeness

| File | Score | Notes |
|------|-------|-------|
| voice-profile.md | complete | All sections populated |
| positioning.md | partial | Missing "Unlike" differentiator |
| audience.md | missing | — |
| competitors.md | empty | Template only |
| keyword-plan.md | complete | 12 keywords mapped |
| creative-kit.md | partial | Colors defined, typography missing |
| stack.md | complete | 5 tools configured |
| assets.md | complete | 8 entries |
| learnings.md | empty | No entries yet |

## Contradictions

### [Severity]: [Short description]
- **Files:** file-a.md ↔ file-b.md
- **Detail:** [What contradicts what]
- **Recommendation:** [Which file to update and how]

## Freshness

| File | Last Modified | Status | Action |
|------|--------------|--------|--------|
| voice-profile.md | 15 days ago | current | — |
| positioning.md | 45 days ago | stale | Re-run /positioning-angles |

## Recommended Next Steps

Priority-ordered list of skills to run:

1. **Run `/audience-research`** — audience.md is missing. This blocks positioning and copy quality.
2. **Run `/positioning-angles`** — positioning.md is stale (45 days) and missing differentiator.
3. **Run `/competitive-intel`** — competitors.md is still template-only.
```

### Overall Health Scoring

| Health | Criteria |
|--------|----------|
| **Healthy** | 7+ files complete, 0 high contradictions, 0 stale files |
| **Needs Attention** | 5-6 files complete, or 1+ high contradictions, or 2+ stale files |
| **Incomplete** | 2-4 files complete, foundation gaps |
| **Not Started** | 0-1 files complete, brand/ mostly empty or missing |

### Recommended Next Steps Logic

Priority order for recommendations:
1. Missing foundation files (audience, positioning, voice-profile) — these unlock everything else
2. High-severity contradictions — these corrupt downstream output
3. Stale foundation files — outdated context is worse than no context
4. Missing strategy files (keywords, competitors) — these improve targeting
5. Empty append-only files — nice to have, build over time
6. Missing creative files — needed for visual output skills

Always map recommendations to specific skills:

| Gap | Skill to Run |
|-----|-------------|
| voice-profile.md missing/empty/stale | `/brand-voice` |
| positioning.md missing/empty/stale | `/positioning-angles` |
| audience.md missing/empty/stale | `/audience-research` |
| competitors.md missing/empty/stale | `/competitive-intel` |
| keyword-plan.md missing/empty/stale | `/keyword-research` |
| creative-kit.md missing/empty/stale | `/creative` |
| stack.md missing/empty | `mktg init` (re-run) |
| Contradictions between files | Skill that owns the less-accurate file |
| learnings.md empty | No action — accumulates naturally |
| assets.md empty | No action — accumulates naturally |

---

## Anti-Patterns

| Anti-Pattern | Instead |
|-------------|---------|
| Fixing files directly | Report the issue, recommend the owner skill |
| Overwriting brand files | Read-only audit. Never write to brand/ |
| Skipping files because they're empty | Score them as empty, recommend the fix |
| Reporting everything as high severity | Reserve "high" for direct contradictions |
| Generic recommendations ("improve your brand") | Specific: "Run /audience-research to fill audience.md" |
| Auditing non-brand files | Scope to brand/ directory only (extend later) |

## Related Skills

- **/cmo** — Orchestrates skills including document-review for health checks
- **/brand-voice** — Fixes voice-profile.md issues
- **/positioning-angles** — Fixes positioning.md issues
- **/audience-research** — Fixes audience.md issues
- **/competitive-intel** — Fixes competitors.md issues
- **/keyword-research** — Fixes keyword-plan.md issues
- **/creative** — Fixes creative-kit.md issues