exam-question-extractor

name	exam-question-extractor
description	Extract exam questions from pasted screenshot images and format them as structured markdown. Replaces selected img tag(s) in a markdown file with the fully formatted question.
user-invokable	true
argument-hint	[image attachment and/or selection]

Question Formatter

Extracts exam question content from screenshot images and formats it as structured markdown for practice exam files.

---

⛔ MANDATORY — Single-Edit Scope (Read First)

This is the highest-priority rule. It overrides all other formatting instincts.

You must make exactly ONE edit to the file. That single edit replaces the selected <img> tag line(s) — and nothing else.

Prohibited actions

• Do not touch, reformat, rewrite, or insert content on any other line in the file.
• Do not fix typos, adjust whitespace, normalize headings, or "clean up" existing questions.
• Do not modify any text above or below the selected line(s).
• Do not make multiple edits or batch unrelated changes.

How to construct the edit

• oldString = the exact <img …> line(s) currently selected — copy them verbatim, nothing more.
• newString = the fully formatted question output (Title → Exam Metadata → Prompt → Answer → Screenshot Block → Explanation Placeholder).
• If the edit tool requires surrounding context lines for uniqueness, include the minimum necessary context but do not alter those context lines in newString.

Self-check before submitting: Does your edit change anything outside the selected <img> line(s)? If yes, discard and redo.

---

Critical Vision Requirement

Text extraction must always come from screenshot image(s) attached or pasted into the current chat.

If an image is not attached in the active chat context, image extraction cannot occur.

---

Critical Rule — No Answer Reasoning

Your only job is to reproduce the question exactly as stated with full fidelity.

• Do not evaluate, filter, or select correct answers.
• Do not reason about which options are right or wrong.
• Reproduce every answer option exactly as shown in the source — no omissions, no reordering, no commentary.

---

Output

Include:

• Title
• Exam Metadata (Domain / Skill / Task / ID)
• Prompt
• Answer
• Screenshot Block
• Explanation Placeholder

Action

Make a single edit that replaces the selected <img> line(s) with the fully formatted question markdown. Do not modify any other line in the file. Re-read the Single-Edit Scope rule above before executing.

---

Process

1. From the attached screenshot image(s), extract all visible text.

2. Detect answer state: Inspect the screenshot for signs that the question has already been submitted and graded — for example, a selected answer highlighted in green or red, a ✓ / ✗ icon, or an "Correct" / "Incorrect" banner. Mark the question as answered if any such indicator is present; otherwise mark it as blank.

3. Identify exam metadata: Determine the practice-exam file's parent exam (e.g., AZ-104, AZ-305, AI-103). Read the exam's Skills.psd1 (e.g., certs/AZ-104/Skills.psd1) to locate the domain/skill/task hierarchy. The file is a PowerShell data file with @{ Domains = @( @{ Name; Skills = @( @{ Name; Tasks = @(…) } ) } ) } structure. Match the question to the most specific domain, skill, and task(s) using best-effort reasoning.

   AI-103, AZ-104, and AZ-305 are active tracks. AI-900 can still be processed when working on completed/retired exam artifacts.

4. Identify question type:

   • Yes / No
   • Multiple Choice
   • Multiple Drop-Down
   • Drag-and-Drop Sequencing
   • Case Study (Solution Evaluation)
   • Drag-and-Drop Matching

5. Format Title, Exam Metadata, Prompt, and Answer.

6. Append Screenshot Block.

7. Append Explanation Placeholder (see rule below).

8. Replace only the selected <img> line(s) with the assembled output. Make exactly one edit. Do not touch any other part of the file.

Explanation Block Rule

• If the question is blank (no answer selected), append the empty explanation placeholder.
• If the question is answered (correct or incorrect indicator visible), invoke the exam-question-explainer skill using the same screenshot(s) to generate the explanation, then insert that explanation inside the <details> block instead of leaving it empty. You must also extract any visible References section from the screenshot (see References Extraction appendix).

---

Output Structure

Title

Create a concise exam-appropriate title (3–10 words).

Heading level rule: Before emitting the title, check the target file:

• If the target file is a per-domain practice question file (any .md file in practice-questions/ that is not README.md), use ### for the question heading. Per-domain files use # domain → ## skill → ### question.
• If the target file is a single-file practice-questions/README.md, use #### for the question heading. Single-file mode uses # title → ## domain → ### skill → #### question.

#### <Title Extracted From Image>   ← single-file (README.md)
### <Title Extracted From Image>    ← per-domain file

---

Exam Metadata

Identify the question's domain, skill, and task(s) from the exam's Skills.psd1. Place this block immediately after the title, before the prompt text.

**Domain:** <domain name (omit weight)>
**Skill:** <skill name>
**Task:** <task>
**Answered:** <Incorretly|Unsure|Correctly>
**ID:** <7-char-hex>

Rules:

