QRG Generation Overview

What Is QRG Generation?

Quick Reference Guides (QRGs) are short BEFORE, DURING, and AFTER action guides derived from approved Emergency Operation Plan (EOP) annex content. The current workflow is category-first: it creates one candidate target for every completed annex and exact General User Tag Category selected on the compiled EOP.

QRGs are category-specific, not inferred-role-specific. The workflow does not discover groups in annex prose or ask an agent to map free-text role names to K12 role IDs.

Current Product Contract

Load the plan snapshot, organization, and exact General User Tag Categories.

Fetch annex forms from the compiled snapshot and clean their approved content.

Create a deterministic target for every annex/category pair. An optional request category list filters by exact category ID.

The Category Guide Generator decides whether the pair warrants a guide. Recommended targets receive BEFORE, DURING, and AFTER content; skipped targets retain an audited reason.

Store request, target, AI-call, result, and timing evidence. Save generated guides to K12 unless dry-run/no-save configuration disables the external write.

Prerequisites

Requirement	Why it matters
Compiled EOP snapshot	The snapshot anchors the annex and category source data.
At least one resolvable General User Tag Category	Categories are the audience contract; the workflow does not infer them from prose.
At least one completed annex form	Empty annex content is recorded as skipped targets.
Organization context	Determines DISTRICT or FACILITY generation scope and the save target.

Both district and facility scopes are represented by the current workflow. Do not apply the older rule that every QRG must belong to a facility or that district-linked EOPs always fail.

How Targets Become Guides

Annex classification is deterministic from the annex name. It supplies the QRG type and functional/hazard classification; it is not a separate model call.

For every non-empty annex/category target, the Category Guide Generator receives:

• the annex name, deterministic classification, and cleaned content;
• the exact category ID, name, and description;
• the DISTRICT or FACILITY scope.

The agent returns a structured decision:

• should_generate;
• recommendation_reason;
• before_event, during_event, and after_event content.

A recommended guide must contain DURING content. The saved QRG has the exact category ID in generalUserTagCategoryIds; generalUserTagIds remains empty because role mapping is not part of this workflow.

Concurrency And Ordering

Model calls use a bounded, process-wide pool. QRG_GENERATION_CONCURRENCY defaults to 4 and is clamped to 1 through 6. Results preserve source annex/category order, and external K12 saves remain sequential.

Status And Partial Results

The kickoff/status/result tools form the public asynchronous surface:

• k12-qrg-generation-kickoff;
• k12-qrg-generation-status;
• k12-qrg-generation-result;
• k12-qrg-cancel.

The final result reports target-level counts:

Field	Meaning
totalAnnexes	Annex forms considered.
totalTargets	Annex count multiplied by selected category count.
generatedTargets	Targets for which guide content was generated.
skippedTargets	Targets the agent did not recommend or whose annex was empty.
failedTargets	Targets whose model/validation processing failed.
saveFailedTargets	Generated guides that could not be written to K12.

Partial target or save failures can produce an overall success result with a warning and detailed errors. The workflow returns overall error only when all processed targets fail and none are generated or intentionally skipped.

Operational Boundaries

• dryRun: true skips external K12 writes but still exercises and persists the internal request/workflow evidence path.
• QRG_SAVE_TO_K12=false disables K12 saves.
• K12_ANNEX_FORM_TYPE_IDS optionally limits the form types fetched from the compiled snapshot.
• No placeholder guide content is generated after an agent failure.
• The exact category ID is authoritative; category names/descriptions provide semantic context only.

Source And Verification

• Workflow: packages/domain-k12/src/qrg-generation.workflow.ts
• Kickoff runner: packages/domain-k12/src/qrg/qrg-generation-workflow-runner.ts
• Schemas: packages/domain-k12/src/qrg/qrg-schemas.ts
• Agents: packages/domain-k12/src/agents/qrg-agents.ts
• Storage: packages/domain-k12/src/qrg-dedicated-storage.ts
• Local category test notes: docs/internal/k12-qrg-category-local-testing.md

Run:

npm run test:k12
npm run typecheck:k12
npm run build:k12
npm run test:live:k12:qrg-category:local

For implementation-level contracts, see QRG Generation Deep Dive and QRG Workflow.