course-review

name

course-review

description

Independently review any course-prep artifact — a blueprint, module outline, single lecture, code samples, task, quiz, full module, complete course package, compiled deliverable, raw imported source, or a finished course end-to-end — using a clean-context subagent so the author's bias does not leak into the verdict. Use when the user asks to review, validate, verify, audit, fact-check, or get a 'second pair of eyes' on educational content, or as a mandatory gate before declaring any course-prep milestone done. Triggers: review course, validate lecture, audit course, verify quiz, fact-check, review module, check the slides, vet the references, sanity-check the blueprint, course QA, course-review.

Course Review

Independent verification of any course-prep artifact using a fresh subagent — eliminates author bias from the implementing context, catches AI-specific failure modes in educational content (hallucinated APIs, dead documentation URLs, fabricated stats, mismatched learning objectives, unrealistic pacing, plagiarised passages), and produces a structured, evidence-based verdict.

The parent agent (you) does NOT do the review. Your job is to identify the target, gather a comprehensive neutral context package, then delegate the review to a clean subagent that has not seen the authoring conversation.

When to Use

• Mandatory gate at each course-prep milestone — before presenting a milestone for user approval
• After importing any third-party source into 00-raw/ (provenance, licensing, accuracy)
• When the user asks to verify, validate, audit, or fact-check any course content
• Before compiling 01-source/ → 02-dist/ for student release
• For full-course audits — when handing a course over to a co-instructor, client, or future cohort

When NOT to Use

• Trivial edits (typo, formatting tweak, single sentence)
• The user wants you to write more content, not review what exists
• The user is mid-authoring and asks "is this heading in the right direction?" — answer directly with your own context; do not spawn a subagent

Review Targets

Identify the target before launching the subagent. If ambiguous, ask one disambiguation question.

Target	Trigger phrases	Typical input
raw-input	"review the research notes", "vet this PDF", "check the imported transcript"	Files under 00-raw/
blueprint	"review the blueprint", "check Milestone 1", "validate the course plan"	01-source/_blueprint.md
module-outline	"review module 02 outline", "check the outlines"	Module outline file(s) — Milestone 2 output
lecture	"review this lecture", "fact-check lecture.md"	A single lecture.md
code	"review the code samples", "do the demos run?"	A module's code/ folder
task	"review this exercise", "check the task"	A single task .md (+ solution + starter)
quiz	"review the quiz", "check the questions"	A quiz.md (+ _quiz-answers.md)
module	"review module 03", "deep-dive on module N", "validate Milestone 3 for module N"	A full module-NN-*/ folder (lecture + code + tasks + quiz)
course-package	"review the full source", "check Milestone 4", "cross-module review"	The whole 01-source/ directory
compiled-output	"verify the slides match the source", "check the PDFs", "audit the Moodle export"	One or more files in 02-dist/ compared against 01-source/
references	"vet the references file", "URL sweep", "check all the external links"	01-source/_references.md and any other reference index
glossary	"review the glossary", "term consistency check"	01-source/_glossary.md
full-course	"audit this course end-to-end", "course health review", "handover review"	The complete course folder (00-raw/ + 01-source/ + 02-dist/)

Workflow