• Source of truth: Read the exam's Skills.psd1 (e.g., certs/AZ-104/Skills.psd1). This is a PowerShell data file with the structure @{ Domains = @( @{ Name = '…'; Skills = @( @{ Name = '…'; Tasks = @('…') } ) } ) }. Each entry in Domains is an exam domain — use .Name for the domain name (omit weight percentages). Each domain's .Skills array contains skills — use .Name for the skill name. Each skill's .Tasks array contains task strings.

• Skill enumeration (mandatory): Before writing the **Skill:** value, enumerate all .Skills[].Name values from the Skills.psd1 and select only from that set. Never synthesize a skill name from task wording.

• Use exact wording from the Skills.psd1 for domain and skill names.

• For tasks, use the most specific task wording. Apply best-effort reasoning when the question spans topics — pick the closest match(es).

• If a question maps to a single task, place it inline on the header line: **Task:** <task>.

• If a question maps to multiple tasks (even across different skills), use a header plus bullets:

  **Task:**

  - <task 1>

  - <task 2>

• Answered — Set to one of Incorretly, Unsure, or Correctly.

• ID — Generate a deterministic 7-character hex ID by running the New-QuestionId.ps1 script in the terminal:

  .assets/scripts/New-QuestionId.ps1 -Title "<question title>"
  

  Pass the exact question title text (the heading you created in step 5). The script computes a SHA-256 hash of the lowercased title and returns the first 7 hex characters. Place the returned value on the **ID:** line.

• Insert a blank line after the metadata block before the prompt text begins.

Example:

**Domain:** Manage Azure Identities and Governance
**Skill:** Manage Azure subscriptions and governance
**Task:** Apply and manage tags on resources
**Answered:** Unsure
**ID:** c82c3e3

**Domain:** Manage Azure Identities and Governance
**Skill:** Manage Azure subscriptions and governance
**Task:**
- Apply and manage tags on resources
- Manage costs by using alerts, budgets, and Azure Advisor recommendations
**Answered:** Unsure
**ID:** a1b2c3d

---

Inline Code Formatting

Apply these rules across all generated output (prompt, explanation, and any other text):

• Wrap command names, cmdlet names, CLI commands, and parameter names in inline code (e.g., New-AzManagementGroupSubscription, Remove-AzResourceLock, --resource-group).
• Wrap referenced Azure resource names, subscription names, resource group names, storage account names, VM names, and other named objects in inline code (e.g., rgmarketing, sub020, STA01, VM1).

---

Prompt

Transcribe the question exactly as shown.

Rules:

• Preserve wording and paragraph breaks.
• Maintain layout fidelity.
• If the prompt contains a PowerShell script or command block, enclose it in a fenced code block with powershell syntax:

```powershell
Get-AzSomething -Parameter value
```

• Long PowerShell commands over 80 characters may wrap using backticks:

Get-AzSomething `
    -Parameter value `
    -Another value

---

Answer Section

Choose format based on detected question type.

---

Type 1 — Yes / No

| Statement | Yes | No |
|----------|-----|----|
| <Statement text> | ☐ | ☐ |
| <Statement text> | ☐ | ☐ |

---

Type 2 — Multiple Choice

A. <Option text>  
B. <Option text>  
C. <Option text>  
D. <Option text>  

(two trailing spaces per line required)

---

Type 3 — Multiple Drop-Down (Fill-in-the-Blank)

Used when UI shows Select or Select ▼ controls.

Cohesion reminder: When a code block contains blank placeholders, output the scenario text → code block → options table as one continuous flow with no horizontal rules or extra headings between them. The options table is part of the same question and must directly follow the code block.

• Replace each dropdown with a numbered blank token in this exact style:

___[1]___
___[2]___

• Preserve tables if present and replace each dropdown cell with the matching blank token:

| Column | Setting |
|--------|---------|
| Item A | ___[1]___ |
| Item B | ___[2]___ |

• Inline dropdowns remain inline and use the same blank token style.

Answer Format

If dropdown option screenshots exist, list choices in a single table exactly like this:

Drop-Down Options:

| Blank | Options |
|-------|---------|
| `[1]` | Option A / Option B / Option C |
| `[2]` | Option A / Option B / Option C |

If option screenshots are missing:

<!-- Dropdown options not yet provided. Paste screenshots of each expanded drop-down to populate. -->

Reference example:

Example - Multiple-Drop-Down.md

---

Type 4 — Drag-and-Drop Sequencing (Ordering)

Used when the UI shows Available options and Selected options panels, and the question asks the user to select and arrange actions in sequence or in the correct order.

• List all available options with letter labels.
• Include an ordering table with the number of steps the question requires.

Prompt format:

Transcribe the scenario text exactly, then list every available option:

A. <Option text>  
B. <Option text>  
C. <Option text>  
D. <Option text>  
E. <Option text>  

(two trailing spaces per line required)

Answer format:

Select and order <N>:

| Step | Action |
|------|--------|
| 1 | |
| 2 | |
| 3 | |

