concept-workflow

name concept-workflow description End-to-end workflow for creating complete JavaScript concept documentation, orchestrating all skills from research to final review 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: Resource Curation — Find quality learning resources Concept Writing — Write the documentation page Test Writing — Create tests for code examples Fact Checking — Verify technical accuracy 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 Identify the concept category (fundamentals, async, OOP, etc.) Search for MDN references — Official documentation Find quality articles — Target 4-6 from trusted sources Find quality videos — Target 3-4 from trusted creators Evaluate each resource — Check quality criteria Write specific descriptions — 2 sentences each 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 Determine the category for file organization Create the frontmatter (title, sidebarTitle, description) Write the opening hook — Question that draws readers in Add opening code example — Simple example in first 200 words Write "What you'll learn" box — 5-7 bullet points 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 Add Key Takeaways — 8-10 numbered points Add Test Your Knowledge — 5-6 Q&A accordions Add Related Concepts — 4 Cards linking to related topics 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 Scan the concept page for all code examples Categorize examples: Testable (console.log, return values) DOM-specific (needs jsdom) Error examples (toThrow) Conceptual (skip) Create test file at tests/{category}/{concept}/{concept}.test.js Create DOM test file (if needed) at tests/{category}/{concept}/{concept}.dom.test.js Write tests for each code example with source line references 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 Verify code examples: Run tests: npm test -- tests/{category}/{concept}/ Check any untested examples manually Verify output comments match actual outputs Verify MDN/spec claims: Click all MDN links — verify they work Compare API descriptions to MDN Check ECMAScript spec for nuanced claims Verify external resources: Check all article/video links work Skim content for accuracy Verify descriptions match content Audit technical claims: Look for "always/never" statements Verify performance claims Check for common misconceptions 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 Audit title tag: 50-60 characters Primary keyword in first half Ends with "in JavaScript" Contains compelling hook Audit meta description: 150-160 characters Starts with action word (Learn, Understand, Discover) Contains primary keyword Promises specific value Audit keyword placement: Keyword in title Keyword in description Keyword in first 100 words Keyword in at least one H2 Audit content structure: Question hook opening Code in first 200 words "What you'll learn" box Short paragraphs Audit featured snippet optimization: 40-60 word definition after "What is" H2 Question-format H2s Numbered steps for how-to content Audit internal linking: 3-5 related concepts linked Descriptive anchor text Related Concepts section complete 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: Announce the phase: ## Phase X: [Phase Name] Using skill: [skill-name] Load the skill to get detailed instructions Execute the phase following the skill's methodology Report completion: Phase X complete: - [Deliverable 1] - [Deliverable 2] - Quality gates: ✅ All passed 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 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. Time Estimates 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