fact-check

SKILL.md

Skill: JavaScript Fact Checker

Use this skill to verify the technical accuracy of concept documentation pages for the 33 JavaScript Concepts project. This ensures we're not spreading misinformation about JavaScript.

When to Use

Before publishing a new concept 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 concept page must be verified for accuracy.

Step-by-Step Process

Identify all code blocks in the document

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

For "wrong" examples (marked with ❌):

Verify they actually produce the wrong/unexpected behavior

Confirm the explanation of why it's wrong is accurate

For "correct" examples (marked with ✓):

Verify they work as stated

Confirm they follow current best practices

Run project tests:

# Run all tests
npm test

# Run tests for a specific concept
npm test -- tests/fundamentals/call-stack/
npm test -- tests/fundamentals/primitive-types/

Check test coverage:

Look in /tests/{category}/{concept-name}/

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(this.name)  // undefined! Arrow has no this
}

Phase 2: MDN Documentation Verification

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

Step-by-Step Process

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

Verify API descriptions:

Compare method signatures with MDN

Check parameter names and types

Verify return types

Confirm edge case behavior

Check for deprecated APIs:

Look for deprecation warnings on MDN

Flag any deprecated methods being taught as current

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

Check link accessibility:

Click each external link

Verify it loads (not 404, not paywalled)

Note any redirects to different URLs

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

Check publication date:

For time-sensitive topics (async, modules, etc.), prefer recent content

Flag resources from before 2015 for ES6+ topics

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

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

❌ "JavaScript is an interpreted language"
→ Verify: Modern JS engines use JIT compilation

❌ "Objects are passed by reference"
→ Verify: Technically "passed by sharing" - the reference is passed by value

❌ "=== is faster than =="
→ Verify: Implementation-dependent, not guaranteed by spec

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

✓ "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

# Run tests for specific concept
npm test -- tests/fundamentals/call-stack/
npm test -- tests/fundamentals/primitive-types/
npm test -- tests/fundamentals/value-reference-types/
npm test -- tests/fundamentals/type-coercion/
npm test -- tests/fundamentals/equality-operators/
npm test -- tests/fundamentals/scope-and-closures/

Test Directory Structure

tests/
├── fundamentals/              # Concepts 1-6
│   ├── call-stack/
│   ├── primitive-types/
│   ├── value-reference-types/
│   ├── type-coercion/
│   ├── equality-operators/
│   └── scope-and-closures/
├── functions-execution/       # Concepts 7-8
│   ├── event-loop/
│   └── iife-modules/
└── web-platform/              # Concepts 9-10
    ├── dom/
    └── http-fetch/

When Tests Are Missing

If a concept doesn't have tests:

Flag this in the report as "needs test coverage"

Manually verify code examples are correct

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

Project Resources

Resource
Path
Use For

Test Suite
/tests/
Verify code examples

Concept Pages
/docs/concepts/
Current content

Run Tests
npm test
Execute all tests

Fact Check Report Template

Use this template to document your findings.

# Fact Check Report: [Concept Name]

**File:** `/docs/concepts/[slug].mdx`
**Date:** YYYY-MM-DD
**Reviewer:** [Name/Claude]
**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 | ✅/⚠️/❌ | [Notes] |
| 2 | [Brief description] | XX | ✅/⚠️/❌ | [Notes] |
| 3 | [Brief description] | XX | ✅/⚠️/❌ | [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:

// The corrected code

Phase 2: MDN/Specification Verification

Claim
Location
Source
Status
Notes

[Claim made]
Line XX
MDN/Spec
✅/⚠️/❌
[Notes]

MDN Link Status

Link Text
URL
Status

[Text]
[URL]
✅ 200 / ❌ 404

Specification Discrepancies

[If any claims don't match the ECMAScript spec, detail them here]

Phase 3: External Resource Verification

Resource
Type
Link
Content
Notes

[Title]
Article/Video
✅/❌
✅/⚠️/❌
[Notes]

Broken Links

Line XX: [URL] - 404 Not Found

Line YY: [URL] - Domain expired

Content Concerns

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

Description Accuracy

Resource
Description Accurate?
Notes

[Title]
✅/❌
[Notes]

Phase 4: Technical Claims Audit

Claim
Location
Verdict
Notes

"[Claim]"
Line XX
✅/⚠️/❌
[Notes]

Claims Needing Revision

Line XX: "[Current claim]"

Issue: [What's wrong]

Suggested: "[Revised claim]"

Phase 5: Test Results

Test File: /tests/[category]/[concept]/[concept].test.js
Tests Run: XX
Passing: XX
Failing: XX

Failing Tests

Test Name
Expected
Actual
Related Doc Line

[Test]
[Expected]
[Actual]
Line XX

Coverage Gaps

Examples in documentation without corresponding tests:

 Line XX: [Description of untested example]

 Line YY: [Description of untested example]

Issues Summary

Critical (Must Fix Before Publishing)

[Issue title]

Location: Line XX

Problem: [Description]

Fix: [How to fix]

Major (Should Fix)

[Issue title]

Location: Line XX

Problem: [Description]

Fix: [How to fix]

Minor (Nice to Have)

[Issue title]

Location: Line XX

Suggestion: [Improvement]

Recommendations

[Priority 1]: [Specific actionable recommendation]

[Priority 2]: [Specific actionable recommendation]

[Priority 3]: [Specific actionable recommendation]

Verification Checklist

 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

 Report complete and ready for handoff

Sign-off

Verified by: [Name/Claude]
Date: YYYY-MM-DD
Recommendation: ✅ Ready to publish | ⚠️ Fix issues first | ❌ Major revision needed

---

## Quick Reference: Verification Commands

```bash
# Run all tests
npm test

# Run specific concept tests
npm test -- tests/fundamentals/call-stack/

# Check for broken links (if you have a link checker)
# Install: npm install -g broken-link-checker
# Run: blc https://developer.mozilla.org/... -ro

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

Summary

When fact-checking a concept page:

Run tests first — npm test catches code errors automatically

Verify every code example — Output comments must match reality

Check all MDN links — Broken links and incorrect descriptions hurt credibility

Verify external resources — Must be accessible, accurate, and JavaScript-focused

Audit technical claims — Watch for misconceptions and unsupported statements

Document everything — Use the report template for consistent, thorough reviews

Remember: Our readers trust us to teach them correct JavaScript. A single piece of misinformation can create confusion that takes years to unlearn. Take fact-checking seriously.