bulk-generate-concepts

name	bulk-generate-concepts
description	Use when generating multiple curriculum-aligned concept files in parallel (5+ concepts) - researches curriculum, creates concept list, spawns parallel generation agents, orchestrates review loop until all pass

Bulk Generate Concepts

Process

1. Clarify scope - Subject, grades, curriculum standard (e.g., German Rahmenlehrplan)

2. Create feature branch - Before any work:

   git fetch origin dev
   git checkout -b concepts/{subject}-grade{N} origin/dev
   

   Branch naming: concepts/{subject}-grade{N} (e.g., concepts/german-grade4)

3. Research curriculum ONCE - Use official sources (ministry sites). Extract:

   • Learning objectives per concept
   • Age-appropriate expectations
   • Difficulty progression
   • Key terminology

   Save to docs/research/{subject}-curriculum-research.md with:

   • Concept list (IDs, titles, grades, scope)
   • Extracted curriculum details per concept
   • Source URLs

   Get user approval on concept list.

4. Spawn parallel agents - One Task tool call per concept:

   Create concept: {subject}/{concept-id} (Grade {grade})
   
   1. Read `docs/concept-rules.md` first
   2. Use write-concept skill
   3. Reference `docs/{subject}-curriculum-research.md` for curriculum context
   4. **SKIP RESEARCH**: All content is provided!
   
   Scope: {one-sentence scope description}
   

   Do NOT paste curriculum content into agent prompts. Agents read the research doc themselves. Keep prompts minimal.

5. Verify files exist - Check that concept files were actually created. Agents may report success without writing files.

6. Validate - Use bun run check:concepts to efficiently check the generated concepts. If failures, resume agents with fixes.

7. Commit and create PR - Stage, commit, push, and open PR against dev:

   git add content/subjects/{subject}/ packages/frontend/public/locales/
   git commit -m "feat(content): add {Subject} Grade {N} concepts (curriculum aligned)"
   git push -u origin concepts/{subject}-grade{N}
   gh pr create --base dev --title "feat(content): {Subject} Grade {N} concepts" --body "Add {N} new concepts for Grade {N} {Subject} based on {curriculum}."
   

8. Cleanup - Delete docs/{subject}-curriculum-research.md after PR is created.

Constraints

• Max 12-14 concepts per grade (consolidate if curriculum suggests more)
• Subagents read write-concept skill themselves - don't duplicate rules
• Research happens ONCE in parent, not per-agent (saves tokens)

Common Rationalizations

Thought	Reality
"The PDF isn't readable, I'll use a different state's curriculum instead"	WRONG. Ask the user which curriculum to use. Different states have different standards, terminology, and grade-level expectations. Never substitute without explicit approval.
"German curricula are similar enough across states"	WRONG. While KMK provides national standards, state implementations differ significantly. The user chose a specific curriculum for a reason.
"I'll research what I can find and ask later"	WRONG. Clarify the curriculum source BEFORE researching. Wasted research on the wrong curriculum wastes tokens and time.
"This curriculum has better web content, so I'll use it"	WRONG. Accessibility doesn't equal correctness. If the target curriculum is hard to access, ask the user for alternative sources or approval to use a substitute.