Appearance
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 |
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.mdworkshops/03-cicd/live-demo.mdworkshops/04-devex/live-demo.mdworkshops/05-ai/live-demo.mdworkshops/07-standards/live-demo.md
The pattern in every live-demo:
- I set the scene (30s): "OK, in your handout you flagged this issue. Let's fix it together."
- I share screen and run/edit the offending file.
- Students mirror me in their own clones. They commit alongside me.
- I measure the before/after; students record the delta in their handout.
- 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.