DDx Content Generator — Layer A

Each pass has explicit inputs, outputs, and gate conditions. Do not skip passes.

Pass 0 — Preflight (deterministic)

Purpose: Verify all reference files are present, internally consistent, and ready for generation.

Run: python3 scripts/preflight.py

What it checks:

• All required reference files exist in references/
• strategy-types.json contains exactly 14 entries
• skill-definitions.json contains exactly 12 skills
• Every skill's EF domains are from: working_memory, cognitive_flexibility, inhibition
• Every strategy type's arcState is one of: clear, watch, blocker, blocker_cascade
• Every strategy type's efStrategy values are from: compensate, accommodate, strengthen, stabilize
• constraints.json contains all required fields
• The sequencing matrix covers all 12 cells (4 EF tiers × 3 ARC states)

Gate: If preflight fails, output the specific failures and STOP. Do not proceed to Pass 1.

Output: output/preflight-result.json

Pass 1 — Skill Kit (AI-generated, human-reviewed)

Purpose: Pre-compute canonical definitions for this skill so they don't drift across 14 entries.

Input: Read these reference files for the target skill:

1. references/preamble.md — clinical model, population context, voice rationale
2. references/skill-definitions.json — the skill's family, pillar, EF domains, ARC needs
3. references/family-mechanisms.md — the skill family's EF/ARC narratives
4. references/voice-guide.md — tone rules, voice anchors
5. references/constraints.json — banned tokens list
6. Family voice anchor — select the matching anchor from the Canonical Family Voice Anchors section below based on this skill's skillFamily

Output shape: Generate a JSON object with:

{
  "skillName": "...",
  "skillFamily": "...",
  "pillar": "...",
  "primaryEF": "...",
  "secondaryEF": "...",
  "tertiaryEF": null,
  "primaryARCNeedHypothesis": "...",
  "secondaryARCNeedHypothesis": "...",
  "familyMechanism": "...",
  "familyVoiceAnchor": {
    "corePattern": "Selected verbatim from canonical anchors based on skillFamily",
    "causalLanguage": "Selected verbatim from canonical anchors based on skillFamily",
    "strengthRegister": "Selected verbatim from canonical anchors based on skillFamily"
  },
  "efMechanismDetail": {
    "{primaryEF}": "How this EF domain constrains THIS skill specifically",
    "{secondaryEF}": "How secondary EF domain interacts",
    "interaction": "How both constrained (EF-2) creates compound effect for THIS skill"
  },
  "studentVoiceLexicon": {
    "skillDefinitionSimple": "Plain language for what this skill is",
    "strengthPhrases": ["3 phrases for strengths lead"],
    "commonStruggles": ["3 phrases for growth edge"],
    "efPlainLanguage": { "{ef}": "Plain language explanation" },
    "arcPlainLanguage": { "{need}": ["Plain language terms"] }
  },
  "coachRuleOutBanks": {
    "universal": ["3-5 universal rule-outs"],
    "familySpecific": ["2-3 family-specific rule-outs"],
    "skillSpecific": ["3-5 skill-specific rule-outs"],
    "arcWatch": ["2-3 watch-state rule-outs"],
    "arcBlocker": ["2-3 blocker-state rule-outs"],
    "efDomain": ["2-3 EF-domain rule-outs"],
    "equityReminders": ["3-4 equity reminders"]
  }
}

Gate: Present the Skill Kit to the user for review. Do not proceed to Pass 2 until approved.

Output: output/skill-kits/{skillName}.json

Pass 2 — Generate entries (AI-generated)

Purpose: Generate all 14 DDx entries for this skill.

Input: Load these references:

• output/skill-kits/{skillName}.json — the approved Skill Kit
• references/strategy-types.json — the 14 strategy type definitions
• references/schema.json — entry output shape
• references/sequencing-matrix.json — EF × ARC temporal guidance with timeframes
• references/arc-watch-blocker.md — tone differentiation for ARC states
• references/authoring-instructions.md — field-by-field authoring rules
• references/voice-guide.md — tone rules and voice anchors
• references/feedback-template.md — feedback structure template
• references/constraints.json — banned tokens, reading level, required caveats
• references/strength-compositing.md — strength signal compositing model and construct glossary

