Drg

All paths are relative to hugo/content/merit-badges/.

If guide/_index.md already exists, read the existing guide files and resume from their current state. If guide/_index.md does not exist yet, first run BADGE_SLUG=$ARGUMENTS bun run scaffold:drg to create the deterministic guide scaffold, then read the generated files and replace placeholders with real content.

The scaffold creates only deterministic structure: _index.md, requirement pages, extended-learning.md, print/index.md, front matter, guide_nav, prev/next links, exact requirement shortcode blocks, placeholder sections, and official resource stubs. It does not write final educational copy or polished titles.

Do not overwrite existing guide files during scaffolding. The scaffold script is idempotent and should only create missing files. Always keep or create guide/print/index.md for a printable single-page version of the full guide.

if [ ! -f "hugo/content/merit-badges/$ARGUMENTS/guide/_index.md" ]; then
  BADGE_SLUG=$ARGUMENTS bun run scaffold:drg
fi

After scaffolding, continue by reading the generated files and filling in placeholders in place.

Use the scaffolded file structure as the source of truth for page order and navigation. Replace placeholder titles like [TITLE] and [GROUP: Requirement 1] with strong editorial titles during writing, but keep the scaffolded file paths and overall page structure unless there is a deliberate reason to change them.

For v1 scaffolds, keep grouping conservative: create deterministic overview pages where the data structure calls for them (such as select parents, is_option branches, and nested all-of parents with child pages) plus one page per true leaf requirement, instead of trying to predict combined pages like req5ef.md during the initial structure pass.

Follow the scaffolded hierarchy as the default writing structure. If the scaffold gives you an overview page and child pages, write into that tree rather than collapsing it back into one giant page unless there is a deliberate editorial reason and you also update navigation consistently.

After scaffolding, you may still make editorial consolidation decisions during writing. If several standalone scaffolded pages clearly work better as one combined teaching page, you may merge them.

When merging scaffolded pages:

• preserve full requirement coverage
• preserve every official resource URL on the correct resulting page
• update guide_nav and all prev/next links consistently
• remove superseded standalone files cleanly once their content has been merged

When resuming an existing guide, do not re-scaffold unless the user explicitly wants missing files created.

Keep resource stubs in the dedicated placeholder resource blocks created by the scaffold unless you intentionally move them while preserving every official URL on the correct page.

Use the scaffolded official resource shortcodes as the baseline for requirement pages so verify:drg-resources passes as soon as the guide content is complete.

Always preserve the existing Hugo guide architecture: flat markdown files in guide/, not page-bundle subdirectories for requirement pages.

Do not create videos.json or images.json as part of scaffolding or writing.

Always keep file-path expectations aligned with scripts/verify-drg-resources.ts.

After writing, run the verification flow below before considering the guide complete:

BADGE_SLUGS="$ARGUMENTS" bun run verify:drg-resources
BADGE_SLUGS="$ARGUMENTS" bun run verify:youtube-links
bun run build

verify:drg-resources checks that every official resource appears on the correct page and that YouTube resources use the correct shortcode. verify:youtube-links is also required because it verifies that each YouTube video actually exists and is embeddable (or flags embed-disabled / broken videos). A guide is not done if verify:drg-resources passes but verify:youtube-links reports broken videos.

If the scaffold created placeholder content, replace placeholders rather than layering duplicate sections on top.

The rest of this skill describes how to turn that scaffolded structure into a high-quality finished guide.

Audience & Voice

Who is the reader?

• Primary: Scouts BSA members, ages 11–17
• Secondary: Merit badge counselors using the guide as a teaching companion
• Tertiary: Parents/guardians helping Scouts prepare

Voice Rules

What the guide is NOT

• Not a workbook. It teaches the knowledge to fulfill requirements — no fill-in-the-blank answers.
• Not a pamphlet replacement. It supplements and enriches.
• Not a merit badge counselor. It prepares the Scout for the conversation with their counselor.

Information Architecture

Every guide has exactly four page types, in this order for the primary guide flow plus a printable companion:

