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)
- [ 

---

*Content truncated.*