Generation order: Generate entries in escalating order. Each entry builds on the previous:

1. pure_skill_gap (EF-0, clear) — most optimistic baseline
2. skill_coaching (EF-0, clear) — standard coaching
3. monitor_need_coach (EF-0, watch) — add need monitoring
4. address_need_first (EF-0, blocker) — need restoration priority
5. scaffold_targeted (EF-1, clear) — add primary EF scaffold
6. scaffold_targeted_monitor (EF-1, watch) — scaffold + need monitoring
7. compensate_targeted_need (EF-1, blocker) — scaffold + need restoration
8. compensate_change (EF-2, clear) — dual EF compensation
9. compensate_scaffold_monitor (EF-2, watch) — compensation + need monitoring
10. compensate_need_high (EF-2, blocker) — compensation + need restoration
11. compensate_heavy (EF-3, clear) — comprehensive compensation
12. compensate_heavy_monitor (EF-3, watch) — comprehensive + need monitoring
13. compensate_heavy_need_max (EF-3, blocker) — comprehensive + need restoration
14. clinical_screen (EF-3, blocker_cascade) — clinical referral pathway

Critical content rules (apply to every entry):

1. Reading level: 8th grade Flesch-Kincaid target, 12th grade maximum ceiling. Max ~16 words/sentence average. Max 4 sentences in insightBody. No em dashes. No bare construct names in student text.
2. Banned student token: NEVER use "brain" in student-facing text.
3. Micro-caveat: insightBody must include the correct variant from constraints.json. Strategies 1–12 use the standard variant. Strategy 13 (clinical_screen) uses the clinicalScreen variant. Use exact text from constraints.json.
4. Scaffold closing: scaffoldSequence must end with: "If structured supports do not improve performance within {timeframe}, revisit all hypotheses." Use timeframe from constraints.json timeframeMap.
5. Feedback headers: feedbackStructure must include all three headers: "What's Working", "Growth Edge", "Next Step".
6. Rule-out checklist: 3-5 items. Must include one cultural communication norms item and one language/code-switching item.
7. Clinical screen: Register shift from coaching to concern. Must include "referral" and "scope of coaching" language.
8. Pure skill gap: Must NOT mention EF, executive function, motivational strain, barriers, or constraints. Maximally optimistic.
9. No assessment taxonomy in student text. Never use bare construct names: "working memory," "inhibition," "cognitive flexibility," "autonomy," "relatedness," "competence," "executive function," "intrinsic motivation." Describe what each capacity does in everyday language. See strength-compositing.md construct glossary. Coach text may use clinical terms.
10. EF-3 tags: All EF-3 entries must set tags.heavyCompensation = true.
11. Family voice anchor: Use the Skill Kit's familyVoiceAnchor for all causal explanations (insightBody, growthEdge, clinicalSummary, hypotheses) and strength framing (strengthsLead, strengthsLeverage). Do not borrow vocabulary from other families' anchors.
12. Strength compositing: strengthsLead must blend all available strength signals for the entry's strategy type. See strength-compositing.md. Do not pick one signal. Each entry's strengthsLead must be distinct from other strategy types for the same skill.
13. Em dash ban: No em dashes (—) or en dashes (–) in student text. Use periods and shorter sentences.
14. Coach addressing: Coach text addresses the coach as "you" or uses imperative voice. Never "the coach can/should/may."
15. Pronoun clarity: Max one pronoun (it, them, they, this, that) per sentence in student text. Restate the noun when the referent could be unclear.

Output: output/entries/{skillName}-all.json — single file with all 14 entries

Pass 3 — Lint + Assemble (deterministic)

Purpose: Validate every entry against hard rules.

Run: python3 scripts/lint.py output/entries/{skillName}-all.json

What the linter checks:

