copy-editing-evaluation

name: copy-editing-evaluation description: Evaluates grammar, spelling, and formatting in design systems' documentation. Use when checking mechanics like spelling, punctuation, heading hierarchy, and list formatting.

Copy editing

Hard technique for evaluating grammar, spelling, and formatting in design systems documentation.

Two-pass approach

1. Deterministic pass: Run the copy-editing script to get objective findings
2. Qualitative pass: Apply LLM judgment on top for context-dependent factors

The deterministic pass catches spelling errors, flagged words, heading issues, and formatting problems. The qualitative pass covers everything else: list structure, link quality, terminology consistency, and punctuation style.

Running the script

Run copy-editing.js from the same directory as this skill file. Pass the path to a markdown file as the only argument.

node <skill-directory>/copy-editing.js <file.md>

The script:

• Checks spelling using cspell with a standard English dictionary
• Flags words from @.opencode/dockit/references/flagged-words.txt in the style guide references directory (includes forbidden words and words with preferred substitutions)
• Checks heading hierarchy (skipped levels, multiple H1s) and sentence case
• Detects em-dashes
• Outputs JSON to stdout

Multi-word phrases in @.opencode/dockit/references/flagged-words.txt (e.g. "in order to", "end user") are not detected by the script. Flag those during the qualitative pass.

Output structure

The script outputs a JSON object with five keys:

{
  "spelling": [
    {
      "word": "componnet",
      "line": 5,
      "offset": 4
    }
  ],
  "forbiddenWords": [
    {
      "word": "ensure",
      "line": 9,
      "lineText": "Please ensure that you use the correct variant.",
      "suggestion": "make sure"
    },
    {
      "word": "simply",
      "line": 5,
      "lineText": "Simply add the component to your page."
    }
  ],
  "headings": [
    {
      "type": "skipped-level",
      "line": 7,
      "text": "Skipped heading",
      "message": "Heading level skipped: H2 → H4. Expected H3."
    },
    {
      "type": "multiple-h1",
      "line": 17,
      "text": "Second title",
      "message": "Multiple H1 headings found. ..."
    },
    {
      "type": "not-sentence-case",
      "line": 21,
      "text": "This Is Title Case",
      "message": "Heading is not in sentence case: \"This Is Title Case\"."
    }
  ],
  "formatting": [
    {
      "type": "em-dash",
      "line": 5,
      "lineText": "The button component — one of the most common — is used for actions.",
      "message": "Em-dash (—) found. Use an alternative phrasing or punctuation."
    }
  ],
  "summary": {
    "spelling": 1,
    "forbiddenWords": 2,
    "headings": 3,
    "formatting": 1,
    "total": 7
  }
}

spelling — misspelled words detected by cspell. Each entry has the word, the line number (1-indexed), and the character offset from the start of the file.

forbiddenWords — words from @.opencode/dockit/references/flagged-words.txt found in the document. Entries with a suggestion field are words that have a preferred replacement. Entries without suggestion are strictly forbidden and should be removed or the sentence restructured.

headings — heading hierarchy and capitalisation issues. The type field is one of skipped-level, multiple-h1, or not-sentence-case. The message field provides a human-readable description.

formatting — punctuation issues. Currently detects em-dashes (—).

summary — counts of issues by category and a total across all categories.

Scope boundary

The copy editor checks mechanics: grammar, spelling, punctuation, formatting, and structural consistency. It does not evaluate:

• Voice or tone
• Content completeness
• Readability grade level

If a sentence is grammatically correct but does not match the style guide's tone, do not flag it. If a section is thin, do not flag it. Stay in your lane.

Qualitative checks

The following checks are performed by the LLM during the qualitative pass. The script does not cover these.

Multi-word flagged phrases

The script only flags single words. During the qualitative pass, also check for multi-word phrases from @.opencode/dockit/references/flagged-words.txt such as "in order to", "for the purpose of", "end user", and "in conjunction with".

Spelling: DS-specific terminology

List formatting

Link formatting

Terminology consistency

Punctuation

Output format

[severity] Section: {section name} (line ~{number})
  Issue: {description}
  Current: "{the current text}"
  Suggested: "{the corrected text}"
  Rule: {which rule this falls under}

Copy Editing Summary:
  Spelling: {count} findings
  Headings: {count} findings
  Lists: {count} findings
  Links: {count} findings
  Terminology: {count} findings
  Punctuation: {count} findings
  Formatting: {count} findings

  Total: {count} findings ({critical} critical, {suggestions} suggestions, {nitpicks} nitpicks)