lunar-review-docs

# lunar-review-docs Review the current `lunarphp/docs` branch and produce a local convention report. Read-only: no GitHub comments, no file edits. This is the counterpart to `lunar-document`. Where `lunar-document` *drafts* docs from a `lunarphp/lunar` PR or release, this skill *reviews* the in-progress changes on the current docs branch against the conventions defined in `CLAUDE.md`. ## When to use Invoked with no argument. The skill operates on whatever is currently checked out in the working directory. If the user passes a PR number or URL, respond with a one-line note that this skill only reviews the local branch, and suggest they push and review locally on that branch instead. ## Steps ### 1. Prep - Confirm the working directory is the `lunarphp/docs` repo (`git remote get-url origin` contains `lunarphp/docs`). Abort with a clear message otherwise. - Identify the base branch — prefer `next` if it exists on the remote, else `main`. - If the current branch *is* the base branch and the working tree is clean, emit a short note and stop. ### 2. Build the change set ```bash BASE=$(git rev-parse --abbrev-ref --symbolic-full-name @{u} 2>/dev/null || echo origin/next) MERGE_BASE=$(git merge-base HEAD "$BASE") git diff --name-status "$MERGE_BASE"...HEAD git diff "$MERGE_BASE"...HEAD ``` Also include uncommitted work — run `git status --porcelain` and `git diff HEAD` so in-progress edits are reviewed too. Partition the touched files into: - MDX content under `1.x/`, `0.x/`, `support/`, `logs/` - `docs.json` - Other (images, redirects, config) — list but do not lint If neither MDX nor `docs.json` changed, emit a short note and stop. ### 3. Determine docs version Infer from the touched paths (`1.x/...` vs `0.x/...`). Mixed-version changes are flagged as a finding, not an abort. ### 4. Check passes Run all four passes against each touched MDX file. Collect findings; do not stop early. #### a. Style, voice & frontmatter - Frontmatter parses cleanly; `title` present. - Third person — flag occurrences of `\b(we|our|us)\b` outside fenced code blocks. - American English — flag British spellings: `colour`, `behaviour`, `organisation`, `centre`, `licence`, `analyse`, `optimise`, `customise`, `recognise`. - Em-dash density — flag files with more than 2 em dashes per 1000 characters as "review for overuse" per `CLAUDE.md` ("Use em dashes sparingly"). - Summary sentence — verify a non-empty paragraph sits between the H1 and the next block. #### b. Structural conventions - Code fences referencing `Lunar\` use the full namespace inline or a visible `use` statement in the same fence. - Eloquent model field tables have columns: **Field, Type, Description** (in that order). - Relationship tables have columns: **Relationship, Type, Related Model, Description**. - Scope tables have columns: **Scope, Description**. - `nullable` appears inline at the end of the Type cell, formatted as code (e.g. `` `foreignId` `nullable` ``). - `id` row is described as "primary key". - Standard timestamps (`created_at`, `updated_at`, `deleted_at`) are present in field tables but need no description. #### c. Navigation wiring (`docs.json`) For each touched file with status: - `A` (added): verify the path appears exactly once under `navigation.versions[].tabs[].groups[].pages`. - `D` (deleted): verify the path has been removed from `docs.json`. - `R` (renamed): verify the old path is gone and the new path is present. If new MDX files were added but `docs.json` is unchanged in the diff, flag as a **blocker**. See `lunar-document/SKILL.md` → "Navigation update rules" for the traversal pattern. #### d. Accuracy vs `../lunar` Run only when the change set touches `<ver>/reference/...` or any MDX references `Lunar\Models\...`. - Resolve each referenced class by searching `../lunar/packages/` for the matching path. - If `../lunar` is missing, skip this pass with a note. Do not fail. - For documented fields, compare against the latest migration plus `$fillable` / `$casts` and report: - Missing fields. - Wrong column types. - Order drift relative to the migration. - `nullable` mismatches. - For documented relationships and scopes, confirm each named method exists on the model class. `../lunar` is the source of truth per `CLAUDE.md`. ### 5. Report Print a single grouped Markdown report to the chat. No `gh pr review`, no `gh pr comment`, no file edits. Order: 1. **Blockers** — missing `docs.json` entries for new pages, missing `title` frontmatter, broken MDX frontmatter. 2. **Conventions** — voice, spelling, summary sentence, em-dash overuse. 3. **Structure** — namespaces, table columns, schema order, nullable formatting. 4. **Navigation** — non-blocker `docs.json` drift, deletion mismatches. 5. **Accuracy** — `../lunar` mismatches. 6. **Info** — version, current branch, base branch, files reviewed, files skipped, whether uncommitted changes were included. Each finding includes: file path, line number where derivable, one-sentence explanation, suggested fix. End with the conventions checklist from `lunar-document/SKILL.md` so the user can scan-confirm. ## Stop conditions Abort cleanly with a message when: - The current directory is not the `lunarphp/docs` repo. - The current branch is the base branch with a clean working tree. - The change set has no MDX or `docs.json` changes. ## Out of scope - Reviewing remote PRs — push the branch and run the skill on the local checkout instead. - Posting GitHub review comments (read-only by design). - Editing files in the change set. - Running `mint dev` or full MDX compilation. - Reviewing `0.x/` content beyond the same checks — legacy docs are reported but not deeply cross-referenced against `../lunar`. See `/Users/glenn/GitHub/lunarphp/docs/CLAUDE.md` for the authoritative convention list. Do not duplicate it here.