Concept Workflow

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.