concept-workflow

• Creating a brand new concept page from scratch
• Completely rewriting an existing concept page
• When you want a full end-to-end workflow with all quality checks

For partial tasks, use individual skills instead:

• Just adding resources? Use resource-curator
• Just writing content? Use write-concept
• Just adding tests? Use test-writer
• Just verifying accuracy? Use fact-check
• Just optimizing SEO? Use seo-review

---

```

┌─────────────────────────────────────────────────────────────────────────────┐

│ COMPLETE CONCEPT WORKFLOW │

├─────────────────────────────────────────────────────────────────────────────┤

│ │

│ INPUT: Concept name (e.g., "hoisting", "event-loop", "promises") │

│ │

│ ┌──────────────────┐ │

│ │ PHASE 1: RESEARCH │ │

│ │ resource-curator │ Find MDN refs, articles, videos │

│ └────────┬─────────┘ │

│ ▼ │

│ ┌──────────────────┐ │

│ │ PHASE 2: WRITE │ │

│ │ write-concept │ Create the documentation page │

│ └────────┬─────────┘ │

│ ▼ │

│ ┌──────────────────┐ │

│ │ PHASE 3: TEST │ │

│ │ test-writer │ Generate tests for all code examples │

│ └────────┬─────────┘ │

│ ▼ │

│ ┌──────────────────┐ │

│ │ PHASE 4: VERIFY │ │

│ │ fact-check │ Verify accuracy, run tests, check links │

│ └────────┬─────────┘ │

│ ▼ │

│ ┌──────────────────┐ │

│ │ PHASE 5: OPTIMIZE│ │

│ │ seo-review │ SEO audit and final optimizations │

│ └────────┬─────────┘ │

│ ▼ │

│ OUTPUT: Complete, tested, verified, SEO-optimized concept page │

│ │

└─────────────────────────────────────────────────────────────────────────────┘

```

---

Skill: resource-curator

Goal: Gather high-quality external resources before writing

What to Do

1. Identify the concept category (fundamentals, async, OOP, etc.)
2. Search for MDN references — Official documentation
3. Find quality articles — Target 4-6 from trusted sources
4. Find quality videos — Target 3-4 from trusted creators
5. Evaluate each resource — Check quality criteria
6. Write specific descriptions — 2 sentences each
7. Format as Card components — Ready to paste into the page

Deliverables

• List of 2-4 MDN/reference links with descriptions
• List of 4-6 article links with descriptions
• List of 3-4 video links with descriptions
• Optional: 1-2 courses or books

Quality Gates

Before moving to Phase 2:

• [ ] All links verified working (200 response)
• [ ] All resources are JavaScript-focused
• [ ] Descriptions are specific, not generic
• [ ] Mix of beginner and advanced content

---

Skill: write-concept

Goal: Create the full documentation page

What to Do

1. Determine the category for file organization
2. Create the frontmatter (title, sidebarTitle, description)
3. Write the opening hook — Question that draws readers in
4. Add opening code example — Simple example in first 200 words
5. Write "What you'll learn" box — 5-7 bullet points
6. Write main content sections:

- What is [concept]? (with 40-60 word definition for featured snippet)

- Real-world analogy

- How it works (with diagrams)

- Code examples (multiple, progressive complexity)

- Common mistakes

- Edge cases

1. Add Key Takeaways — 8-10 numbered points
2. Add Test Your Knowledge — 5-6 Q&A accordions
3. Add Related Concepts — 4 Cards linking to related topics
4. Add Resources — Paste resources from Phase 1

Deliverables

• Complete .mdx file at /docs/concepts/{concept-name}.mdx
• File added to docs.json navigation (if new)

Quality Gates

Before moving to Phase 3:

• [ ] Frontmatter complete (title, sidebarTitle, description)
• [ ] Opens with question hook
• [ ] Code example in first 200 words
• [ ] "What you'll learn" Info box present
• [ ] All required sections present
• [ ] Resources section complete
• [ ] 1,500+ words

---

Skill: test-writer

Goal: Create comprehensive tests for all code examples

What to Do

1. Scan the concept page for all code examples
2. Categorize examples:

- Testable (console.log, return values)

- DOM-specific (needs jsdom)

- Error examples (toThrow)