Introduction & Overview  → _index.md
Requirement Pages        → req{N}.md or req{N}{letter}.md
Extended Learning        → extended-learning.md
Printable Companion      → print/index.md

IMPORTANT — Flat files, not page bundles: Requirement pages and extended-learning are flat markdown files in the guide/ directory (e.g., guide/req1a.md, guide/extended-learning.md). Do NOT create subdirectories with index.md files (e.g., guide/req1a/index.md). The only files that use the directory/index.md page-bundle pattern are worksheets, the printable companion at guide/print/index.md, and the section index _index.md.

Do NOT create videos.json or images.json. Those files are managed by separate skills (drg-videos and drg-images). This skill creates only .md files.

URL Slug Convention

/merit-badges/{slug}/guide/              (Introduction & Overview — _index.md)
/merit-badges/{slug}/guide/req1a/        (Requirement 1, sub-part a — file: req1a.md)
/merit-badges/{slug}/guide/req1b/        (Requirement 1, sub-part b — file: req1b.md)
/merit-badges/{slug}/guide/req2/         (Requirement 2, no sub-parts — file: req2.md)
/merit-badges/{slug}/guide/extended-learning/  (file: extended-learning.md)

Page Grouping

Requirements are grouped by top-level number and given a descriptive group title that captures the theme (not just "Requirement 1"). This title appears in the sidebar nav and as a kicker above the H1.

Sub-requirement Splitting

Requirements with multiple sub-parts (a, b, c) can be separate pages or combined on one page. Use this heuristic:

• If sub-requirements are thematically similar and short → one page (e.g., req2.md covering 2a–2c)
• If sub-requirements are thematically distinct or lengthy → separate pages (e.g., req1a.md, req1b.md)

Combined page naming: When combining adjacent sub-requirements on one page, concatenate the letters in the filename (e.g., req5ef.md for 5e and 5f combined). Use an en dash range in the title: "Req 5e–5f — Descriptive Title". Set req_number in front matter to the first sub-requirement (e.g., "5e").

