js-docs-fact-check

name	js-docs-fact-check
description	Verify technical accuracy of JavaScript documentation by checking code examples, MDN/ECMAScript compliance, and common misconceptions. Use before publishing, after major edits, or during periodic accuracy audits.
license	Sustainable Use License 1.0
metadata	{"domain":"documentation","subdomain":"technical-docs","tags":"fact-checking, accuracy, verification, javascript, documentation, quality","author":"Yunseo Kim <[e-mail]>","lastUpdated":"12026-02-25","provenance":"adapted"}

Skill: JavaScript Fact Checker

Use this skill to verify the technical accuracy of JavaScript documentation pages. This ensures published content is correct and doesn't spread misinformation about JavaScript.

When to Use

• Before publishing a new documentation page
• After significant edits to existing content
• When reviewing community contributions
• When updating pages with new JavaScript features
• Periodic accuracy audits of existing content

What We're Protecting Against

• Incorrect JavaScript behavior claims
• Outdated information (pre-ES6 patterns presented as current)
• Code examples that don't produce stated outputs
• Broken or misleading external resource links
• Common misconceptions stated as fact
• Browser-specific behavior presented as universal
• Inaccurate API descriptions

---

Fact-Checking Methodology

Follow these five phases in order for a complete fact check.

Phase 1: Code Example Verification

Every code example in the documentation must be verified for accuracy.

Step-by-Step Process

1. Identify all code blocks in the document

