---
name: needs-analysis
description: "Structured intake before course design — captures context, task analysis, learner analysis, and planning flags."
---

# Needs Analysis Skill

> **HPI/ID standard** — this skill applies the HPI/ID practitioner standard automatically (CLAUDE.md §Operating Standard: HPI/ID Practitioner). Ground decisions in `standards/instructional-design.md` — design sections 1–12 and the HPI diagnostic layer in Section 13. Name the framework behind every judgment; every design recommendation carries gap → data → principle → mechanism.

> **Assurance by design.** This skill applies `standards/assessment-assurance-design.md` automatically (CLAUDE.md §Operating Standard: Assurance by Design). The task-analysis and planning-flags output should set up the future assessment mix to secure at least one anchor for the grade and plan task-level AI declaration.


> **Plugin**: ASU Canvas Course Builder
> **Trigger**: `/needs-analysis`
> **Referenced by**: course-build, syllabus-generator

## Purpose

Run a structured pre-design intake before course planning or content generation. This skill captures:

1. **Context** — why the request exists, delivery realities, professional setting, timing notes
2. **Task analysis** — what learners actually need to do, what they need first, and which tools/systems matter; Bloom-level demand for each task cluster
3. **Learner analysis** — what learners already know, what motivates them, access constraints, and audience notes
4. **HPI signals** — lightweight Gilbert BEM scan for environment-side risks, Mager-Pipe skill/will branch when a concrete performance gap exists, Bloom-aligned task demand tags

The HPI layer captures advisory signals useful for course design and downstream audits. This is a **higher-ed intake, not a full HPI audit** — every step stays advisory and the workflow always continues.

Write the intake to `courses/{courseId}/course-config.json` under a `needs_analysis` block so later skills can reuse it instead of re-asking foundational questions.

---

## Output Schema

Write this exact structure to `courses/{courseId}/course-config.json`:

```python
{
  'needs_analysis': {
    'context': {
      'request_origin': '',
      'delivery_constraints': [],
      'professional_context': '',
      'timeline_notes': ''
    },
    'task_analysis': {
      'core_tasks': [],
      'core_task_bloom': {},
      'prerequisites': [],
      'tools_and_systems': []
    },
    'learner_analysis': {
      'prior_knowledge': '',
      'motivation': [],
      'access_constraints': [],
      'audience_notes': ''
    },
    'planning_flags': {
      'training_fit': 'clear|mixed|unclear',
      'risk_notes': [],
      'risk_notes_bem': [],
      'mager_pipe_branch': 'skill_knowledge|will_environment|mixed|unclear|not_applicable'
    }
  }
}
```

**New field rules:**