- Conceptual (skip)

1. Create test file at tests/{category}/{concept}/{concept}.test.js
2. Create DOM test file (if needed) at tests/{category}/{concept}/{concept}.dom.test.js
3. Write tests for each code example with source line references
4. Run tests to verify all pass

Deliverables

• Test file: tests/{category}/{concept-name}/{concept-name}.test.js
• DOM test file (if applicable): tests/{category}/{concept-name}/{concept-name}.dom.test.js
• All tests passing

Quality Gates

Before moving to Phase 4:

• [ ] All testable code examples have tests
• [ ] Source line references in comments
• [ ] Tests pass: npm test -- tests/{category}/{concept}/
• [ ] DOM tests in separate file with jsdom directive

---

Skill: fact-check

Goal: Verify technical accuracy of all content

What to Do

1. Verify code examples:

- Run tests: npm test -- tests/{category}/{concept}/

- Check any untested examples manually

- Verify output comments match actual outputs

1. Verify MDN/spec claims:

- Click all MDN links — verify they work

- Compare API descriptions to MDN

- Check ECMAScript spec for nuanced claims

1. Verify external resources:

- Check all article/video links work

- Skim content for accuracy

- Verify descriptions match content

1. Audit technical claims:

- Look for "always/never" statements

- Verify performance claims

- Check for common misconceptions

1. Generate fact-check report

Deliverables

• Fact-check report documenting:

- Code verification results

- Link check results

- Any issues found and fixes made

Quality Gates

Before moving to Phase 5:

• [ ] All tests passing
• [ ] All MDN links valid
• [ ] All external resources accessible
• [ ] No technical inaccuracies found
• [ ] No common misconceptions

---

Skill: seo-review

Goal: Optimize for search visibility

What to Do

1. Audit title tag:

- 50-60 characters

- Primary keyword in first half

- Ends with "in JavaScript"

- Contains compelling hook

1. Audit meta description:

- 150-160 characters

- Starts with action word (Learn, Understand, Discover)

- Contains primary keyword

- Promises specific value

1. Audit keyword placement:

- Keyword in title

- Keyword in description

- Keyword in first 100 words

- Keyword in at least one H2

1. Audit content structure:

- Question hook opening

- Code in first 200 words

- "What you'll learn" box

- Short paragraphs

1. Audit featured snippet optimization:

- 40-60 word definition after "What is" H2

- Question-format H2s

- Numbered steps for how-to content

1. Audit internal linking:

- 3-5 related concepts linked

- Descriptive anchor text

- Related Concepts section complete

1. Calculate score and fix any issues

Deliverables

• SEO audit report with score (X/27)
• All high-priority fixes implemented

Quality Gates

Before marking complete:

• [ ] Score 24+ out of 27 (90%+)
• [ ] Title optimized
• [ ] Meta description optimized
• [ ] Keywords placed naturally
• [ ] Featured snippet optimized
• [ ] Internal links complete

---

Use this master checklist to track progress through all phases.

```markdown

# Concept Workflow: [Concept Name]

Started: YYYY-MM-DD

Target Category: {category}

File Path: /docs/concepts/{concept-name}.mdx

Test Path: /tests/{category}/{concept-name}/

---

• [ ] MDN references found (2-4)
• [ ] Articles found (4-6)
• [ ] Videos found (3-4)
• [ ] All links verified working
• [ ] Descriptions written (specific, 2 sentences)
• [ ] Resources formatted as Cards

Status: ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

• [ ] Frontmatter complete
• [ ] Opening hook written
• [ ] Opening code example added
• [ ] "What you'll learn" box added
• [ ] Main content sections written
• [ ] Key Takeaways added
• [ ] Test Your Knowledge added
• [ ] Related Concepts added
• [ ] Resources pasted from Phase 1
• [ ] Added to docs.json (if new)

Status: ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

• [ ] Code examples extracted and categorized
• [ ] Test file created
• [ ] DOM test file created (if needed)
• [ ] All testable examples have tests
• [ ] Source line references added
• [ ] Tests run and passing

Test Results: X passing, X failing

Status: ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

• [ ] All tests passing
• [ ] Code examples verified accurate
• [ ] MDN links checked (X/X valid)
• [ ] External resources checked (X/X valid)
• [ ] Technical claims audited
• [ ] No misconceptions found
• [ ] Issues fixed

Status: ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

• [ ] Title tag optimized (50-60 chars)
• [ ] Meta description optimized (150-160 chars)
• [ ] Keywords placed correctly
• [ ] Content structure verified
• [ ] Featured snippet optimized
• [ ] Internal links complete

SEO Score: X/27 (X%)

Status: ⬜ Not Started | 🟡 In Progress | ✅ Complete

---

All Phases Complete: ⬜ No | ✅ Yes

Ready to Publish: ⬜ No | ✅ Yes

Completed: YYYY-MM-DD

```

