| name | exam-question-organizer |
| description | Reorganize practice exam questions by domain, skill, and task metadata for any certification exam, then update the coverage table on the exam README. Use when asked to organize practice exams, classify exam questions by domain, or update practice exam coverage. |
| user-invokable | true |
| argument-hint | [exam] |
Practice Exam Organizer
Reorganize a practice exam README.md to group questions under their correct exam domain and skill headings, with task-level metadata on each question. After reorganizing, update the coverage table on the exam's main README.
When to Use
- Organizing or reorganizing practice exam questions by domain structure
- Classifying exam questions into domain → skill → task hierarchy
- Updating the Practice Exam Coverage table after questions are added or removed
Prerequisites
Every question block must already have **Domain:**, **Skill:**, and **Task:** metadata lines immediately after its question heading (#### in single-file mode, ### in per-domain mode). These metadata lines are the single source of truth for classification — the script does not infer classification from question content.
Two additional optional metadata lines may follow: **Answer Result:** (values: wrong, unsure, correct) and **ID:** (7-character hex identifier). Missing Answer Result defaults to unsure; missing ID is deterministically generated from the question title on write.
If questions are missing metadata, add the metadata manually before running the organizer. Use the exam's Skills.psd1 file (e.g., certs/AZ-104/Skills.psd1) to find the correct domain, skill, and task values.
File Modes
The script auto-detects the file layout per exam:
- Single-file mode — All questions live in
practice-questions/README.md. Used by AZ-104 and legacy exams.
- Per-domain mode — Questions are split into numbered
.md files (e.g., 01-identity-governance-monitoring.md). README.md is an index page. Used by AZ-305 and future exams.
Detection: if practice-questions/ contains .md files beyond README.md, the script uses per-domain mode.
Target Files
Single-file exams:
| Exam | Practice Exam File | Domain Reference | Coverage Table |
|---|
| AZ-104 | certs/AZ-104/practice-questions/README.md | certs/AZ-104/Skills.psd1 | certs/AZ-104/README.md — Practice Exam Coverage section |
| AI-103 | certs/AI-103/practice-questions/README.md | certs/AI-103/Skills.psd1 | certs/AI-103/README.md — Practice Exam Coverage section |
Per-domain exams:
| Exam | Practice Exam Files | Domain Reference | Coverage Table |
|---|
| AZ-305 | certs/AZ-305/practice-questions/01-identity-governance-monitoring.md
certs/AZ-305/practice-questions/02-data-storage.md
certs/AZ-305/practice-questions/03-business-continuity.md
certs/AZ-305/practice-questions/04-infrastructure.md | certs/AZ-305/Skills.psd1 | certs/AZ-305/README.md — Practice Exam Coverage section |
| SC-300 | certs/SC-300/practice-questions/01-user-identities.md
certs/SC-300/practice-questions/02-authentication-access-management.md
certs/SC-300/practice-questions/03-workload-identities.md
certs/SC-300/practice-questions/04-identity-governance.md | certs/SC-300/Skills.psd1 | certs/SC-300/README.md — Practice Exam Coverage section |
Legacy support (explicit request only):
| Exam | Practice Exam File | Domain Reference | Coverage Table |
|---|
| AI-900 | certs/AI-900/practice-questions/README.md | certs/AI-900/Skills.psd1 | certs/AI-900/README.md — Practice Exam Coverage section |
If no exam is specified, ask which exam to process.
Script
The reorganizer is implemented as a deterministic PowerShell script:
.assets/scripts/Invoke-PracticeExamReorganizer.ps1
Usage
# Preview changes without modifying files
.assets/scripts/Invoke-PracticeExamReorganizer.ps1 -ExamName AZ-104 -WhatIf -Verbose
# Execute reorganization
.assets/scripts/Invoke-PracticeExamReorganizer.ps1 -ExamName AZ-104 -Verbose
What the Script Does
- Loads domain structure — Loads the exam's
Skills.psd1 via Import-PowerShellDataFile to extract the canonical domain → skill → task ordering.
- Parses question blocks — Extracts every
#### question block with its **Domain:**, **Skill:**, and **Task:** metadata. Preserves full body content exactly (question text, answer options, <details> blocks).
- Sorts by canonical order — Orders questions by domain index, then skill index (from the exam README), preserving relative order within each skill.
- Regenerates file — Writes the reorganized file with proper
#/##/###/#### heading hierarchy, nested TOC with anchor links (including GitHub-style -1, -2 dedup for duplicates), and --- separators between questions.
- Updates coverage table — Counts questions per task from metadata and updates the Qs column in the exam README's coverage table.
- Verifies — Confirms question count matches, all metadata is present, and reports any gaps or unrecognized domain/skill values.
Warnings
The script emits warnings for:
- Unrecognized domain/skill — When a question's
**Skill:** value does not match any skill in the exam's Skills.psd1. These questions sort to the end of their domain group. Fix the metadata to match the exact wording from the exam's Skills.psd1.
- Metadata gaps — When questions are missing
**Domain:**, **Skill:**, or **Task:** lines. Add the missing metadata before re-running.
- Count mismatch — When the number of questions written differs from the number parsed. This indicates a parsing bug.
Output Structure
Heading Hierarchy
Single-file mode (AZ-104, AI-103, legacy):
| Element | Heading | Notes |
|---|
| Page title | # | # Practice Exam Questions - <EXAM> (single H1) |
| Domain | ## | Matches the domain name from the question metadata |
| Skill | ### | Matches the skill name from the question metadata |
| Question | #### | Existing question title — preserved exactly |
Per-domain mode (AZ-305, future exams):
| Element | Heading | Notes |
|---|
| Page title | # | # Practice Questions — <Domain Name> (one file per domain) |
| Skill | ## | Matches the skill name from the question metadata |
| Question | ### | Existing question title — preserved exactly |
Question Metadata Format
Immediately after each question heading (#### single-file, ### per-domain), separated by a blank line:
Single task:
**Domain:** <domain name>
**Skill:** <skill name>
**Task:** <task description>
**Answer Result:** <wrong|unsure|correct>
**ID:** <7-char-hex>
Multiple tasks:
**Domain:** <domain name>
**Skill:** <skill name>
**Task:**
- <task description 1>
- <task description 2>
**Answer Result:** <wrong|unsure|correct>
**ID:** <7-char-hex>
- Answer Result — Tracks the user's outcome on the question. Values:
wrong, unsure, correct. Defaults to unsure when missing. The reorganizer sorts questions within each skill group by result: wrong first, then unsure, then correct.
- ID — A stable 7-character hex identifier derived from the SHA-256 hash of the lowercased question title. Generated by the extractor at extraction time. The reorganizer script deterministically generates an ID from the title when missing; existing IDs are preserved.
Task descriptions must match the exact wording from the exam's Skills.psd1.
Table of Contents
After the page title, a nested bullet-point TOC with anchor links:
* [Domain Name](#domain-anchor)
* [Skill Name](#skill-anchor)
* [Question Title](#question-anchor)
Ordering Rules
- Domains appear in exam order (Domain 1 first).
- Skills appear in the order listed in the exam README.
- Answer result — Within each skill, questions are sorted by answer result priority:
wrong first, then unsure, then correct. This surfaces the questions that need the most review.
- Questions with the same answer result within a skill preserve their relative order from the source file.
- Omit skills that have no questions assigned to them.
Workflow
Step 1 — Run the Script
Execute the reorganizer script for the target exam:
.assets/scripts/Invoke-PracticeExamReorganizer.ps1 -ExamName <EXAM> -Verbose
Step 2 — Review Output
Check the script's summary output for:
- Question count verification (parsed vs. written)
- Metadata completeness (all Domain/Skill/Task present)
- Warnings about unrecognized domain/skill values
Step 3 — Fix Issues (if any)
If warnings were reported:
- Unrecognized domain/skill — Edit the question's metadata to match the exact wording from the exam's
Skills.psd1, then re-run the script.
- Missing metadata — Add
**Domain:**, **Skill:**, and **Task:** lines to the question block, then re-run.
- Count mismatch — Investigate the practice questions file for parsing edge cases (missing
--- separators, malformed headings).
Rules
- Do not alter question text, answer options, screenshots,
<details> blocks, or explanation content.
- Do normalize question heading levels to
#### (single-file) or ### (per-domain).
- Do ensure every question has
**Domain:**, **Skill:**, and **Task:** metadata.
- Metadata is the single source of truth for classification — no LLM inference is used.
- The script is idempotent — running it multiple times produces the same result.