flowchart LR
    A[Identify target] --> B[Gather target-specific context]
    B --> C[Build neutral brief]
    C --> D[Launch Task subagent]
    D --> E[Subagent reads CRITERIA.md and OUTPUT_FORMAT.md]
    E --> F[Subagent investigates with read-only tools + web verification]
    F --> G[Devil's-advocate self-pass]
    G --> H[Return structured verdict]
    H --> I[Present verbatim to user alongside the artifact]

Step 1: Identify the target

Match the user's request against the target table. If ambiguous, ask one disambiguation question with the candidate targets as options. Do not guess — a wrong target wastes the entire review.

Step 2: Gather target-specific context

Use these concrete commands. Capture outputs as artifacts to embed in the brief.

• raw-input: list paths under 00-raw/. Capture provenance metadata if present (source URL, date imported, license). Note the inferred type (research notes, transcript, third-party doc).
• blueprint: read 01-source/_blueprint.md. Capture the user's original brief from 00-raw/original-outline.md verbatim (this is the spec).
• module-outline: read the module's outline file(s). Also capture the blueprint's row for this module (objectives, time allocation, prerequisites).
• lecture / code / task / quiz: read the target file(s) plus the parent module's outline (so the subagent knows what was supposed to be covered).
• module: list all files in module-NN-*/. Capture the module outline + the blueprint's row for this module.
• course-package: collect the tree of 01-source/ (depth 3 max, no full file dumps). Capture _blueprint.md, _references.md, _glossary.md verbatim. Do NOT read every lecture — the subagent pulls what it needs.
• compiled-output: list every file in 02-dist/. Identify the corresponding source files in 01-source/. Capture build commands / compilation tool versions if known.
• full-course: collect the full course tree (depth 4). Capture all top-level READMEs and the blueprint. Do NOT exhaustively read modules — the subagent uses Read/Grep on demand.

In all cases also collect:

• The course's original brief (00-raw/original-outline.md)
• The blueprint (01-source/_blueprint.md) — it is the contract every artifact answers to
• Any project rules (AGENTS.md, CLAUDE.md, .cursor/rules/) if they exist
• The target audience profile and stated language
• Any user-stated focus areas ("I'm worried about the React 19 examples") or known constraints

If any required context is missing (no blueprint, no brief, no clear target file), ask the user one focused question before launching the subagent.

Step 3: Build a neutral brief

The brief is the only context the subagent will see for this conversation. It must be self-contained.

Required sections:

1. Target type — one of the 11 from the table above
2. Scope summary — one line stating what is being reviewed
3. Original brief (verbatim) — the user's course request as captured in 00-raw/original-outline.md
4. Blueprint excerpt — relevant rows from 01-source/_blueprint.md (objectives, audience, tech stack with versions, time allocation)
5. Target audience — explicit profile from the blueprint (e.g., "marketing staff, no prior coding")
6. Course language — natural language of the materials (English / Ukrainian / etc.)
7. Deliverable inventory — exact file paths to review
8. Mode — default comprehensive; alternatives below
9. Severity preference — default critical/warning/suggestion; user may override
10. Verification tools available — confirm the subagent has WebSearch/WebFetch (it needs them for URL and API verification)

Anti-bias rules — DO NOT include in the brief:

• Your own justifications for why the content is correct ("I think this lecture is solid but please confirm")
• Authoring history that contains your reasoning ("I chose this example because…")
• Leading framing ("the only concern is whether the React version is current" — let the subagent find concerns)
• Apologies, hedges, or guidance about what to be lenient on
• Your own assessment of pedagogical quality — the subagent decides

A biased brief produces a biased review.

Step 4: Launch the Task subagent

Use the Task tool with a research-capable subagent type. The subagent MUST have web search/fetch tools — they are required for URL and factual verification.

Concrete subagent_type values (use the one your runtime supports):

Runtime	Read-only targets (raw-input, blueprint, module-outline, lecture, task, quiz, compiled-output)	Targets that require code execution (code, module, course-package, full-course)
Claude Code	subagent_type="explore" (read + web only)	subagent_type="general-purpose" (must have Bash)
Cursor	subagent_type="generalPurpose"	subagent_type="generalPurpose"
Claude Agent SDK	matching read-only agent definition	matching general-purpose agent definition

Bash is mandatory for code-bearing targets. If the subagent does not have Bash for code / module / course-package / full-course, abort the review and surface the missing capability to the user — running code is a load-bearing check, not a nice-to-have.

Path resolution for CRITERIA.md and OUTPUT_FORMAT.md. The subagent needs absolute paths. Use the first one that exists, in this order:

1. The directory containing this SKILL.md (if your runtime exposes that — e.g. via ${SKILL_DIR} or by Reading <this-skill>/CRITERIA.md first to confirm the path)
2. ~/.claude/skills/course-review/ (Claude Code default)
3. ~/.cursor/skills/course-review/ (Cursor default)
4. <project>/course-review/ (sibling-of-course-prep layout, as in this repo)

Substitute the resolved path everywhere <ABSOLUTE_PATH_TO_COURSE_REVIEW> appears in the template before launching.

Use this prompt template verbatim, filling in the bracketed sections:

You are an independent course reviewer. You have NOT seen the authoring conversation. Your job is to validate the deliverable against the brief with no charity, no assumptions of correctness, no editorial framing.

## Step 1: Read the criteria and output format

Read these two files first, then follow them strictly:
- <ABSOLUTE_PATH_TO_COURSE_REVIEW>/CRITERIA.md
- <ABSOLUTE_PATH_TO_COURSE_REVIEW>/OUTPUT_FORMAT.md

(The parent agent has substituted the absolute path for you above. If the path is still a placeholder, stop and report the error.)

## Step 2: Review brief

[Insert the full brief from Step 3 here]

## Step 3: Select applicable dimensions

The review target is: [target type]
Read the "Target -> applicable dimensions" table at the top of CRITERIA.md and select only the dimensions that apply to this target. Skip the rest.

## Step 4: Conduct the review

For each applicable dimension:
1. Investigate using Read, Grep, Glob, WebSearch, WebFetch — and Bash if you have it (run sample code, lint, etc. only when the brief lists the target as `code`, `module`, `course-package`, or `full-course`)
2. Cite evidence (file:line, command output, URL fetched on which date, diff hunk) for every finding
3. Classify severity per the rubric in CRITERIA.md
4. Score confidence 0-100. Findings below 80 go to the "Unverified claims" section, not "Findings"
5. If you cannot verify a claim, mark it UNVERIFIED — do not guess

For URL verification: fetch every external link in the target. A link is valid only if (a) it resolves, (b) the page is the resource it claims to be, and (c) the cited content is actually present on the page. Record each fetched URL in the Evidence ledger with the access date.

For technical accuracy: cross-reference against official documentation for the exact version stated in the blueprint. A method that exists in version N+1 but not in version N is a finding. Quote the doc page in the evidence — "I read the docs carefully" is not evidence; the quoted page section is.

For code samples (`code`, `module`, `course-package`, `full-course` targets): you MUST actually run the samples via Bash and record exit codes in the Evidence ledger. Reading code "carefully against docs" instead of running it is the exact AI failure mode this skill exists to catch — do not substitute reading for execution. If Bash is unavailable to you, abort and report this as a blocker for the parent agent.

For quiz/assessment review: independently answer every question BEFORE consulting the provided answer key. Record each derived answer in the Evidence ledger. A mismatch with the key is a Critical finding (either the question is ambiguous or the key is wrong).

## Step 5: Devil's-advocate self-pass

Before finalizing:
- For every finding, challenge it: "is this a real problem, or am I pattern-matching on something that looks bad?" Mark KEEP / WEAKEN (lower severity by 1) / DROP with a one-line reason
- Re-scan the target once more for things you might have missed (gap pass) — even if you found zero issues. Pay particular attention to: forward references to unintroduced concepts, terminology that drifts from the glossary, time estimates that obviously do not match content depth

## Step 6: Submit structured output

Return ONLY the format defined in OUTPUT_FORMAT.md. No conversational preamble. No "I hope this helps". The output is the deliverable.

Pass the prompt to the Task tool. Wait for completion.

Step 5: Present findings verbatim alongside the artifact

Pass the subagent's structured output through to the user without softening. Specifically:

• Do NOT summarize away Critical findings
• Do NOT add "I think this is mostly fine" framing
• Do NOT silently drop findings you disagree with

Mandatory-gate behaviour (course-prep integration): When this skill is invoked as the gate before a Milestone approval, present both the artifact (or a pointer to it) and the review verbatim. Then:

1. If the verdict is BLOCK or REQUEST_CHANGES: fix Critical findings before re-presenting. Do not ask the user to approve until the verdict reaches APPROVE_WITH_CHANGES or APPROVE.
2. If the verdict is APPROVE_WITH_CHANGES: present to the user with the warnings clearly displayed; let the user decide whether to fix-then-approve or approve-then-fix.
3. If the verdict is APPROVE: still surface the gap-pass notes — even a clean review usually finds non-blocking improvements.

If the user disputes a finding, do not auto-concede. Either:

1. Re-launch the subagent with the dispute as new evidence and ask for a re-review of that finding only, OR
2. Present both views and let the user decide

Highlight Critical findings prominently. Offer next steps: fix critical findings, dispute with evidence, or accept.

Optional Modes

Modes are orthogonal to target type. Pass the chosen mode in the brief.

Mode ∩ matrix rule: The final dimension set is the intersection of (the mode's listed dimensions) and (the target/dimension matrix in CRITERIA.md). A mode that names a dimension irrelevant to the chosen target simply skips it. Modes can list more than the target ends up applying — listing is a whitelist within the matrix, not an override.

Mode	Whitelisted dimensions (intersected with the matrix for the actual target)
comprehensive (default)	All applicable dimensions
accuracy-only	Factual & Technical Accuracy + URLs & References + AI-Specific Risks + Validation Markers Resolved
pedagogy-only	Pedagogical Soundness + Audience Fit + Time & Pacing Realism + Cross-Module Consistency
code-only	Code Sample Correctness + URLs & References + AI-Specific Risks (use for the code target or pre-release smoke)
quiz-only	Assessment Quality + Pedagogical Soundness + AI-Specific Risks (forces independent answer-key verification)
provenance-only	Provenance & Licensing + URLs & References + AI-Specific Risks (use after importing raw-input)
fidelity-only	Compilation Fidelity + Source Formatting & Obsidian (use for compiled-output)
quick	Same dimensions as comprehensive, but skip the gap pass and only surface findings with confidence ≥ 90

Do NOT use quick at the milestone gate. quick is for fast pre-commit sanity, not for the deliverable that goes to the user. It suppresses borderline findings that the gate should surface.

Example: "review the quiz for module 03 in quiz-only mode"

Anti-Patterns

• Reviewing in the same context as the authoring — defeats the entire point. Always use the Task tool, never review inline.
• Editorial framing in the brief — leading the subagent toward your preferred verdict.
• Skipping evidence — accepting findings or rebuttals without file:line citations or fetched URLs.
• Treating the verdict as advisory — if Critical findings exist with high confidence, the milestone is not done.
• Reviewing trivial edits — wastes tokens and trains the user to ignore reviews.
• Reviewing without identifying the target — the same checklist applied to a quiz and a blueprint produces nonsense; identify first.
• Letting the subagent skip URL/API verification — these are the highest-yield checks in educational content; insist on them.
• Reading every file in a course-package or full-course audit upfront — the subagent has Grep/Read; let it pull what it needs.
• Auto-fixing findings without telling the user — when the parent agent acts on review findings, every change must be visible to the user.

Integration with course-prep

This skill is designed as the mandatory review gate for course-prep. The mapping:

course-prep Milestone	course-review target(s) to invoke before user-approval gate
1 — Blueprint	blueprint (also raw-input for the research notes)
2 — Module outlines	module-outline per module
3 — Source content	module per module (covers lecture + code + tasks + quiz)
4 — Cross-module review	course-package
5 — Output compilation	compiled-output per deliverable format

When the parent agent is following course-prep, it MUST run the matching course-review target before declaring the milestone ready for user review. See [course-prep/SKILL.md "Review gate" sections] for the exact triggers.

See Also

• CRITERIA.md — full review criteria across all dimensions, target applicability matrix, severity rubric, confidence scoring, devil's-advocate pass
• OUTPUT_FORMAT.md — required structured output schema
• koldovsky/skill-review-task — the generic code/PR/spec review skill this is adapted from