Remediation Playbook: My source of truth

Not for students until the relevant workshop has happened.

Every deliberate pain point in the OrbitTasks codebase, mapped to the workshop that walks through the fix together with students (not as solo homework). Each row tells me where the issue lives, which workshop addresses it, and what the live-demo step is.

The key pedagogical move: students don't fix any of these on their own. I demonstrate the fix during the workshop, students follow along in their own clones, and they leave with the same green state.

---

Pain points and their workshops

#	Pain point	File	Found in	Fixed in	Live demo
1	15-second billing rollup test (real HTTP)	apps/api/tests/reports.test.ts	W1 baseline, W2 profiling	W5 AI-assisted refactor	W5 live-demo, step 4
2	Flaky Promise.race timing test	apps/api/tests/reports.test.ts	W1 (when it fails)	W2 root-cause analysis	W2 live-demo, step 3
3	maxWorkers: 1 in Jest config	apps/api/jest.config.js	W2 profiling	W3 CI/CD optimization	W3 live-demo, step 4
4	collectCoverage: true always on	apps/api/jest.config.js	W2 profiling	W3 CI/CD optimization	W3 live-demo, step 3
5	incremental: false in tsconfig	apps/api/tsconfig.json	W2 profiling	W3 CI/CD optimization	W3 live-demo, step 2
6	No npm cache in CI workflow	.github/workflows/ci.yml	W1, W3	W3 CI/CD optimization	W3 live-demo, step 1
7	Sequential per-file deploy script	scripts/deploy.sh	W2 profiling	W3 CI/CD optimization	W3 live-demo, step 8
8	Misleading README ("npm install && npm start")	README.md	W4 audit	W4 DevEx	W4 live-demo, step 2
9	Broken setup.sh (typo: logss)	scripts/setup.sh	W4 audit	W4 DevEx	W4 live-demo, step 1
10	Missing JWT_SECRET in .env.example	.env.example	W4 audit	W4 DevEx	W4 live-demo, step 3
11	Out-of-date architecture doc (mentions Postgres / Prisma)	docs/architecture.md	W4 audit	W4 DevEx	W4 live-demo, step 4
12	~130-line god function for CSV export	apps/api/src/routes/reports.ts	W2	W5 AI-assisted refactor	W5 live-demo, step 1
13	Zero tests for auth.service.ts	apps/api/src/services/auth.service.ts	W2	W5 AI-assisted refactor	W5 live-demo, step 2
14	TaskList renders 500 items (no virtualization)	apps/web/tests/components/TaskList.test.tsx	W2 profiling	W5 AI-assisted refactor	W5 live-demo, step 3
15	CommentList flaky relative timestamp	apps/web/tests/components/CommentList.test.tsx	W2 (when it fails)	W5 AI-assisted refactor	W5 live-demo, step 4
16	Login flaky missing-waitFor test	apps/web/tests/pages/Login.test.tsx	W2 (when it fails)	W5 AI-assisted refactor	W5 live-demo, step 5
17	Vitest singleFork: true no parallelism	apps/web/vite.config.ts	W2 profiling	W3 CI/CD optimization	W3 live-demo, step 4
18	Vitest coverage.enabled: true always on	apps/web/vite.config.ts	W2 profiling	W3 CI/CD optimization	W3 live-demo, step 3
19	No husky / pre-commit hook	(project root)	W4 audit	W7 standards	W7 live-demo, step 1
20	No AI usage policy	(project root)	W5 reflection	W7 standards	W7 live-demo, step 2

---

Reference branches (deterministic answer key)

The OrbitTasks repo (sample-repo/orbittasks, remote tbf-orbittasks) carries a cumulative stack of branches, one per code workshop, each holding that workshop's fixes pre-applied as one commit per live-demo step. main is the untouched baseline. Each branch builds on the previous, so w5-ai shows the repo after W2 through W5 combined. This is the answer key: a green, identical target to converge a drifting room onto, every cohort.

main (baseline, all pain points)
 └─ w2-profiling   flaky api tests fixed deterministically (fake timers)
     └─ w3-cicd     pipeline optimizations (cache, incremental, coverage, parallel, matrix+shard, deploy)
         └─ w4-devex   onboarding (setup.sh, README, .env, architecture, Makefile)
             └─ w5-ai     AI-assisted (refactor, auth tests, mock transport, virtualize, flaky FE fixes)
                 └─ w7-standards   husky+lint-staged+prettier, lint rule, PR template

W1, W6 and W8 make no code changes, so they have no branch. Each 0N-*/live-demo.md opens with a "Reference branch" block mapping every step to its commit. Verified on this build: test:api 231 tests in ~3s after the W5 mocks (was ~12 min), web 77 tests deterministic.

Three deliberate divergences from the older narration (flagged in the live-demo files):

1. W2 owns the flaky-api fix (branch w2-profiling), so everything downstream stays green; W5 still fixes the web flaky tests.
2. W3 keeps vitest isolate:true; flipping isolate:false over-shares jsdom here and breaks the web suite, so that stays a teaching beat, not the committed state.
3. W5 mocks at the transport seam (one fetch stub mirroring the mock server) instead of six per-client mocks, and rewrites the TaskList 500-render test into a window assertion plus a visibleRange unit test.

Branches are local-only until pushed: git push origin w2-profiling w3-cicd w4-devex w5-ai w7-standards.

How to use this during the workshop

Before each workshop, open the corresponding live-demo.md in the workshop folder. That file has the exact step-by-step screen-share script:

• workshops/02-profiling/live-demo.md
• workshops/03-cicd/live-demo.md
• workshops/04-devex/live-demo.md
• workshops/05-ai/live-demo.md
• workshops/07-standards/live-demo.md

The pattern in every live-demo:

1. I set the scene (30s): "OK, in your handout you flagged this issue. Let's fix it together."
2. I share screen and run/edit the offending file.
3. Students mirror me in their own clones. They commit alongside me.
4. I measure the before/after; students record the delta in their handout.
5. I move to the next issue.

This is faster, lower-anxiety, and more authentic than "go figure it out and report back." Real teams do it this way too: engineers learn from senior engineers walking them through it the first time.

When not to do it live

Three situations where solo work is better:

• The pain point is one a student already identified themselves and wants to fix on their own (encourage them).
• The fix has many right answers (e.g., README content); let students draft their own version, then compare.
• A student is significantly behind the group; give them solo catch-up time after class, not live-demo time.

Otherwise: demo it.