qa-review-content
Layer 2 of grammar 2-layer strategy. Sonnet judgment for: spelling errors (confirms Layer 1 candidates against full dictionary), grammar, word choice, homophone correctness (grades Layer 1 candidates)
SKILL.mdskills/qa-review-content/SKILL.md
GitHubWhat it checks
Everything that requires judgment over visible page text. This is the Sonnet half of the 2-layer content strategy — Layer 1 (qa-detect-content-patterns) finds deterministic patterns and candidates; this layer confirms candidates and grades grammar.
Standard mode (any non-legal route)
| Issue type | severity | What it catches |
|---|---|---|
spellingError |
medium | Misspellings confirmed from Layer 1 candidateMisspelling candidates (real dictionary check) |
grammarError |
medium | Subject-verb disagreement, wrong tense, missing articles |
wordChoice |
medium | Confirmed homophone misuse from Layer 1 homophoneCandidate (your/you're, their/there/they're, its/it's, affect/effect, to/too/two, etc.) |
awkwardPhrasing |
low | Run-on sentences, stilted machine-translated copy |
capitalizationInconsistency |
low | Headings mixing Title Case / sentence case / ALL CAPS |
punctuationError |
low | Missing periods, double commas, no space after punctuation |
terminologyInconsistency |
medium | The SAME action/label uses different words across the page — "Sign in" vs "Log in", "Cancel" vs "Close", "Delete" vs "Remove", "Edit" vs "Modify". Pick one term per concept. Judge only same-meaning verbs/labels; do NOT flag genuinely different actions. |
Legal/compliance mode (route matches content.legal_routes)
Triggered automatically when the cell's route path matches a pattern in automation.config.json → content.legal_routes (default: ["/privacy", "/terms", "/legal", "/cookie", "/refund", "/shipping", "/gdpr", "/ccpa"]).
| Issue type | severity | What it catches |
|---|---|---|
missingRequiredCompliancePrivacy |
high | Privacy page missing required GDPR phrases: data controller, right to erasure, lawful basis, retention period, third-party sharing |
missingRequiredComplianceCCPA |
high | CCPA page missing "Do Not Sell My Personal Information" or right-to-know wording |
missingRequiredComplianceCookie |
high | Cookie page missing categories (necessary/analytics/marketing) and consent mechanism description |
missingRequiredComplianceTerms |
medium | T&C missing: governing law, dispute resolution, liability limitation, termination clause |
missingRequiredComplianceContact |
medium | Legal page has no contact route for the data controller / DPO |
vagueComplianceWording |
low | "We may share with partners" without specifying which/why — fails GDPR transparency |
Orchestrator flow
Run
probe.extractVisibleText— returns visible text (capped at 5,000 chars), page title, and the cell's resolved route path.Build context inputs from this cell's existing findings + config:
alreadyCaught— Layer 1 final findings (typos, plurals, i18n keys, html entities, markdown, mojibake, lorem, todo, long sentence, reading level, generic CTA). Filter findings array whereskill === 'qa-detect-content-patterns'ANDissueTypeis in the L1-final set (NOTcandidateMisspellingorhomophoneCandidate).candidateMisspellings— array of{word, snippet}from L1 findings whereissueType === 'candidateMisspelling'.homophoneCandidates— array of{word, snippet}from L1 findings whereissueType === 'homophoneCandidate'.properNouns— fromautomation.config.json → content.proper_nouns(default:[appName]).mode—"legal"if the cell's route matches any pattern incontent.legal_routes, else"standard".
Dispatch to Sonnet sub-agent with mode-specific prompt:
Standard-mode prompt
Agent(
subagent_type: "general-purpose",
model = "sonnet",
prompt = `You are reviewing the visible text of a web page for content quality issues.
Cell context:
route: {cell.route}
viewport: {cell.viewport}
browser: {cell.browser}
Proper nouns / brand names — NEVER flag these as misspellings:
{properNouns.join(", ")}
Visible text from the page:
---
{extractedText}
---
Issues already detected by Layer 1 (DO NOT re-report these patterns):
---
{alreadyCaught}
---
Layer 1 flagged these words as POSSIBLE misspellings — confirm each one with your dictionary:
---
{candidateMisspellings.map(c => `"${c.word}" in "${c.snippet}"`).join("\n")}
---
For each candidate:
- If it IS a real misspelling → emit one finding with issueType: "spellingError", snippet: candidate.word, suggestion: corrected form
- If it is NOT a misspelling (technical term, brand, valid rare word) → DROP it silently
Layer 1 flagged these sentences as homophone candidates — judge whether the homophone is used CORRECTLY in context:
---
{homophoneCandidates.map(c => `"${c.word}" in "${c.snippet}"`).join("\n")}
---
For each homophone candidate:
- If used INCORRECTLY (e.g., "your" where "you're" is needed) → emit one finding with issueType: "wordChoice", snippet: the offending phrase, suggestion: corrected form
- If used CORRECTLY → DROP it silently
Find ADDITIONAL judgment issues from these categories:
- grammarError (subject-verb / tense / articles)
- awkwardPhrasing (clear run-ons / stilted machine translation)
- capitalizationInconsistency
- punctuationError (missing period, double punctuation)
General rules:
- Do NOT re-flag patterns from "already detected" above
- Do NOT flag proper nouns from the brand list above
- Do NOT flag intentional casing like iPhone, macOS, GitHub, JavaScript, npm
- Do NOT flag URLs, email addresses, code snippets, file paths
- Limit total NEW findings to 20 per cell
- Output ONLY a valid JSON array — no prose, no markdown
Return JSON:
[
{
"issueType": "spellingError | grammarError | wordChoice | awkwardPhrasing | capitalizationInconsistency | punctuationError",
"severity": "low" | "medium" | "high",
"snippet": "<the offending text, max 80 chars>",
"suggestion":"<corrected text, max 80 chars, or null>",
"context": "<what's around it, max 80 chars, for the bug description>"
}
]
If nothing is wrong, return [].`
)
Legal-mode prompt
Agent(
subagent_type: "general-purpose",
model = "sonnet",
prompt = `You are auditing a LEGAL/COMPLIANCE page for required phrases and clarity.
Page context:
route: {cell.route}
page title: {pageTitle}
suspected category: privacy | terms | cookies | refund | shipping (infer from route)
Visible legal text:
---
{extractedText}
---
Apply the appropriate required-phrase rubric:
IF privacy/GDPR page, check for ALL of:
1. Identity of data controller (entity name + contact)
2. Right to erasure / "right to be forgotten"
3. Lawful basis for processing (consent, contract, legitimate interest, etc.)
4. Data retention period (specific duration or criteria)
5. Third-party data sharing (named recipients OR categories)
6. Data subject rights summary (access, rectification, portability)
7. Supervisory authority contact (or pointer to one)
IF CCPA page, check for ALL of:
1. "Do Not Sell My Personal Information" link / mechanism
2. Right to know what categories of personal info are collected
3. Right to delete personal info
4. Right to non-discrimination for exercising CCPA rights
5. Categories of sources from which info is collected
IF cookie page, check for ALL of:
1. Cookie categories (strictly necessary, functional, analytics, marketing)
2. Consent mechanism described (how to accept/reject)
3. Third-party cookies named OR categorized
4. How to withdraw consent / change preferences
5. Cookie retention duration
IF terms / T&C page, check for ALL of:
1. Governing law / jurisdiction
2. Dispute resolution mechanism (arbitration, court, mediation)
3. Limitation of liability
4. Termination conditions
5. Modification policy ("we may update these terms")
6. User obligations / acceptable use
For each MISSING required item, emit one finding:
issueType: missingRequiredCompliancePrivacy | missingRequiredComplianceCCPA |
missingRequiredComplianceCookie | missingRequiredComplianceTerms
severity: "high" for items 1-5, "medium" for the rest
snippet: name the missing required item (e.g., "Data retention period not specified")
suggestion: what to add
ALSO check for vague wording that fails transparency:
- "We may share with partners" without naming who/why → vagueComplianceWording
- "From time to time we may update" without notice mechanism → vagueComplianceWording
- "Reasonable security measures" with no specifics → vagueComplianceWording
Skipping rules:
- Do NOT re-flag patterns already caught by Layer 1
- Do NOT flag the absence of items that are clearly N/A for this page type
- Limit total findings to 15 per cell
- Output ONLY a valid JSON array
Return JSON:
[
{
"issueType": "missingRequiredCompliance{Privacy|CCPA|Cookie|Terms|Contact} | vagueComplianceWording",
"severity": "low" | "medium" | "high",
"snippet": "<which required item is missing, max 80 chars>",
"suggestion":"<what to add, max 80 chars>",
"context": "<surrounding text excerpt, max 80 chars>"
}
]
If page is fully compliant, return [].`
)
Receive the JSON array back. For each finding, convert into the standard issue schema:
{ skill: "qa-review-content", issueType: <finding.issueType>, severity: <finding.severity>, selector: null, description: `${finding.context} → "${finding.snippet}"` + (finding.suggestion ? ` (suggestion: "${finding.suggestion}")` : ''), bbox: null }Append to issues. Apply the standard screenshot step from qa-argus (cell-level capture is sufficient; per-finding annotation is not meaningful for content issues — they don't have bboxes).
Probe (browser_evaluate)
// probe.extractVisibleText
() => {
const SKIP_TAGS = new Set(['SCRIPT', 'STYLE', 'NOSCRIPT', 'NAV', 'FOOTER', 'IFRAME']);
const out = [];
const walk = (node) => {
if (!node) return;
if (node.nodeType === Node.ELEMENT_NODE) {
if (SKIP_TAGS.has(node.tagName)) return;
if (node.getAttribute && node.getAttribute('aria-hidden') === 'true') return;
const style = node.nodeType === 1 ? window.getComputedStyle(node) : null;
if (style && (style.display === 'none' || style.visibility === 'hidden')) return;
}
if (node.nodeType === Node.TEXT_NODE) {
const t = (node.textContent || '').replace(/\s+/g, ' ').trim();
if (t.length >= 2) out.push(t);
return;
}
for (const c of (node.childNodes || [])) walk(c);
};
walk(document.body);
let combined = out.join(' ').replace(/\s+/g, ' ').trim();
// Cap at 5000 chars: keep the first 2500 + last 2500
if (combined.length > 5000) {
combined = combined.slice(0, 2500) + ' … ' + combined.slice(combined.length - 2500);
}
return {
text: combined,
charCount: combined.length,
pageTitle: document.title || '',
routePath: location.pathname + location.search
};
}
Cost control
[grammar]
critical_routes = ["/", "/login", "/signup", "/checkout", "/dashboard"]
max_cells = 10
max_chars = 5000
If critical_routes is empty [], the skill runs on every cell. Legal routes (matching content.legal_routes) ALWAYS run regardless of critical_routes — compliance is mandatory.
Mode-selection algorithm
mode = "standard"
for pattern in content.legal_routes:
if cell.route matches pattern (string contains, case-insensitive):
mode = "legal"
break
Default content.legal_routes: ["/privacy", "/terms", "/legal", "/cookie", "/refund", "/shipping", "/gdpr", "/ccpa"].
Issue schema mapping
The Sonnet sub-agent returns {issueType, severity, snippet, suggestion, context}. The orchestrator maps each to the standard issue record:
| Sub-agent field | Issue record field |
|---|---|
issueType |
issueType |
severity |
severity |
snippet + context + suggestion |
combined into description |
null |
selector (content findings have no element selector) |
null |
bbox (no element box) |
Cell-skipping rules
- Self-skip if
probe.extractVisibleTextreturnscharCount < 50(likely a redirect, loader, or blank state) - Self-skip if standard-mode AND route is in
customize.toml → grammar.critical_routeswhitelist AND current route is NOT in the list - NEVER self-skip in legal-mode — compliance check is mandatory on legal routes
- Hard cap after
customize.toml → grammar.max_cellsreached (standard mode only; legal-mode cells are uncapped)
Notes
- No external dependencies, no third-party API, no spellcheck library
- Does NOT modify the page, never types, never clicks, never navigates
- Brand-aware: reads
automation.config.json → content.proper_nounsto suppress brand false-positives at Sonnet prompt level - 2-layer contract: Layer 1 candidates are explicitly confirmed or dismissed — no double-reporting, no missed catches
- Legal-mode is route-triggered automatically — no flag needed in customize.toml beyond keeping the skill enabled