Combined page internal structure: A combined page must still preserve clear section boundaries for each covered sub-requirement. After the intro, add an explicit section heading for each sub-requirement in order (for example, ## Requirement 1a: Garden Hazards and Prevention, then ## Requirement 1b: Preventing and Treating Common Garden Health Problems). Within each sub-requirement section, use deeper headings (###) for subtopics. Do not create sibling ## headings that blur the boundary between grouped sub-requirements. The goal is that a Scout can instantly see where one sub-requirement ends and the next begins.

Umbrella Requirement Text

Many top-level requirements have vague umbrella text like "Do the following:" or "Explain the following:" that only makes sense when accompanied by the list of sub-requirements. When a page displays such an umbrella requirement via the drg/requirement shortcode, always add a brief intro paragraph immediately after the shortcode that lists what topics the page covers (as a bulleted list or short narrative). This orients the reader and prevents the page from opening with a confusing standalone phrase. Example:

{{</* drg/requirement number="4" */>}}
Explain the following:
{{</* /drg/requirement */>}}

This requirement covers four topics that every archer needs to understand:

- **Ends and rounds** — how shooting is organized
- **Field, target, and 3-D archery** — the three main formats
- ...

This applies to both combined pages (where all sub-requirements appear on one page) and overview pages (where sub-requirements link out to separate pages).

Named Artifact Investigation

Some requirements name a formal artifact instead of spelling it out in the requirement text. When that happens, do not assume the requirement text alone is enough.

A named artifact includes things like a code, policy, checklist, oath, law, acronym expansion, table, test, form, or procedure referenced by name.

Common examples:

• Scuba Diver's Code
• Safety Afloat
• Safe Swim Defense
• Outdoor Code
• named checklists, forms, and tests
• acronym expansions such as S.A.F.E.

If a requirement tells the Scout to discuss, explain, review, use, or follow a named artifact, investigate that artifact directly in the official pamphlet or other official source before writing.

When the requirement expects discussion of the artifact itself, include the actual artifact text or enumerated items on the page when appropriate so the Scout can see what they are being asked to discuss.

Do not broadly copy the pamphlet. This exception applies only to the specific named artifact needed to teach the requirement accurately.

Pamphlet Concept Lookup

Some requirements depend on a concept, procedure, acronym, or safety standard that is only briefly named in the requirement text. When that concept is important to teaching the requirement accurately, search the official pamphlet before writing instead of guessing from general knowledge.

Use pamphlet lookup for things like:

• named procedures and checks
• technical terms the Scout must explain or demonstrate
• acronym expansions
• safety standards or frameworks
• concepts that the requirement assumes the Scout already understands

If pamphlet_url exists, prefer targeted pamphlet search over broad page dumping.

Start with:

bun run search:pdf "$PAMPHLET_URL" --query "Safe Swim Defense" --ignore-case --json

Then review matched_pages and dump only the relevant pages:

bun run search:pdf "$PAMPHLET_URL" --dump-pages 19-20

If the first search misses, retry with alternate wording, acronym/full-name variants, or regex only when needed.

Use pamphlet search to confirm the official framing and terminology needed for the guide page. Do not dump or copy large pamphlet sections when only a small excerpt or enumerated list is needed.

Hybrid Parent Requirements

Some parent requirements are not just umbrellas. They contain real instructional content of their own and then continue into child sub-requirements.

Example pattern:

• Parent requirement: Explain the following terms: native metal, malleable, metallurgy, alloy, nonferrous, and ferrous. Then do the following:
• Child requirements: 2a, 2b, 2c, 2d

For these hybrid parents, do not treat the parent text as a throwaway intro. Instead, structure the page in this order:

1. Parent drg/requirement shortcode
2. Parent-specific teaching content first
3. Clearly labeled child requirement sections in order
4. A short synthesis, checklist, or bridge tying the whole page together

Use this approach when all of these are true:

• the parent requirement still has meaningful instructional content even before you read the child list
• the child requirements elaborate on, apply, or extend that parent content
• the whole requirement reads better as one coherent learning unit than as separate disconnected pages

A simple test: if removing the child requirements would still leave you with something real to teach from the parent text, treat it as a hybrid parent requirement.

Do not use the hybrid-parent pattern when the parent text is only a vague umbrella such as Do the following: or Explain the following: with no substantive standalone content. In those cases, use the normal umbrella-intro pattern instead.

Inherited Action Patterns

Some parent requirements carry the operative verbs while the child sub-requirements are only topic labels. In those cases, the page structure should mirror the action pattern instead of leaving the prose as one undifferentiated block.

Common example:

• Parent requirement: Describe the symptoms and signs of, show first aid for, and explain prevention of these wounds:
• Child requirement: Closed wounds, such as a bruise (contusion) or a hematoma

On the child section or page, organize the teaching content under ### headings that restate the parent action with the child topic. This makes the page easier for Scouts to scan and makes the relationship between the requirement and the teaching copy obvious.

Use this pattern:

{{</* drg/inherited-requirement number="3a" req_path="3.a" topic="Closed wounds, such as a bruise (contusion) or a hematoma" */>}}

### Signs and symptoms of closed wounds

Brief Scout-facing explanation of what they would notice.

### First aid for closed wounds

Brief Scout-facing explanation of what to do first.

### Prevention of closed wounds

Brief Scout-facing explanation of how to avoid the injury.

Apply this when all of these are true:

• the parent requirement supplies the verbs
• the child requirement is mainly a topic label, not a full sentence with its own verbs
• the parent action naturally breaks into distinct teaching buckets

Do not force this pattern onto every badge. If the child requirement already contains full operative text, or if the parent action does not split cleanly into reusable buckets, write normal prose instead.

Inherited Parent Sentence Pattern

Some child requirements are even simpler than the inherited-action case: the parent requirement supplies the full task, and each child is only a name, place, publication, event, or topic label.

Common examples:

• Parent requirement: Give a short biographical summary of any TWO of the following, and tell of their roles in how Scouting developed and grew in the United States.
• Child requirement: Daniel Carter Beard