Concept Workflow

Skill: Complete Concept Workflow

Use this skill to create a complete, high-quality concept page from start to finish. This skill orchestrates all five specialized skills in the optimal order:

1. Resource Curation — Find quality learning resources 2. Concept Writing — Write the documentation page 3. Test Writing — Create tests for code examples 4. Fact Checking — Verify technical accuracy 5. SEO Review — Optimize for search visibility

When to Use

• 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

---

Workflow Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                     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              │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

---

Phase 1: Resource Curation

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

---

Phase 2: Concept Writing

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

7. Add Key Takeaways — 8-10 numbered points 8. Add Test Your Knowledge — 5-6 Q&A accordions 9. Add Related Concepts — 4 Cards linking to related topics 10. 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

---

Phase 3: Test Writing

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)

3. Create test file at tests/{category}/{concept}/{concept}.test.js 4. Create DOM test file (if needed) at tests/{category}/{concept}/{concept}.dom.test.js 5. Write tests for each code example with source line references 6. 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

---

Phase 4: Fact Checking

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

2. Verify MDN/spec claims:

• Click all MDN links — verify they work
• Compare API descriptions to MDN
• Check ECMAScript spec for nuanced claims

3. Verify external resources:

• Check all article/video links work
• Skim content for accuracy
• Verify descriptions match content

4. Audit technical claims:

• Look for "always/never" statements
• Verify performance claims
• Check for common misconceptions

5. 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

---

Phase 5: SEO Review

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

2. Audit meta description:

• 150-160 characters
• Starts with action word (Learn, Understand, Discover)
• Contains primary keyword
• Promises specific value

3. Audit keyword placement:

• Keyword in title
• Keyword in description
• Keyword in first 100 words
• Keyword in at least one H2

4. Audit content structure:

• Question hook opening
• Code in first 200 words
• "What you'll learn" box
• Short paragraphs

5. Audit featured snippet optimization:

• 40-60 word definition after "What is" H2
• Question-format H2s
• Numbered steps for how-to content

6. Audit internal linking:

• 3-5 related concepts linked
• Descriptive anchor text
• Related Concepts section complete

7. 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

---

Complete Workflow Checklist

Use this master checklist to track progress through all phases.

# Concept Workflow: [Concept Name]

**Started:** YYYY-MM-DD
**Target Category:** {category}
**File Path:** `/docs/concepts/{concept-name}.mdx`
**Test Path:** `/tests/{category}/{concept-name}/`

---

## Phase 1: Resource Curation
- [ ] 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

---

## Phase 2: Concept Writing
- [ ] 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

---

## Phase 3: Test Writing
- [ ] 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

---

## Phase 4: Fact Checking
- [ ] 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

---

## Phase 5: SEO Review
- [ ] 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

---

## Final Status

**All Phases Complete:** ⬜ No | ✅ Yes
**Ready to Publish:** ⬜ No | ✅ Yes
**Completed:** YYYY-MM-DD

---

Execution Instructions

When executing this workflow, follow these steps:

Step 1: Initialize

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:

   ## Phase X: [Phase Name]
   Using skill: [skill-name]

2. Load the skill to get detailed instructions

3. Execute the phase following the skill's methodology

4. Report completion:

   Phase X complete:
   - [Deliverable 1]
   - [Deliverable 2]
   - Quality gates: ✅ All passed

5. Move to next phase only after quality gates pass

Step 3: Final Report

After all phases complete:

# Workflow Complete: [Concept Name]

## Summary
- **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

## Quality Metrics
- **Tests:** XX passing
- **Fact Check:** ✅ All verified
- **SEO Score:** XX/27 (XX%)

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

## Ready to Publish: ✅ Yes

---

Phase Dependencies

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

---

Skill Reference

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

---

Time Estimates

---

Quick Start

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.