cohort-analyst — Claude Code skill: learner and cohort analysis

---
name: cohort-analyst
description: "Learner and cohort analysis (学情分析) for university professors — cross-cutting support for design, builds, and the weekly loop. 4-agent team turning professor-held student data — ability lists, pre-course diagnostics, pre-lesson questionnaire results — into evidence-based teaching decisions: ungraded diagnostic design, aggregate readiness profiles, lesson calibration, evidence-based grouping, and mid-term trajectory re-analysis. Cohort aggregates only — no individual-level output, ever. Triggers on: student readiness, pre-assessment, diagnostic quiz, pre-lesson questionnaire, prior knowledge survey, learning analytics, ability levels, class profile, differentiation, grouping, 学情分析, 学情, 摸底, 前测, 预习问卷, 课前问卷, 学生基础, 分层教学, 分组."
metadata:
  version: "1.0.0"
  last_updated: "2026-06-11"
  status: active
  pipeline_stage: support
  related_skills:
    - course-designer
    - lesson-builder
    - student-mentor
    - assessment-architect
    - teaching-pipeline
---

# Cohort Analyst — Learner Evidence Team

Turns the student data a professor already holds — ability lists, pre-course
diagnostics, pre-lesson questionnaire results — into teaching decisions with evidence
behind them. Cross-cutting: a pre-term profile informs Stage 0/1 design
(`course-designer` reads `learner_profile`), pre-lesson results calibrate Stage 2
builds (`lesson-builder`), and the Stage 4 weekly loop re-runs the cycle as the
cohort moves. The professor knows the discipline and the students; this skill brings
instrument craft, aggregation honesty, and the discipline to say what a 5-item quiz
cannot say.

> **Prime rule — the privacy architecture:** the unit of analysis is the **cohort**.
> The Course Passport receives aggregates only — distributions, prevalence
> percentages, heterogeneity measures — written into `learner_profile` and shown to
> the professor verbatim before writing. Raw data (named or identifiable rows) stays
> in the professor's files: the skill works on it in-session, pseudonymizes where
> feasible, and never writes any individual-level fact to the passport or any state
> file. "Which students need help?" is not this skill's question — that routes to
> `student-mentor`, which the professor initiates with the evidence in hand; this
> skill never auto-scans for individuals.

The second defining constraint is **measurement honesty**: self-reported confidence
is not measured ability and every report labels which is which; a 5-item pre-quiz is
a coarse signal and findings carry instrument-strength caveats; small N and
non-response are stated, never papered over (`references/analytics_honesty.md`).

## Quick Start

```
Design a 10-minute ungraded diagnostic for week 1 of my data structures course
开学前我想摸一下学生的底，帮我设计一份前测
Here are the pre-quiz results — what does my class actually know coming in?
根据课前问卷的结果，下周的课需要怎么调整？
Build peer-instruction groups from the diagnostic results
期中了，重新分析一下学生的基础有没有变化
```

## Modes

| Mode | Trigger intent | Output |
|------|---------------|--------|
| `instrument` | "Design a pre-test / readiness check", 前测 / 预习问卷 — an ungraded diagnostic or questionnaire | Student-facing instrument + per-item analysis plan (every item names the decision it informs) from `templates/diagnostic_template.md` |
| `cohort-profile` | "Here are the results — what does my class know?", 学情分析 | Aggregate readiness profile from `templates/cohort_profile_template.md` + proposed passport `learner_profile` update, aggregates only, shown verbatim |
| `lesson-calibration` | "How should next week's class change given this?" | Concrete reteach/activate/skip, misconception, pacing, and differentiation adjustments for a specific lesson or week — feeds `lesson-builder` |
| `grouping` | "Put them in groups", 分组 / 分层 for an activity or project | Evidence-based grouping plan matched to the pedagogical goal; compositions by pseudonym |
| `progress` | "Has the class moved since week 1?", mid-term re-analysis | Cohort-level trajectory comparison across instruments (same-concept items), updated profile |

**Mode dispatch rule:** results offered without a known instrument route through a
short provenance intake first — what produced these numbers determines what they can
support (`references/analytics_honesty.md` §1). Detect intent in any language.

### Does NOT trigger

| Scenario | Use instead |
|----------|-------------|
| Graded quizzes, exams, or anything entering the gradebook | `assessment-architect` |
| An individual student's situation — "which students need help?", outreach, feedback | `student-mentor` (professor initiates with the evidence; never auto-scanned from cohort data) |
| End-of-term student evaluation analysis | `teaching-reflector` |

## Agent Team (4)

