From building-in-the-open
Runs deterministic quality gates (token count, readability, completeness via bito) and agent-based editorial judgment (conference-talk test, tone drift, assumed context) on documentation artifacts. Use when asked to proofread, review, edit, or check writing quality; before committing docs; when checking if documentation is ready to ship or publish; or as the final gate in any writing skill's workflow.
npx claudepluginhub claylo/building-in-the-open --plugin building-in-the-openThis skill is limited to using the following tools:
**Announce at start:** "I'm using the editorial-review skill to run quality gates on this artifact."
Implements Playwright E2E testing patterns: Page Object Model, test organization, configuration, reporters, artifacts, and CI/CD integration for stable suites.
Guides Next.js 16+ Turbopack for faster dev via incremental bundling, FS caching, and HMR; covers webpack comparison, bundle analysis, and production builds.
Discovers and evaluates Laravel packages via LaraPlugins.io MCP. Searches by keyword/feature, filters by health score, Laravel/PHP compatibility; fetches details, metrics, and version history.
Announce at start: "I'm using the editorial-review skill to run quality gates on this artifact."
The final gate before an artifact reaches the repository. This skill coordinates two layers of quality checking: deterministic tools for things agents are bad at (counting tokens, computing readability scores, validating section completeness) and agent-based review for things tools can't catch (sarcasm, assumed context, tone drift, the conference-talk test).
This is the tone firewall in practice — the enforcement mechanism behind ADR-0002.
PRIVATE_MEMORY.md, private memory files) — private context bypasses the firewall entirely. That's the point.| Layer | Tool | What it checks | When it fails |
|---|---|---|---|
| Deterministic | bito tokens | Token count vs. budget | Handoffs over 2,000 tokens |
| Deterministic | bito readability | Flesch-Kincaid grade level | Above persona target (≤8 for Doc Writer, ≤12 for Technical Writer) |
| Deterministic | bito completeness | Required sections present and substantive | Missing or placeholder sections |
| Agent-based | ${CLAUDE_PLUGIN_ROOT}/agents/editorial-reviewer.md | Conference-talk test, negative refs, assumed context, tone consistency | Any passage that would be uncomfortable on stage |
Determine:
Dialect: Check for BITO_DIALECT environment variable or the project's bito config for a dialect preference (en-us, en-gb, en-ca, en-au). If set, pass --dialect <value> to bito analyze to enforce dialect-consistent spelling. The consistency checker will flag wrong-dialect spellings in addition to mixed usage.
Run the applicable bito checks. Not all checks apply to all artifact types.
| Artifact type | Token check | Readability check | Completeness check |
|---|---|---|---|
| Handoff | Yes (budget: 2000) | No (density metric, not grade) | Yes (template: handoff) |
| ADR | No | Yes (max-grade: 12) | Yes (template: adr) |
| Design doc | No | Yes (max-grade: 12) | Yes (template: design-doc) |
| End-user doc | No | Yes (max-grade: 8) | No (structure varies) |
| Changelog entry | No | No (too short for meaningful score) | No |
| Release announcement | No | Yes (max-grade: 8) | No |
Commands:
# Token check (handoffs only)
bito tokens <file> --budget 2000
# Readability check
bito readability <file> --max-grade <target>
# Completeness check
bito completeness <file> --template <type>
If any deterministic check fails, report the failure. The artifact should be revised before proceeding to agent review — no point checking tone on a document that's missing required sections.
The context: fork frontmatter on this skill delegates to the editorial-reviewer agent automatically. The agent receives this skill's instructions as its task, along with the artifact content, type, and target persona from the earlier steps.
The agent works through six checks:
Produce a structured review report:
If all checks pass:
## Editorial Review: [artifact type]
**Overall:** PASS
**Deterministic checks:**
- Tokens: [N/A or PASS (count/budget)]
- Readability: [N/A or PASS (grade/target)]
- Completeness: [N/A or PASS]
**Agent review:** No issues found. The artifact meets professional standards and is ready to commit.
If any checks fail:
## Editorial Review: [artifact type]
**Overall:** FAIL — N issues found
**Deterministic checks:**
- Tokens: [PASS/FAIL with details]
- Readability: [PASS/FAIL with details]
- Completeness: [PASS/FAIL with details]
**Agent review issues:**
### Issue 1: [Category]
**Passage:** "[quoted text]"
**Problem:** [what's wrong]
**Suggested revision:** "[revised text]"
### Notes
[Optional observations that aren't failures but worth considering]
If the review fails:
Do not auto-fix agent review issues. The reviewer identifies problems and suggests revisions; the writer decides how to address them. The writer persona may have good reasons to push back on a suggestion.
curating-context, capturing-decisions, writing-design-docs, writing-end-user-docs, writing-changelogs)${CLAUDE_PLUGIN_ROOT}/hooks/pre-commit-docs) for manually-written or externally-modified docsbito CLI (cargo install bito) for deterministic checks, ${CLAUDE_PLUGIN_ROOT}/agents/editorial-reviewer.md for agent-based review| Mistake | Fix |
|---|---|
| Skipping deterministic checks and going straight to agent review | Run tools first. Agent review on a document missing required sections wastes an API call and produces noisy feedback. |
| Auto-fixing agent review issues without writer input | The reviewer suggests; the writer decides. Flag the issue and let the writing skill or user choose how to address it. |
| Applying the wrong readability target | Match the target to the persona, not the artifact type. Doc Writer docs target grade ≤ 8; Technical Writer docs target grade ≤ 12. |
| Running editorial review on PRIVATE_MEMORY.md | Never. Private memory is explicitly outside the firewall. If someone asks to review it, decline. |
| Treating "Notes" as failures | Notes are observations, not blockers. A note might say "consider shortening this paragraph" — that's advice, not a gate. |
| Re-running all checks after a minor revision | If only the agent review failed, re-run only the agent review. Deterministic checks are idempotent but unnecessary to repeat if the relevant content didn't change. |