2. For each code block:

   • Read the code and any output comments (e.g., // "string")
   • Mentally execute the code or test in a JavaScript environment
   • Verify the output matches what's stated in comments
   • Check that variable names and logic are correct

3. For "wrong" examples (marked with X):

   • Verify they actually produce the wrong/unexpected behavior
   • Confirm the explanation of why it's wrong is accurate

4. For "correct" examples (marked with checkmark):

   • Verify they work as stated
   • Confirm they follow current best practices

5. Run project tests (if available):

   # Run all tests
   npm test
   
   # Run tests in watch mode
   npm run test:watch
   
   # Run tests with coverage
   npm run test:coverage
   

6. Check test coverage:

   • Verify tests exist for major code examples
   • Flag examples without test coverage

Code Verification Checklist

Check	How to Verify
console.log outputs match comments	Run code or trace mentally
Variables are correctly named/used	Read through logic
Functions return expected values	Trace execution
Async code resolves in stated order	Understand event loop
Error examples actually throw	Test in try/catch
Array/object methods return correct types	Check MDN
typeof results are accurate	Test common cases
Strict mode behavior noted if relevant	Check if example depends on it

Common Output Mistakes to Catch

// Watch for these common mistakes:

// 1. typeof null
typeof null        // "object" (not "null"!)

// 2. Array methods that return new arrays vs mutate
const arr = [1, 2, 3]
arr.push(4)        // Returns 4 (length), not the array!
arr.map(x => x*2)  // Returns NEW array, doesn't mutate

// 3. Promise resolution order
Promise.resolve().then(() => console.log('micro'))
setTimeout(() => console.log('macro'), 0)
console.log('sync')
// Output: sync, micro, macro (NOT sync, macro, micro)

// 4. Comparison results
[] == false        // true
[] === false       // false
![]                // false (empty array is truthy!)

// 5. this binding
const obj = {
  name: 'Alice',
  greet: () => console.log(.)  
}

---

Phase 2: MDN Documentation Verification

All claims about JavaScript APIs, methods, and behavior should align with MDN documentation.

Step-by-Step Process

1. Check all MDN links:

   • Click each MDN link in the document
   • Verify the link returns 200 (not 404)
   • Confirm the linked page matches what's being referenced

2. Verify API descriptions:

   • Compare method signatures with MDN
   • Check parameter names and types
   • Verify return types
   • Confirm edge case behavior

3. Check for deprecated APIs:

   • Look for deprecation warnings on MDN
   • Flag any deprecated methods being taught as current

4. Verify browser compatibility claims:

   • Cross-reference with MDN compatibility tables
   • Check Can I Use for broader support data

MDN Link Patterns

Content Type	MDN URL Pattern
Web APIs	https://developer.mozilla.org/en-US/docs/Web/API/{APIName}
Global Objects	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/{Object}
Statements	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/{Statement}
Operators	https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/{Operator}
HTTP	https://developer.mozilla.org/en-US/docs/Web/HTTP

What to Verify Against MDN

Claim Type	What to Check
Method signature	Parameters, optional params, return type
Return value	Exact type and possible values
Side effects	Does it mutate? What does it affect?
Exceptions	What errors can it throw?
Browser support	Compatibility tables
Deprecation status	Any deprecation warnings?

---

Phase 3: ECMAScript Specification Compliance

For nuanced JavaScript behavior, verify against the ECMAScript specification.

When to Check the Spec

• Edge cases and unusual behavior
• Claims about "how JavaScript works internally"
• Type coercion rules
• Operator precedence
• Execution order guarantees
• Claims using words like "always", "never", "guaranteed"

How to Navigate the Spec

The ECMAScript specification is at: https://tc39.es/ecma262/

Concept	Spec Section
Type coercion	Abstract Operations (7.1)
Equality	Abstract Equality Comparison (7.2.14), Strict Equality (7.2.15)
typeof	The typeof Operator (13.5.3)
Objects	Ordinary and Exotic Objects' Behaviours (10)
Functions	ECMAScript Function Objects (10.2)
this binding	ResolveThisBinding (9.4.4)
Promises	Promise Objects (27.2)
Iteration	Iteration (27.1)

Spec Verification Examples

// Claim: "typeof null returns 'object' due to a bug"
// Spec says: typeof null -> "object" (Table 41)
// Historical context: This is a known quirk from JS 1.0
// Verdict: Correct, though calling it a "bug" is slightly informal

// Claim: "Promises always resolve asynchronously"
// Spec says: Promise reaction jobs are enqueued (27.2.1.3.2)
// Verdict: Correct - even resolved promises schedule microtasks

// Claim: "=== is faster than =="
// Spec says: Nothing about performance
// Verdict: Needs nuance - this is implementation-dependent

---

Phase 4: External Resource Verification

All external links (articles, videos, courses) must be verified.

Step-by-Step Process

1. Check link accessibility:

   • Click each external link
   • Verify it loads (not 404, not paywalled)
   • Note any redirects to different URLs

2. Verify content accuracy:

   • Skim the resource for obvious errors
   • Check it's JavaScript-focused (not C#, Python, Java)
   • Verify it's not teaching anti-patterns

3. Check publication date:

   • For time-sensitive topics (async, modules, etc.), prefer recent content
   • Flag resources from before 2015 for ES6+ topics

4. Verify description accuracy:

   • Does our description match what the resource actually covers?
   • Is the description specific (not generic)?

External Resource Checklist

Check	Pass Criteria
Link works	Returns 200, content loads
Not paywalled	Free to access (or clearly marked)
JavaScript-focused	Not primarily about other languages
Not outdated	Post-2015 for modern JS topics
Accurate description	Our description matches actual content
No anti-patterns	Doesn't teach bad practices
Reputable source	From known/trusted creators

Red Flags in External Resources

• Uses var everywhere for ES6+ topics
• Uses callbacks for content about Promises/async
• Teaches jQuery as modern DOM manipulation
• Contains factual errors about JavaScript
• Video is >2 hours without timestamp links
• Content is primarily about another language
• Uses deprecated APIs without noting deprecation

---

Phase 5: Technical Claims Audit

Review all prose claims about JavaScript behavior.

Claims That Need Verification

Claim Type	How to Verify
Performance claims	Need benchmarks or caveats
Browser behavior	Specify which browsers, check MDN
Historical claims	Verify dates/versions
"Always" or "never" statements	Check for exceptions
Comparisons (X vs Y)	Verify both sides accurately

Red Flags in Technical Claims

• "Always" or "never" without exceptions noted
• Performance claims without benchmarks
• Browser behavior claims without specifying browsers
• Comparisons that oversimplify differences
• Historical claims without dates
• Claims about "how JavaScript works" without spec reference

Examples of Claims to Verify

BAD: "async/await is always better than Promises"
-> Verify: Not always - Promise.all() is better for parallel operations

BAD: "JavaScript is an interpreted language"
-> Verify: Modern JS engines use JIT compilation

BAD: "Objects are passed by reference"
-> Verify: Technically "passed by sharing" - the reference is passed by value

BAD: "=== is faster than =="
-> Verify: Implementation-dependent, not guaranteed by spec

OK: "JavaScript is single-threaded"
-> Verify: Correct for the main thread (Web Workers are separate)

OK: "Promises always resolve asynchronously"
-> Verify: Correct per ECMAScript spec

---

Common JavaScript Misconceptions

Watch for these misconceptions being stated as fact.

Type System Misconceptions

Misconception	Reality	How to Verify
typeof null === "object" is intentional	It's a bug from JS 1.0 that can't be fixed for compatibility	Historical context, TC39 discussions
JavaScript has no types	JS is dynamically typed, not untyped	ECMAScript spec defines types
== is always wrong	== null checks both null and undefined, has valid uses	Many style guides allow this pattern
NaN === NaN is false "by mistake"	It's intentional per IEEE 754 floating point spec	IEEE 754 standard

Function Misconceptions

Misconception	Reality	How to Verify
Arrow functions are just shorter syntax	They have no this, arguments, super, or new.target	MDN, ECMAScript spec
var is hoisted to function scope with its value	Only declaration is hoisted, not initialization	Code test, MDN
Closures are a special opt-in feature	All functions in JS are closures	ECMAScript spec
IIFEs are obsolete	Still useful for one-time initialization	Modern codebases still use them

Async Misconceptions

Misconception	Reality	How to Verify
Promises run in parallel	JS is single-threaded; Promises are async, not parallel	Event loop explanation
async/await is different from Promises	It's syntactic sugar over Promises	MDN, can await any thenable
setTimeout(fn, 0) runs immediately	Runs after current execution + microtasks	Event loop, code test
await pauses the entire program	Only pauses the async function, not the event loop	Code test

Object Misconceptions

Misconception	Reality	How to Verify
Objects are "passed by reference"	References are passed by value ("pass by sharing")	Reassignment test
const makes objects immutable	const prevents reassignment, not mutation	Code test
Everything in JavaScript is an object	Primitives are not objects (though they have wrappers)	typeof tests, MDN
Object.freeze() creates deep immutability	It's shallow - nested objects can still be mutated	Code test

Performance Misconceptions

Misconception	Reality	How to Verify
=== is always faster than ==	Implementation-dependent, not spec-guaranteed	Benchmarks vary
for loops are faster than forEach	Modern engines optimize both; depends on use case	Benchmark
Arrow functions are faster	No performance difference, just different behavior	Benchmark
Avoiding DOM manipulation is always faster	Sometimes batch mutations are slower than individual	Depends on browser, use case

---

Test Integration

Running the project's test suite is a key part of fact-checking.

Test Commands

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

When Tests Are Missing

If a documentation page doesn't have tests:

1. Flag this in the report as "needs test coverage"
2. Manually verify code examples are correct
3. Consider adding tests as a follow-up task

---

Verification Resources

Primary Sources

Resource	URL	Use For
MDN Web Docs	https://developer.mozilla.org	API docs, guides, compatibility
ECMAScript Spec	https://tc39.es/ecma262	Authoritative behavior
TC39 Proposals	https://github.com/tc39/proposals	New features, stages
Can I Use	https://caniuse.com	Browser compatibility
Node.js Docs	https://nodejs.org/docs	Node-specific APIs
V8 Blog	https://v8.dev/blog	Engine internals

---

Fact Check Report Template

Use this template to document your findings.

# Fact Check Report: [Page Title]

**File:** `[file path]`
**Date:** YYYY-MM-DD
**Reviewer:** [Name]
**Overall Status:** Verified | Minor Issues | Major Issues

---

## Executive Summary

[2-3 sentence summary of findings. State whether the page is accurate overall
and highlight any critical issues.]

**Tests Run:** Yes/No
**Test Results:** X passing, Y failing
**External Links Checked:** X/Y valid

---

## Phase 1: Code Example Verification

| # | Description | Line | Status | Notes |
|---|-------------|------|--------|-------|
| 1 | [Brief description] | XX | OK/WARN/FAIL | [Notes] |
| 2 | [Brief description] | XX | OK/WARN/FAIL | [Notes] |

### Code Issues Found

#### Issue 1: [Title]

**Location:** Line XX
**Severity:** Critical/Major/Minor
**Current Code:**
` ` `javascript
// The problematic code
` ` `
**Problem:** [Explanation of what's wrong]
**Correct Code:**
` ` `javascript
// The corrected code
` ` `

---

## Phase 2: MDN/Specification Verification

| Claim | Location | Source | Status | Notes |
|-------|----------|--------|--------|-------|
| [Claim] | Line XX | MDN/Spec | OK/WARN/FAIL | [Notes] |

### MDN Link Status

| Link Text | URL | Status |
|-----------|-----|--------|
| [Text] | [URL] | 200 / 404 / Redirect |

### Specification Discrepancies

[Detail any claims that don't match the ECMAScript spec]

---

## Phase 3: External Resource Verification

| Resource | Type | Link | Content | Notes |
|----------|------|------|---------|-------|
| [Title] | Article/Video | OK/FAIL | OK/WARN/FAIL | [Notes] |

### Broken Links

1. **Line XX:** [URL] - 404 Not Found

### Content Concerns

1. **[Resource name]:** [Concern - e.g., outdated, wrong language, anti-patterns]

---



| Claim | Location | Verdict | Notes |
|-------|----------|---------|-------|
| "[Claim]" | Line XX | OK/WARN/FAIL | [Notes] |



  "[Current claim]"
  [What's wrong]
  "[Revised claim]"

---





 
 Location: Line XX
 Problem: [Description]
 Fix: [How to fix]



 
 Location: Line XX
 Problem: [Description]
 Fix: [How to fix]



 
 Location: Line XX
 Suggestion: [Improvement]

---



 [ ] All code examples verified for correct output
 [ ] All MDN links checked and valid
 [ ] API descriptions match MDN documentation
 [ ] ECMAScript compliance verified (if applicable)
 [ ] All external resource links accessible
 [ ] Resource descriptions accurately represent content
 [ ] No common JavaScript misconceptions found
 [ ] Technical claims are accurate and nuanced
 [ ] Project tests run and reviewed (if applicable)
 [ ] Report complete and ready for handoff

---



 [Name]
 YYYY-MM-DD
 Ready to publish | Fix issues first | Major revision needed

---

Quick Reference: Verification Commands

# Run all tests
npm test

# Quick JavaScript REPL for testing
node
> typeof null
'object'
> [1,2,3].map(x => x * 2)
[ 2, 4, 6 ]

---

Summary

When fact-checking a JavaScript documentation page:

1. Run tests first — npm test catches code errors automatically
2. Verify every code example — Output comments must match reality
3. Check all MDN links — Broken links and incorrect descriptions hurt credibility
4. Verify against the spec — For edge cases and "how it works" claims
5. Verify external resources — Must be accessible, accurate, and JavaScript-focused
6. Audit technical claims — Watch for misconceptions and unsupported statements
7. Document everything — Use the report template for consistent, thorough reviews

Readers trust documentation to teach them correct JavaScript. A single piece of misinformation can create confusion that takes years to unlearn. Take fact-checking seriously.