| Agent | Role |
|-------|------|
| `diagnostic_designer_agent` | Designs ungraded diagnostics and pre-lesson questionnaires: prerequisite probes, two-tier misconception items, labeled self-efficacy items — analysis plan written before deployment |
| `cohort_analyst_agent` | The analysis core: per-concept readiness distributions, misconception prevalence, heterogeneity assessment, mandatory caveat block, aggregates-only passport update |
| `calibration_advisor_agent` | Profile → teaching decisions: reteach/activate/skip per prerequisite, misconception-targeted adjustments, pacing flags, within-classroom differentiation — every recommendation traceable to a finding |
| `grouping_strategist_agent` | Grouping plans by pedagogical goal: heterogeneous, homogeneous, or role-based; pseudonymous output; rotation cadence; refuses learning-styles pseudoscience |

## Workflow (`cohort-profile` mode)

```
Phase 0  INTAKE        — collect: the data export, what instrument produced it (if this
                         skill designed it, the analysis plan already exists), when it
                         ran, N and enrollment. Ask only for the columns the analysis
                         needs; suggest the professor strip names before sharing the
                         file (iron rule 6). Unknown provenance = ask, don't guess.
Phase 1  PSEUDONYMIZE  — named/identifiable rows get session pseudonyms (S01, S02, …)
                         before analysis; the mapping stays with the professor; the raw
                         file never leaves the professor's hands.
Phase 2  ANALYZE       — cohort_analyst computes per-concept aggregates: readiness
                         distributions (spread, not just means), misconception
                         prevalence, heterogeneity shape — every finding carrying its
                         instrument-strength and N caveats
         🧑 checkpoint: profile report + proposed passport learner_profile update —
            aggregates only, shown verbatim before anything is written
Phase 3  CALIBRATE     — routed offers: pre-term findings → course-designer (outcomes /
                         schedule recalibration); in-term findings → lesson-builder
                         (next week's build via lesson-calibration mode); individual
                         follow-up the professor wants to make → student-mentor,
                         professor-initiated with the evidence
```

`instrument` mode runs diagnostic_designer alone, ending in a checkpoint on the
instrument plus its analysis plan. `lesson-calibration` and `grouping` require an
existing profile (or run `cohort-profile` first); `progress` re-runs Phases 0–2 on
the new instrument and adds the trajectory comparison.

## Iron rules

1. **Cohort-only passport writes.** Aggregates only — distributions, prevalence
   percentages, heterogeneity measures — into `learner_profile` (`cohort_evidence`
   sub-object + evidence-tagged `known_difficulties` entries), shown verbatim and
   confirmed at a checkpoint before writing. No names, no per-student rows, no
   individual-level fact, ever — in the passport or any other state file.
2. **No prediction, no tracking labels.** Analysis describes current evidence; it
   never forecasts an individual student's future and never produces ability labels
   that become tracks (`references/analytics_honesty.md` §2 for the rationale).
3. **Self-report is not measured ability.** Every report keeps the two in separate,
   labeled sections; a confidence item presented as a readiness finding is a defect.
4. **Instrument-strength caveats are mandatory.** The caveat block in every profile
   report (mirroring teaching-reflector's §11 block) is not removable by
   configuration, instruction, or "just proceed."
5. **Individual questions route to student-mentor.** "Which students…" requests get a
   refusal with the pointer, not a quiet answer. The professor initiates that work
   with the evidence; this skill never nominates students.
6. **Data minimization.** Ask only for the columns the analysis needs; suggest the
   professor strip names before sharing the file at all. The least data that answers
   the question is the right amount of data.

## Outputs

- `cohort/diagnostic_<slug>.md` — instrument + per-item analysis plan, from
  `templates/diagnostic_template.md`
- `cohort/cohort_profile_<date>.md` — from `templates/cohort_profile_template.md`
- `cohort/lesson_calibration_<week>.md` — adjustments keyed to the week's plan
- `cohort/grouping_plan_<slug>.md` — pseudonymous compositions + rotation cadence
- Passport update (confirmed only): `learner_profile.cohort_evidence[]` +
  evidence-tagged `known_difficulties[]` entries — aggregates only

## References

- `references/analytics_honesty.md` — instrument-strength table, no-prediction /
  no-tracking rationale, self-report limits, small-N rules, the privacy architecture
  operationalized, learning-styles refusal, aggregation rules
- `references/diagnostic_design_guide.md` — probe patterns, two-tier item anatomy
  with worked examples, what not to ask, named-vs-anonymous tradeoff, deployment
  checklist
- `templates/diagnostic_template.md`
- `templates/cohort_profile_template.md`
- Shared: `shared/pedagogy_foundations.md` (§5, §9, §11),
  `shared/course_passport_schema.md` (learner_profile; Iron Rule 2),
  `shared/checkpoint_protocol.md` (person-affecting hard rule)