- `task_analysis.core_tasks` — UNCHANGED. List of concrete learner-action strings.
- `task_analysis.core_task_bloom` — NEW. Map from core-task string (or task-cluster label) to one Bloom level: `Remember`, `Understand`, `Apply`, `Analyze`, `Evaluate`, `Create`. Keys must match entries in `core_tasks`. Default `{}`. Mapping guide: knowledge application → usually `Apply`; procedure/workflow → usually `Apply`; analysis and judgment → `Analyze` or `Evaluate` (ask which); product/design/drafting → `Create`.
- `planning_flags.risk_notes` — UNCHANGED. List of plain-sentence concern strings.
- `planning_flags.risk_notes_bem` — NEW. List of objects, each exactly `{"bem_cell": "...", "note": "..."}`. `bem_cell` must be one of the 6 Gilbert BEM cells: `Information`, `Instruments`, `Incentives`, `Knowledge`, `Capacity`, `Motives`. Default `[]`. Rule: every BEM-tagged entry must also have a plain sentence in `risk_notes` for legacy-consumer compatibility.
- `mager_pipe_branch` — NEW. One of exactly 5 values: `skill_knowledge` (couldn't perform even with high stakes — training/practice may fit), `will_environment` (could perform if stakes/supports were right — environment dominates), `mixed`, `unclear`, `not_applicable` (no concrete performance gap exists). Default `unclear`.

If `course-config.json` already contains a `needs_analysis` block, load it first, summarize the current values, and ask whether to refine or replace them before writing updates.

---

## Intake Rules

- Use `AskUserQuestion` for every branching decision or constrained choice.
- Keep the conversation focused on course design inputs, not plugin mechanics.
- Do not ask about VARK, "learning styles," "auditory learners," or "visual learners" as learner categories for design decisions. Those constructs are not evidence-backed for instructional planning and should not be used in this intake.
- If the user volunteers that language, redirect to evidence-based questions such as prior knowledge, motivation, task demands, accessibility needs, or learning environment constraints.
- The training-justification gate is **advisory only** in higher-ed contexts. If the request may not be best solved by training, flag that in `planning_flags.training_fit` and `planning_flags.risk_notes`, but continue the intake and do not block the workflow.
- **Gilbert BEM advisory scan**: use the 6 BEM cells as a lightweight planning-risk check, not a full audit. Scan environment cells first (Information, Instruments, Incentives) — per `docs/memory/MEMORY.md`, ~80% of performance problems are environment-side. Then scan individual cells (Knowledge, Capacity, Motives). Tag each concern in `risk_notes_bem` with the relevant cell and mirror a plain sentence into `risk_notes`.
- **Mager-Pipe branch**: apply only when a concrete performance gap exists. The stakes-based question ("if learners had to perform this today and the stakes were high, could they do it?") distinguishes skill/knowledge deficits from will/environment issues. Do not force the branch on general course-design requests.
- **Bloom-level tags**: use Bloom's Revised Taxonomy to describe task demand, not to over-engineer objectives at intake. Tag each task cluster in `core_task_bloom` with the dominant cognitive level the task actually requires.

---

## Recommended Flow

### Step 0: Load Existing Context

1. Read `courses/{courseId}/course-config.json`.
2. If `needs_analysis` exists and contains non-empty values:
   - Show a short summary of what is already captured.
   - Present an `AskUserQuestion`:

| Label | Description |
|---|---|
| **Refine existing analysis** | Keep what is there and fill gaps or update weak spots |
| **Replace it** | Start over and overwrite the existing needs analysis |
| **Keep as-is** | Reuse the current analysis and exit |

3. If the user chooses **Keep as-is**, stop after confirming the analysis is available for downstream skills.

### Step 1: Context Intake

Start with the broad course-design context. Capture:
- `context.request_origin`
- `context.delivery_constraints`
- `context.professional_context`
- `context.timeline_notes`

Use a short conversational sequence:

1. Ask who requested or initiated the course or redesign, and what prompted it.
2. Ask about delivery realities: modality, calendar, accreditation, staffing, technology, scheduling, enrollment scale, or any non-negotiable course constraints.
3. Ask what professional, disciplinary, or program context should shape the course.
4. Ask whether there are timeline pressures, launch dates, review deadlines, or revision windows.

When choices help, present an `AskUserQuestion`:

**Question**: "Which best describes the main origin of this request?"

| Label | Description |
|---|---|
| **Program or department need** | The course is being created or revised to meet a curricular requirement |
| **Instructor-led redesign** | A faculty member wants to improve or update the course |
| **Compliance or review pressure** | Accreditation, quality review, or policy requirements are driving the work |
| **Mixed reasons** | More than one force is shaping the request |

Normalize delivery constraints into a list. Examples:
- `["fully online asynchronous", "7.5-week session", "large enrollment"]`
- `["hybrid", "clinical placement coordination", "required third-party platform"]`

### Step 2: Task Analysis Intake

Move from course context to what successful learners must actually do. Capture:
- `task_analysis.core_tasks`
- `task_analysis.core_task_bloom`
- `task_analysis.prerequisites`
- `task_analysis.tools_and_systems`

Ask for:
1. The most important real tasks, performances, or decisions learners must be able to carry out by the end of the course.
2. Entry requirements: prior coursework, prior skills, assumed concepts, program standing, certifications, or technical readiness.
3. Tools, software, equipment, clinical systems, lab environments, or workflow platforms learners will use.

Present an `AskUserQuestion` to build the Bloom-aligned performance profile:

**Question**: "What is the dominant kind of performance this course prepares learners for?"

| Label | Description | Likely Bloom level |
|---|---|---|
| **Knowledge application** | Learners mainly apply concepts to cases, problems, or examples | `Apply` |
| **Procedure or workflow execution** | Learners perform a process, protocol, or sequence of actions | `Apply` |
| **Analysis and judgment** | Learners interpret evidence, diagnose issues, or make decisions | `Analyze` or `Evaluate` |
| **Product, design, or drafting** | Learners create an original artifact, document, or solution | `Create` |
| **Mixed performance profile** | The course combines several task types | (tag per cluster) |

After collecting `core_tasks`, tag each task or cluster with a Bloom level in `core_task_bloom`. Use this mapping as default guidance — override when the task clearly belongs at a different level:
- Knowledge application → usually `Apply`
- Procedure/workflow → usually `Apply`
- Interpretation or diagnosis → `Analyze` or `Evaluate` (ask which if unclear)
- Design, drafting, or original product → `Create`
- Foundational recall only → `Remember` or `Understand`

Record `core_tasks` as concrete learner actions, not content topics. Good examples:
- "Interpret arterial blood gas results in patient cases" → `Analyze`
- "Use spreadsheet formulas to analyze business scenarios" → `Apply`
- "Draft a policy memo supported by scholarly evidence" → `Create`

### Step 2.5: Assurance-by-Design Advisory

Apply `standards/assessment-assurance-design.md` to the emerging assessment strategy: note in `planning_flags.risk_notes` whether the proposed assessment mix secures at least one anchor for the grade (Two-Lane) and plans task-level AI declaration. This is the upstream, highest-leverage insertion point; downstream skills build individual instruments, but needs-analysis sets the mix before any instrument exists.

### Step 3: Learner Analysis Intake

Finish with learner characteristics that affect course design. Capture:
- `learner_analysis.prior_knowledge`
- `learner_analysis.motivation`
- `learner_analysis.access_constraints`
- `learner_analysis.audience_notes`

Ask about:
1. What learners are likely to know before they enter the course.
2. What tends to motivate them: degree progress, licensure, workplace application, personal relevance, confidence building, or other drivers. Normalize `motivation` as short phrases, one per driver. Example: `["professional license renewal", "career change", "degree requirement"]`.
3. Access constraints: bandwidth, devices, scheduling, disability/accessibility needs, time zones, caregiving, fieldwork, or platform access. Normalize `access_constraints` as specific constraints, not generic labels. Example: `["unreliable broadband", "mobile-only access", "limited after-hours screen time"]`.
4. Any audience notes that would matter for tone, examples, scaffolding, or support.

Present an `AskUserQuestion` when needed:

**Question**: "How would you describe the learners' starting point?"

| Label | Description |
|---|---|
| **Mostly new to the domain** | Learners need more scaffolding and explicit foundations |
| **Mixed entry knowledge** | Some learners are prepared and some are not |
| **Mostly experienced** | Learners can move quickly into applied or advanced work |

Do not ask whether learners are "visual," "auditory," or any other so-called learning-style type. If the user asks for that, respond plainly: course design here uses prior knowledge, motivation, task demands, and accessibility needs instead because learning-style categories are not evidence-backed.

### Step 4: HPI Advisory Gate

Before saving, run a lightweight Human Performance Improvement pass. This is advisory only — the workflow always continues regardless of findings.

#### 4.1 Gap check

Present an `AskUserQuestion`:

**Question**: "Is this course responding to a specific performance gap, or mainly a new or revised course-design need?"

| Label | Description |
|---|---|
| **Specific performance gap** | Learners are failing to perform something they need to be able to do |
| **General course design need** | New course, curriculum update, quality improvement — no specific failure identified |
| **Unclear** | Not sure, or the request mixes both |

- If **General course design need**: set `mager_pipe_branch = "not_applicable"`. Still run the BEM scan (step 4.3) for planning risks. Set `training_fit` based on instructional usefulness.
- If **Specific performance gap** or **Unclear**: proceed to step 4.2.

#### 4.2 Mager-Pipe branch (only when a performance gap exists)

Present an `AskUserQuestion` using a stakes-based probe:

**Question**: "If learners had to perform this today and the stakes were high — their job, license, or grade depended on it — could they do it?"

| Label | Meaning | `mager_pipe_branch` value |
|---|---|---|
| **Yes** — they could perform under high stakes | Issue is motivation, confidence, tools, or environment — not skill | `will_environment` |
| **No** — they genuinely couldn't perform even if motivated | Knowledge, skill, or practice deficit present | `skill_knowledge` |
| **Mixed or unsure** | Both factors may be at play | `mixed` or `unclear` |

Save the branch to `planning_flags.mager_pipe_branch`.

#### 4.3 Lightweight BEM walk

Walk all 6 Gilbert BEM cells in order. For each cell, run a one-line probe. Any concern → add a plain sentence to `risk_notes` AND an object to `risk_notes_bem` with `{"bem_cell": "...", "note": "..."}`.

| BEM cell | One-line probe |
|---|---|
| **Information** | Do learners have clear expectations, worked examples, performance criteria, and timely feedback? |
| **Instruments** | Do learners have the tools, time, systems, templates, access, and staffing they need to perform? |
| **Incentives** | Are rewards, consequences, and accountability actually aligned with the desired performance? |
| **Knowledge** | Is there a genuine lack of knowledge, skill, models, or practice opportunities? |
| **Capacity** | Is workload, cognitive load, prerequisite demand, bandwidth, and accessibility realistic for this learner population? |
| **Motives** | Is learner confidence, relevance, buy-in, and sense of belonging credible given the course design? |

Scan environment cells (Information, Instruments, Incentives) first — these are the most common root causes. Then scan individual cells (Knowledge, Capacity, Motives).

Advisory framing examples:
- "Training can address the Knowledge cell, but the Instruments cell (tool access) may matter just as much."
- "The Incentives cell is unclear — accountability for applying this may need to be built into the assessment design."

#### 4.4 Set training_fit

| `training_fit` value | Meaning |
|---|---|
| `clear` | Knowledge, skill, judgment, or guided practice is the dominant gap — course design can address it |
| `mixed` | Instructional needs are real, but BEM environment cells (Information, Instruments, Incentives) also show concerns |
| `unclear` | The problem is poorly defined or primarily non-instructional |

Add concise notes to `planning_flags.risk_notes` for any `mixed` or `unclear` findings. Normalize `risk_notes` as flagged concerns written as sentences. Example: `["Instruments cell: tool access uncertain for remote learners", "SME availability uncertain past Module 3"]`.

### Step 5: Confirm and Write

Summarize the captured analysis in three sections:
- Context
- Task analysis
- Learner analysis

Then present an `AskUserQuestion`:

| Label | Description |
|---|---|
| **Save this analysis** | Write the needs analysis to `course-config.json` |
| **Revise before saving** | Update one or more sections first |

On save:
1. Preserve all unrelated keys already present in `course-config.json`.
2. Write or replace only the `needs_analysis` block.
3. Confirm that downstream skills can now reuse the saved analysis.

---

## Good Defaults and Guardrails

- Prefer short, evidence-based prompts over broad brainstorming.
- Record unknowns as concise notes in `planning_flags.risk_notes` instead of forcing guesses.
- If the user only has partial information, save the partial analysis and mark risks clearly.
- In higher-ed settings, avoid hard "should this be training at all?" gatekeeping. Advisory notes are enough.
- Downstream reuse matters: phrase entries so other skills can directly consume them.

---

## Scope Fit / Session Triage

Before confirming the analysis (Step 5), check whether the proposed topic/module count fits the target session. This is especially relevant for in-person → online conversions (e.g., 15-week → 7.5-week A/B session).

**How to run it:**

```bash
python scripts/scope_triage.py --course-id {courseId} --session A [--start YYYY-MM-DD]
```

Or supply a topic count directly if the config is not yet saved:

```bash
python scripts/scope_triage.py --course-id {courseId} --session A --topic-count N --start YYYY-MM-DD
```

**What it does:**

- Computes session capacity: `floor((session_weeks - 0.5) * topics_per_week)` (default 1 topic/week).
- Flags over-scope when `topic_count > capacity` and shows how many topics exceed the limit.
- Surfaces cut **candidates** — limited to topics explicitly marked `optional: true` in `course-config.json`. It never auto-selects or ranks substantive topics for removal.
- Prints build-complete deadlines (target = start − 28 days, floor = start − 14 days) and runway status when `--start` is provided.

**HARD BOUNDARY:** The cut decision always belongs to the instructor (and relevant program faculty). This tool flags and proposes; it never decides. Every over-scope result carries a note stating this explicitly. If scope reduction is needed, surface the finding to the faculty member and document their decision in `courses/{courseId}/course-memory.md`.

Use `--json` for machine-readable output, `--emit-backlog` to add an over-scope finding to the course backlog. Calendar data lives in `standards/asu-academic-calendar.json` — resync annually.

---

## Downstream Reuse

After save, tell the user the analysis is available for:
- `/syllabus-generator` to preload prior knowledge, constraints, core tasks, and prerequisites
- `/course-build` as an advisory design input before building, or merged with a planning document's structured detail via its Course Plan Import Path
