vf-doc-review

name	vf-doc-review
description	Use when reviewing veryfront documentation in docs/guides or docs/reference - audits content accuracy against src/, structure (frontmatter, index order, single H1, cross-links), professional technical writing voice, and Getting Started completeness

Veryfront Documentation Review

Overview

A four-pillar review of veryfront's user-facing docs (docs/guides/, docs/reference/). Catches what the existing test suite cannot: stale API references, AI-flavored prose, structural drift, and broken reading flows.

Core principle: Documentation is a product surface. Review it like code — concrete findings with file:line citations, no vague impressions.

Scope

In scope	Out of scope
docs/guides/*.md content & code samples	docs/reference/veryfront/*.md body (generated by scripts/docs/generate-api-reference.ts)
docs/guides/index.md ordering	Architecture deep-dives in docs/architecture/
Frontmatter on every guide	README files in src/
Cross-links between guides + into reference docs

For reference docs: only check that guides link to the correct generated reference pages, not the reference body itself.

What Is Already Automated — Do Not Redo

These tests already run in CI. Run them first; only flag what they miss.

Test	Checks
tests/docs/guide-contracts.test.ts	Per-guide required references + code snippets exist
tests/docs/guide-content.test.ts	Specific content invariants (e.g. OAuth uses tokenStore.getTokens, deploy guides don't claim a URL is printed)
tests/docs/guide-code-examples.test.ts	TypeScript code samples compile against real imports
tests/docs/guide-examples.test.ts	End-to-end snippet execution

Run before reviewing:

deno task test -- tests/docs/

If any of these fail, fix the test failures first — they are higher-signal than any review finding.

The Four Pillars

1. Content Accuracy

Every API symbol, file path, env var, and CLI command in a guide must match real code.

Checks:

• Every import ... from "veryfront/..." resolves through the deno.json import map to a file that exports the named symbol. Do not assume veryfront/<module> lives at src/<module>/index.ts — many public surfaces (e.g. veryfront/router, veryfront/head, veryfront/context) map to src/react/runtime/core.ts via explicit imports entries
• Every function call signature matches the real signature (arg names, return type)
• Every env var (VERYFRONT_*, VF_*) appears in the codebase
• Every file path shown (e.g. agents/foo.ts, app/api/hello/route.ts) is one the framework actually discovers
• Every CLI command (veryfront <cmd>) appears in cli/commands/ and the flags match
• Every cross-link [...](./other-guide.md) resolves
• Every reference link [...](../reference/veryfront/<module>.md) points to a file that exists

How to verify (grep-able claims):

# Resolve a public import "veryfront/<sub>" to its real source file
# Step 1: check deno.json import map for an explicit mapping
python3 -c 'import json; m=json.load(open("deno.json"))["imports"]; print(m.get("veryfront/<sub>", "(no map entry — falls back to package resolution)"))'

# Step 2: confirm the named symbol is exported from the resolved file
# (replace <resolved-path> with the value from step 1)
grep -nE "^export[[:space:]]+(\\{|const|function|class|type|interface).*\\b<symbolName>\\b" <resolved-path>

# CLI command exists
ls cli/commands/ | grep <cmd>

# Env var is read somewhere
grep -rn "VERYFRONT_<NAME>" src/ cli/

# Cross-link target exists
ls docs/guides/<target>.md

Claims that grep cannot verify — these need a manual run, not a code search:

• Downloadable installer URLs and behavior (e.g. curl ... | sh, PowerShell irm | iex snippets)
• Docker image tag existence and runtime compatibility (e.g. FROM denoland/deno:2.6.0)
• Third-party CLI flag behavior (e.g. deno init --npm, npm create <pkg>)
• External package existence on npm/PyPI/etc.
• Minimum-version compatibility claims (Node 18.18, Deno 1.45, Bun 1.1)
• Live URL patterns (e.g. https://<slug>.production.veryfront.com)

If a claim falls in this category and you cannot run it during the review, flag it in the report as Unverified rather than Blocker or Quality. Recommend the maintainer test it.

2. Structure

Per-guide invariants (every file in docs/guides/ except index.md, README.md):

• Has frontmatter with title:, description:, order:
• No # Heading at the top of the body — the renderer adds H1 from frontmatter title. A # H1 in the body produces a duplicate H1.
• First content section is ## (H2), not #
• Code fences declare a language (```ts, ```bash, ```json). Use ```text for non-code blocks like file trees or plain output — bare ``` is acceptable for those but text is clearer
• No TODO, FIXME, XXX, or TBD markers

Index invariants (docs/guides/index.md):

• Every .md file in docs/guides/ (except index.md, README.md) appears in a table
• No table entry points at a deleted file
• The order: field in each guide matches its position in the index reading order (Getting Started 1–6, then Foundations, then Pages and APIs, etc.)
• Section groupings still make sense (no guide stranded in the wrong section)

Quick checks:

# Duplicate-H1 audit (prints file:line for any body H1; title belongs in frontmatter only)
for f in docs/guides/*.md; do
  case "$f" in *index.md|*README.md) continue;; esac
  awk 'BEGIN{c=0} /^---$/{c++; next} c>=2 && /^# /{print FILENAME":"NR": [body H1]"; exit}' "$f"
done

# Frontmatter completeness
for f in docs/guides/*.md; do
  case "$f" in *README.md) continue;; esac
  for field in title description order; do
    grep -q "^$field:" "$f" || echo "MISSING $field: $f"
  done
done

# Guides not linked from index
for f in docs/guides/*.md; do
  base=$(basename "$f")
  case "$base" in index.md|README.md) continue;; esac
  grep -q "$base" docs/guides/index.md || echo "ORPHAN: $base"
done

# Broken sibling links
grep -rEo '\]\(\./[a-z0-9-]+\.md\)' docs/guides/ | while IFS=: read -r src link; do
  target="docs/guides/${link#*(./}"
  target="${target%)}"
  [ -f "$target" ] || echo "BROKEN: $src -> $link"
done

3. Voice — Professional Technical Writer, Not AI

Veryfront docs aim for the tone of a senior engineer writing for other senior engineers: direct, specific, no padding. Flag any of the following.

Banned words and phrases (almost always a sign of AI-generated marketing prose):

Pattern	Why it's bad	Rewrite as
"powerful", "robust", "seamless", "comprehensive", "best-in-class", "cutting-edge", "world-class"	Empty marketing adjectives	Delete, or state the concrete capability
"leverage", "utilize", "facilitate"	Inflated verbs	"use", "use", "let"
"delve into", "dive deep", "unlock", "elevate", "empower"	AI cliches	Delete, or use a plain verb
"simply", "just", "easily"	Patronizes the reader; often wrong	Delete
"In this guide, we will explore..." / "Let's take a look at..."	Filler intro	State what the guide does in one sentence
"It's worth noting that", "Keep in mind that", "Note that" (as filler)	Padding	Delete and state the fact
"In order to"	Wordy	"To"
"a wide range of", "a variety of", "numerous", "myriad"	Vague quantifier	Give the number or a concrete list
"etc." in technical lists	Lazy — reader cannot complete the list	Enumerate, or end the list cleanly
"blazing fast", "lightning-fast", "blazingly"	Hype	Delete or give numbers
"Whether you're a beginner or an expert..."	Audience-pandering intro	Delete
"—" used to bolt on a clause when a period would do	AI stylistic tic	Use a period
Emoji in body text (✨ 🚀 ⚡ 🎉)	Casual register, ages badly	Delete

Voice rules:

• Second person ("you") for the reader, not "we" or "users"
• Imperative for instructions ("Create agents/foo.ts", not "You can create…" or "You should create…")
• Present tense for behavior ("The runtime loads…", not "will load")
• Concrete over abstract: name files, env vars, function names — not "the configuration"
• One idea per sentence; no compound rambling
• No hedging on framework behavior. "Veryfront does X" — not "may do" or "typically does" — unless there's a documented condition
• No motivational openers ("Building agents is fun! In this guide…")

Grep for the worst offenders:

grep -nEi '\b(powerful|robust|seamless|leverage|delve|simply|just|easily|blazing|lightning|in order to|comprehensive|world-class|cutting-edge|best-in-class|elevate|empower|unlock)\b' docs/guides/*.md

4. Completeness — Getting Started Flow

The Getting Started path (six guides) must work end-to-end on a clean machine.

Read in order, as a new user would:

1. installation.md → 2. create-a-project.md → 3. create-an-agent.md → 4. create-an-api.md → 5. create-a-frontend.md → 6. deploy-a-project.md

Per-step checks:

• Prerequisites at the top name the previous step (so a reader who jumps in mid-flow knows what's missing)
• Every command can be run by copy-paste — no <placeholder> left unexplained
• State assumed by step N+1 is produced by step N (e.g. if step 3 says "in your project from step 2", step 2 must have produced one)
• No forward references that haven't been introduced ("…using the agent.tools field" before tools are explained)
• Each step is one focused task; if a step has three "optional" branches, it's two steps
• End of step links to the next step (or to the index for "what's next")

Other guides (not Getting Started):

• Opening sentence answers "What will I be able to do after reading this?"
• Has a Prerequisites section if it assumes a project exists
• Has a "Next steps" or related-guides section at the end
• Code samples build to something usable, not isolated fragments

Review Workflow

When invoked (e.g. via /vf-doc-review):

1. Establish scope. Ask the user, or infer:
   • "Recent changes" → git diff --stat main..HEAD -- docs/guides/ and review only changed files
   • "A specific guide" → review that file
   • "Getting Started" → review the six-step flow
   • "Full audit" → all 44 guides (will be long)
2. Run automated tests first. deno task test -- tests/docs/.
   • If failures originate in tests/docs/* or in docs/guides/*: surface them and fix before reviewing — they're higher-signal than any manual finding.
   • If failures originate elsewhere (e.g. .claude/worktrees/*, stray src/ issues, environment problems): note them as out-of-scope and proceed with the review. Don't get sidetracked.
3. Run the structural greps from Pillar 2 — these are mechanical and find most issues in seconds.
4. For each guide in scope, work the four pillars. Cite findings as docs/guides/<file>.md:<line> with the offending snippet quoted.
5. Produce a report grouped by severity:
   • Blocker — wrong API, broken link, missing prerequisite that breaks the flow
   • Quality — AI prose, structural drift, missing frontmatter
   • Unverified — claims that depend on external systems (URLs, Docker tags, third-party flags) that grep cannot prove; recommend a manual test
   • Nit — minor wording, formatting consistency
6. Offer to fix. Group fixes by file. For voice fixes, propose the exact rewrite. Do not bulk-edit without showing the diff.

Report Format

## docs/guides/<file>.md

### Blockers
- L42: `import { foo } from "veryfront/bar"` — `bar` has no `foo` export (src/bar/index.ts only exports `Foo`, `createBar`). Rewrite to `import { Foo } from "veryfront/bar"`.
- L88: link `./quickstart.md` — file was renamed to `create-a-project.md`.

### Quality
- L7: "powerful framework" — drop "powerful". Rewrite: "Define an agent and stream the response."
- L120: duplicate H1 (`# Create an agent` after frontmatter `title: "Create an agent"`). Remove the body H1.

### Unverified
- L56: `FROM denoland/deno:2.6.0` — Docker tag existence not provable from source. Recommend pulling the image once to confirm.

### Nits
- L55: code fence missing language hint (` ``` ` → ` ```text ` for the file-tree block).

Common Mistakes

Mistake	Fix
Reviewing reference docs body	They are generated. Only check links into them.
Skipping the automated tests	Run deno task test -- tests/docs/ first; their failures outrank your findings.
Flagging vague "tone" issues without a rewrite	Always propose the replacement text.
Bulk-rewriting AI prose without diff	Show the user each change; voice is opinionated.
Citing docs/architecture/ issues	Out of scope for this skill.
Treating order: numbers as cosmetic	They drive the rendered nav order; mismatches with index.md break the reading flow.
Adding new guides to a section without updating index.md	Index is the source of truth for nav; orphaned guides are unreachable.
Reviewing the entire 7,000-line corpus when the user asked about recent changes	Start with git diff main..HEAD -- docs/guides/ and scope down.
Assuming veryfront/<sub> always lives at src/<sub>/index.ts	Check the deno.json import map first — many public surfaces (router, head, context) re-export from src/react/runtime/core.ts.

Red Flags — Stop the Review

• Automated docs tests failing → fix those first; review is meaningless on broken contracts
• A guide references a symbol that doesn't exist in src/ → blocker, before any voice work
• index.md lists a deleted file → blocker, before anything else
• You catch yourself writing "the documentation could be improved by…" without a file:line citation → you're padding; delete and find the next concrete finding