Replace <N> with the number of actions to select (e.g., "Select and order 3"). Add or remove rows to match the required count.

---

Type 5 — Case Study (Solution Evaluation)

Used when the UI shows a Case Study with a Solution Evaluation section. Multiple screenshots are provided — one per sub-question — each presenting the same scenario with a different proposed solution and asking "Does this meet the goal?"

Key indicators:

• "Case Study" header in the UI.
• "Solution Evaluation" section label.
• Instructions stating the case study contains a series of questions that present the same scenario.
• Each sub-question shares the same scenario but proposes a unique solution.
• Binary Yes / No answer per sub-question.

Prompt format:

State the case study preamble once, then transcribe the shared scenario exactly. Do not repeat the scenario for each sub-question.

*Case Study — Solution Evaluation*

This case study contains a series of questions that present the same scenario. Each question in the series contains a unique solution that might meet the stated goals. Some question sets might have more than one correct solution, while others might not have a correct solution.

<Shared scenario text>

Does this meet the goal?

Answer format:

List each solution in the order the sub-questions appear (one row per screenshot):

| Solution | Yes | No |
|----------|-----|----|
| 1. <Solution text from Question 1> | ☐ | ☐ |
| 2. <Solution text from Question 2> | ☐ | ☐ |
| 3. <Solution text from Question 3> | ☐ | ☐ |

Add or remove rows to match the number of sub-questions provided.

---

Type 6 — Drag-and-Drop Matching (Mapping)

Used when the UI shows Available options at the bottom and a list of descriptions or scenarios each paired with an empty drop target. The question asks the user to match (map) each description to the correct option. Unlike Type 4, there is no sequencing — each description independently maps to one option.

Key indicators:

• "Available options" panel with named options (not numbered steps).
• A list of descriptions, each with a blank target box.
• Instructions stating an option may be used once, more than once, or not at all.

Prompt format:

Transcribe the scenario text exactly, then present the descriptions and available options.

| Description | Answer |
|-------------|--------|
| <Description 1> | |
| <Description 2> | |
| <Description 3> | |

Available options:

Available Options:

- Option A
- Option B
- Option C

Add or remove rows/options to match the question.

---

Appendices

Screenshot Block (Collapsed)

Include all selected <img> lines inside one block.

<details>
<summary>📸 Click to expand screenshot</summary>

<img src="<path>" width=700>

</details>

Rules:

• Preserve original src.
• Keep existing width if present; otherwise normalize to width=700.
• Maintain original image order.

---

Explanation Placeholder (Open)

<details open>
<summary>💡 Click to expand explanation</summary>

</details>

Blank questions: Leave the block completely empty (no content between the tags).

Answered questions: Invoke the exam-question-explainer skill with the same screenshot(s) and insert its output between the opening and closing tags. Do not leave the block empty when an answer state is detected.

Explanation formatting: All section topic labels inside the explanation (for example, Solution 1 Explanation:, References, Key takeaway) must be bold — wrapped in **…**. No plain-text section labels are allowed.

---

References Extraction (Mandatory for Answered Questions)

When a question is answered (explanation is generated), you must extract and include any References section visible in the screenshot.

Rules

• Scan the full image, including the bottom edge. References typically appear as colored hyperlink text at the very end of the explanation area and are easy to miss.
• If a "References" heading or labeled link list is visible anywhere in the screenshot, extract every listed reference — even if partially clipped at the image boundary.
• Format each reference as a bullet-point markdown link inside the explanation <details> block under a bold References label:

**References**

* [Link title](URL)
* [Link title](URL)

• If the URL is not readable in the screenshot (clipped or too small), emit the visible link title as a plain-text bullet (e.g., * Virtual network peering). Never guess or construct a URL. The downstream exam-question-explainer skill will resolve plain-text titles into full markdown links via the markdown-link-resolver skill.
• If a partially visible reference is cut off mid-word, extract as much text as is legible and append an ellipsis (…).
• Self-check: Before finalizing the explanation, re-examine the bottom 20% of each screenshot specifically for a References section. If references are present and missing from your output, add them before submitting.
• If no references section is visible in the screenshot, do not fabricate one.

⛔ References Validation Gate (Mandatory for Answered Questions)

Before submitting the final edit, scan every * or - bullet under the References label in the generated explanation. Every bullet must be a full markdown link ([Title](URL)). If any bullet is plain text (no URL), you must invoke the markdown-link-resolver skill to resolve it before inserting the edit. Do not submit the edit with unresolved plain-text reference bullets.

---

⛔ Metadata Validation Gate

Before submitting the final edit, verify:

1. The **Skill:** value appears verbatim as a .Skills[].Name value in the exam's Skills.psd1 — not as a task string.
2. The **Task:** value appears verbatim as a .Skills[].Tasks[] string in the exam's Skills.psd1.
3. If the Skill and Task values are identical, that is almost certainly an error — re-read the Skills.psd1 and correct the Skill value.