Run Research Topic

---
description: Research a topic and produce a cell-by-cell plan file at plans/topic_N_slug.md that /build-topic-notebook can consume directly
---

Research and plan topic: $ARGUMENTS

## GUARD: Read Course Manifest First

Before doing anything else, check for `plans/CORE_TECHNOLOGIES_AND_DECISIONS.md`:

```bash
ls plans/CORE_TECHNOLOGIES_AND_DECISIONS.md 2>/dev/null

If the file does NOT exist, stop immediately and say:

plans/CORE_TECHNOLOGIES_AND_DECISIONS.md not found. Run /init-course first to record the course decisions. Every command requires this file before proceeding.

If it exists, read the full file and keep its contents in mind throughout this command.

---

This command is the natural precursor to /build-topic-notebook. Its only job is to produce a plan file at plans/topic_N_slug.md so that /build-topic-notebook N can build notebooks cell by cell from it.

This command does NOT create any notebooks. It produces markdown only.

Web research is MANDATORY. Use the /research skill for all web searches in this command.

FAILURE DEFINITION

This command has exactly two outcomes: COMPLETE SUCCESS or COMPLETE FAILURE. There is no partial credit.

COMPLETE SUCCESS = all of the following are true:

• All 5 research cycles completed and visible in chat
• Each cycle invoked the /research skill (Skill tool, skill="research")
• PRE-WRITE SELF-CHECK printed in chat with all YES answers
• Plan file written to plans/topic_<N>_<slug>.md with all required sections
• plans/TOPICS.md updated

COMPLETE FAILURE = any of the following happened:

• Fewer than 5 research cycles completed
• Any cycle skipped the /research skill invocation
• PRE-WRITE SELF-CHECK not printed, or any field was NO when Write was called
• Plan file not written (command ended without producing the file)
• Plan file written with stub/placeholder content instead of real cells

If this command ends in COMPLETE FAILURE, the correct response is: report what failed, and restart from the beginning. Do not patch a partial result.

---

Command Arguments

/run-research-topic <topic_number>

Example: /run-research-topic 4

After you invoke this command, I will ASK you three questions before doing any work:

1. Main focuses / things to consider - what to emphasize, go lighter on, or student confusion from prior topics to address.
2. Confirmation of prior-topic continuity - I will state which variables, patterns, and API objects carry over from prior topics and ask you to confirm.
3. Any Barclays-specific context - product names, scenarios, or compliance details to highlight.

DO NOT proceed to research until I have all three answers.

---

Output Contract (NON-NEGOTIABLE)

1. One file only: plans/topic_<N>_<topic_slug>.md (always under plans/, never anywhere else).
2. Structure (every section required):
   • # Topic N: <Title> - Cell-by-Cell Plan
   • ## Context
   • ## Deliverables
   • ## Session Timing (~60-90 min) table
   • # MAIN NOTEBOOK - Cell-by-Cell Content (Target: ~20-25 cells)
   • Each cell: ## Cell N - Markdown/Code: Description with full content in fenced block
   • # VERIFICATION CHECKLIST
   • # RESEARCH VALIDATED (Month Year)
3. No .ipynb files. No Write calls except to plans/topic_<N>_<topic_slug>.md.
4. Plan must be directly executable by /build-topic-notebook - every cell has enough detail the builder does not need to invent content.

Writing the Plan File in Batches

If the plan file will exceed ~150 lines, write it in sections:

1. First Write call: header through ## Session Timing table
2. Subsequent Write calls: append cell-by-cell content in chunks of ~50 lines each (use Edit to append, not overwrite)
3. Final Write/Edit call: append VERIFICATION CHECKLIST and RESEARCH VALIDATED block

This prevents large single Write calls that can get truncated.

---

Pre-Work: MANDATORY Reading

Before any research, read:

1. CLAUDE.md - teaching philosophy, notebook structure, tone, environment
2. plans/CORE_TECHNOLOGIES_AND_DECISIONS.md - pinned versions, estimator rules, IAM setup, canonical patterns
3. plans/SAGEMAKER_LESSONS_LEARNED.md - 14 hard-won pitfalls; every SageMaker cell must pass these before being written into the plan
4. plans/DEFINITION_OF_DONE.md - checklist the plan must satisfy before being handed to /build-topic-notebook
5. initial_docs/outline.pdf - extract this topic's section (title, concepts, labs, objectives)
6. .claude/commands/build-topic-notebook.md - the consumer of your plan
7. If topic N > 1: open exercises/topic_<N-1>_*/topic_<N-1>_*.ipynb - list exact variable names, API patterns, and helpers students already have

---

MANDATORY CYCLE TRACKER

At the start of research, post this tracker in chat and update it after completing each cycle. You MUST NOT write the plan file until all 5 boxes are checked:

CYCLE TRACKER
[_] Cycle 1 - Outline Alignment and Prior-Topic Continuity       /research invoked: NO
[_] Cycle 2 - Environment and Dependencies                        /research invoked: NO
[_] Cycle 3 - Pedagogical Structure                               /research invoked: NO
[_] Cycle 4 - Lab Difficulty and Stretch Labs                     /research invoked: NO
[_] Cycle 5 - Final Integration, Timing, Take-Homes              /research invoked: NO

After each cycle, update BOTH the [_] checkbox AND change NO to YES on the /research invoked field. A cycle is NOT complete if /research invoked still says NO. There are no exceptions.

HARD STOP before writing any file: Check the tracker.

• If any cycle shows [_] (not checked): STOP. Complete that cycle fully before proceeding.
• If any cycle shows /research invoked: NO: STOP. That cycle must be redone with a real /research skill call.
• Only when all 5 show [x] AND all 5 show /research invoked: YES may you write the plan file.
• Writing the plan with any unchecked