• No empty required fields
• "brain" not in studentText
• insightBody contains correct micro-caveat variant (standard for strategies 1-12, clinicalScreen for strategy 13)
• ruleOutChecklist: 3-5 items with cultural + code-switching items
• feedbackStructure contains all three headers
• scaffoldSequence ends with required closing line + correct timeframe
• clinical_screen has referral language
• pure_skill_gap has no EF/barrier language (word-boundary matching)
• EF-3 entries have tags.heavyCompensation = true
• clinical_screen has tags.cascade and tags.clinicalScreen

If lint fails: Fix the specific entries and re-run lint. Do not re-generate all 14.

Output: output/validated/{skillName}.json — final deliverable

Batch execution order (one skill per session)

Process in this order. Review after each family's first skill before continuing.

Review gates:

• After Run 1: review Resilience quality, adjust voice guide or authoring instructions
• After Run 3: review Critical Thinking, adjust for cognitive family patterns
• After Run 7: review Empathy, adjust for interpersonal family patterns

Reference files

Canonical Family Voice Anchors

Pass 1 selects the correct anchor based on skillFamily and includes it verbatim in the Skill Kit. These are human-authored and must not be paraphrased or adapted by the generator.

Self-Directed (Initiative, Resilience)

{
  "corePattern": "The core pattern is a knowing-doing gap — the student has strategies but can't access them under pressure. Frame the issue as blocked access, not missing knowledge.",
  "causalLanguage": "Explain mechanisms as processing pathways being blocked: the feeling arrives before the plan, the intention can't organize the action, the strategy disappears under stress.",
  "strengthRegister": "Frame strengths as: 'You know what to do. You have real strategies. They work when the conditions are right.' The gap isn't about knowledge or motivation. It's about access under pressure. Ground every strength claim in a specific context where the student succeeds. Use strength-compositing.md compositing rules."
}

Interpersonal (Empathy, Communication, Collaboration, Relationship-Building, Networking, Social Awareness)

{
  "corePattern": "The core pattern is a delivery gap — the student has the social understanding but the signal doesn't land as intended. Frame the issue as execution under pressure, not missing social capacity.",
  "causalLanguage": "Explain mechanisms as the message getting distorted between intention and reception: the student knows what to say but the timing is off, the impulse arrives before the judgment, the social read is there but the response overshoots.",
  "strengthRegister": "Frame strengths as: 'You understand people. You read situations well. That shows up when the pressure is manageable.' The ability to connect is real. The delivery under pressure is the gap. Ground every strength claim in a specific context where the student connects well. Use strength-compositing.md compositing rules."
}

Cognitive (Critical Thinking, Creative Problem Solving, Adaptability, Curiosity)

{
  "corePattern": "The core pattern is a capacity limitation — the demand exceeds what the student can hold, sequence, or shift between at once. Frame the issue as load management, not missing ability.",
  "causalLanguage": "Explain mechanisms as processing bandwidth being exceeded: the student can do the thinking when the load is manageable, but when multiple streams compete, the system bottlenecks. The thinking is there — the orchestration is the challenge.",
  "strengthRegister": "Frame strengths as: 'Your thinking is strong when you're not juggling too many things at once.' The ability is real. The challenge is when too much competes for your attention at the same time. Ground every strength claim in a specific context where the student thinks well. Use strength-compositing.md compositing rules."
}

Exemplar: Resilience (structural reference only)

The Resilience batch (14 entries) is available as a structural reference:

• Skill Kit: output/skill-kits/Resilience.json
• Entries: output/entries/resilience-all.json

Use the Resilience entries as a reference for entry structure, field length, escalation pacing, and formatting conventions. Do NOT use them as a voice reference — each skill's voice comes from its own familyVoiceAnchor in the Skill Kit.

Note: causalLanguage phrases in the anchors above are for agent use. When writing student-facing text, translate all mechanism language into everyday terms using the strength-compositing.md construct glossary. When writing coach-facing text, clinical precision is appropriate.