tomevault-io CI Style Review
Machine-readable output format for automated style review in CI pipelines. This skill wraps the interactive style-review skill with a strict JSON contract.
Rules Reference
All style rules, criteria, severity definitions, and examples are defined in the interactive skill:
Read .claude/skills/style-review/SKILL.md before proceeding. Do not skip this step. That file is the single source of truth for what constitutes a violation.
Workflow
Step 1: Load the style rules
Read .claude/skills/style-review/SKILL.md in full. Internalize every rule, severity level, and example.
Step 2: Run the automated scan
Execute the scan script on each file:
bash .claude/skills/style-review/scripts/scan-style.sh <file-path>
Record any findings from the script output.
Step 3: Read each file
Use your file-reading tool to load the full content of every file under review. Do not rely solely on the scan script; it only catches pattern-matchable violations.
Step 4: Qualitative review
The scan script handles pattern-matchable violations. Your job in this step is to find issues that require reading comprehension. These are documented in the "Qualitative Checks" section of style-review/SKILL.md. Focus on:
- Subtle evergreen language (warning): phrases that imply change without using banned keywords
- Alt text quality (suggestion): generic or non-descriptive image alt text
- Link text quality (suggestion): "click here", bare URLs, or other non-descriptive anchors
- Wall-of-text paragraphs (suggestion): paragraphs exceeding ~5 sentences or ~150 words
- FAQ answer quality (warning): vague hedging, overly long answers, voice/tone shifts
- Callout block misuse (suggestion): block type doesn't match content (e.g.
:::warningfor a tip) - Heading-content mismatch (suggestion): heading promises one thing but body discusses another, or heading is too vague
- Subtle gray-label framing (warning): the scan catches literal mentions of Vendasta, Partner Center, and partner/reseller/agency terms, but reviewers should still watch for indirect partner-provider framing that regex cannot detect (e.g., "your provider configured this for you")
Multiple violations on the same line: If a single line has multiple distinct violations (e.g., a Vendasta mention AND historical language), emit separate findings for each. The post-processing pipeline handles multiple findings per line. Do not merge different violation types into a single finding.
Step 5: Verify every finding
Before including a finding in output, re-read the file and confirm:
- The
originaltext appears exactly on the claimedlinenumber - The
linenumber is correct (1-indexed, matching the file on disk) - The
replacementis a valid, complete fix for that line
Drop any finding where the original text does not match. This prevents false positives that break the post-processing pipeline.
Step 6: Output JSON
Print ONLY a valid JSON array. Nothing else.
- No markdown code fences
- No prose before or after the array
- No trailing commas
- No comments
If no issues are found, output exactly: []
Output Schema
Each finding is an object with exactly these fields:
{
"file": "docusaurus/docs/product/feature/index.md",
"line": 12,
"issue": "Vendasta mention",
"severity": "blocker",
"reason": "Gray-label product: business owners have no relationship with Vendasta.",
"original": "Vendasta's Business App makes it easy to manage reviews.",
"replacement": "Business App makes it easy to manage reviews."
}
Field definitions
| Field | Type | Description |
|---|---|---|
file |
string | File path relative to repo root |
line |
integer | 1-indexed line number |
issue |
string | Brief label (e.g. "Vendasta mention", "em dash", "third-person") |
severity |
string | One of: blocker, warning, suggestion |
reason |
string | A brief, conversational sentence explaining why this matters. Write as if you're a helpful colleague leaving a code review comment. Don't repeat the issue label -- explain the impact. Good: "Business owners reading these docs don't know about Vendasta, so we use the product name directly." Bad: "Vendasta is not allowed in documentation." Good: "We only document features that are live today." Bad: "Future-state language violates evergreen content rules." |
original |
string | The full content of that line, exactly as it appears in the file |
replacement |
string | The full corrected line content |
Severity levels
Severity is mandatory, not discretionary. Use the table below to assign severity. Do NOT escalate or downgrade from this table. A gray-label violation is always a blocker, never a warning. A formatting issue is always a suggestion, never a warning.
| Pattern | Severity | Notes |
|---|---|---|
| Vendasta mention, Partner Center reference, partner/reseller/agency/white-label terminology | blocker |
Always -- exposes internal branding to end users |
| Subtle gray-label framing (e.g. "your provider configured this") | blocker |
Always -- indirect partner-provider language is still a gray-label violation |
| Evergreen violation, future-state language ("new", "now", "recently", "coming soon") | warning |
Always -- implies impermanence |
| Third-person voice, passive voice, marketing language | warning |
Always -- degrades content quality |
| FAQ quality issues, heading-content mismatch, callout misuse | warning |
Always -- misleads or confuses readers |
| Formatting (em dash, backticks on UI elements, heading case, image conventions) | suggestion |
Always -- affects consistency, not correctness |
| Alt text quality, link text quality, wall-of-text paragraphs | suggestion |
Always -- affects readability, not correctness |
If a pattern is not in this table, use your best judgment but lean toward suggestion for cosmetic issues and warning for content-quality issues. Never use blocker for anything other than gray-label violations.
Constraints
- Do not modify any files. This is a read-only review.
- Do not output markdown, prose, or explanation. JSON array only.
- Do not invent findings. Every finding must be verifiable against the actual file content.
Source: vendasta/businessapp-docs — distributed by TomeVault.