---

When executing this workflow, follow these steps:

Step 1: Initialize

```markdown

Starting concept workflow for: [CONCEPT NAME]

Category: [fundamentals/functions-execution/web-platform/etc.]

File: /docs/concepts/[concept-name].mdx

Tests: /tests/[category]/[concept-name]/

```

Step 2: Execute Each Phase

For each phase:

1. Announce the phase:

```markdown

## Phase X: [Phase Name]

Using skill: [skill-name]

```

1. Load the skill to get detailed instructions

1. Execute the phase following the skill's methodology

1. Report completion:

```markdown

Phase X complete:

- [Deliverable 1]

- [Deliverable 2]

- Quality gates: ✅ All passed

```

1. Move to next phase only after quality gates pass

Step 3: Final Report

After all phases complete:

```markdown

# Workflow Complete: [Concept Name]

• Concept Page: /docs/concepts/[concept-name].mdx
• Test File: /tests/[category]/[concept-name]/[concept-name].test.js
• Word Count: X,XXX words
• Code Examples: XX (XX tested)
• Resources: X MDN, X articles, X videos

• Tests: XX passing
• Fact Check: ✅ All verified
• SEO Score: XX/27 (XX%)

1. /docs/concepts/[concept-name].mdx (created)
2. /docs/docs.json (updated navigation)
3. /tests/[category]/[concept-name]/[concept-name].test.js (created)

```

---

Some phases can be partially parallelized, but the general flow should be:

```

Phase 1 (Resources) ──┐

├──► Phase 2 (Writing) ──► Phase 3 (Tests) ──┐

│ │

│ ┌───────────────────────────────────┘

│ ▼

└──► Phase 4 (Fact Check) ──► Phase 5 (SEO)

```

• Phase 1 before Phase 2: Resources inform what to write
• Phase 2 before Phase 3: Need content before writing tests
• Phase 3 before Phase 4: Tests are part of fact-checking
• Phase 4 before Phase 5: Fix accuracy issues before SEO polish

---

| Phase | Skill | Purpose |

|-------|-------|---------|

| 1 | resource-curator | Find and evaluate external resources |

| 2 | write-concept | Write the documentation page |

| 3 | test-writer | Generate tests for code examples |

| 4 | fact-check | Verify technical accuracy |

| 5 | seo-review | Optimize for search visibility |

Each skill has detailed instructions in its own SKILL.md file. Load the appropriate skill at each phase for comprehensive guidance.

---

| Phase | Estimated Time | Notes |

|-------|---------------|-------|

| Phase 1: Resources | 15-30 min | Depends on availability of quality resources |

| Phase 2: Writing | 1-3 hours | Depends on concept complexity |

| Phase 3: Tests | 30-60 min | Depends on number of code examples |

| Phase 4: Fact Check | 15-30 min | Most automated via tests |

| Phase 5: SEO | 15-30 min | Mostly checklist verification |

| Total | 2-5 hours | For a complete concept page |

---

To start the workflow for a new concept:

```

1. Determine the concept name and category
2. Load this skill (concept-workflow)
3. Execute Phase 1: Load resource-curator, find resources
4. Execute Phase 2: Load write-concept, write the page
5. Execute Phase 3: Load test-writer, create tests
6. Execute Phase 4: Load fact-check, verify accuracy
7. Execute Phase 5: Load seo-review, optimize SEO
8. Generate final report
9. Commit changes

```

Example prompt to start:

> "Create a complete concept page for 'hoisting' using the concept-workflow skill"

This will trigger the full end-to-end workflow, creating a complete, tested, verified, and SEO-optimized concept page.