Micro Environment Simulator

---
name: micro-environment-simulator
description: Build a JavaScript micro environment simulator (abstract state machine) to replay workshop steps and verify environment assumptions.
disable-model-invocation: true
---

# Micro Environment Simulator

Use this skill when a workflow needs code-based simulation of learner environments before or during workshop replay analysis.

## Goal

Create and run a **JavaScript abstract state machine** that models student execution environments and validates workshop assumptions step-by-step.

## Included Source

Use the checked-in source directly (do not re-implement from scratch):

- `.github/skills/micro-environment-simulator/simulator.js`
- `.github/skills/micro-environment-simulator/workshop-student-journey.js` (workshop-specific example journey)
- `.github/skills/micro-environment-simulator/workshop-student-population.json` (explicit synthetic-population assumptions)

It exports:

- `defaultEnvironmentForStudent(student, dayOfYear)`
- `replayJourney({ student, date, initialState, steps, transitions })`
- `replayWorkshop({ student, date, initialState, steps, transitions })`
- `simulateStudents(students, date, config)`

CLI usage:

```bash
node .github/skills/micro-environment-simulator/simulator.js \
  --students /tmp/gh-aw/agent/sim/data/profiles.json \
  --journey .github/skills/micro-environment-simulator/workshop-student-journey.js \
  --date "$TODAY" \
  --out /tmp/gh-aw/agent/sim/data/environment-replay.json
```

Use `/tmp/gh-aw/agent/sim/data/environment-replay.json` as the source of environment mismatch diagnostics during simulation.

Generate a reproducible synthetic cohort from the maintained population model:

```bash
node .github/skills/micro-environment-simulator/simulator.js \
  --generate-population \
  --population-model .github/skills/micro-environment-simulator/workshop-student-population.json \
  --seed workshop-student-cohort \
  --out /tmp/gh-aw/agent/sim/data/profiles.json
```

The simulator API is workflow-agnostic. Each workflow should provide its own journey `steps` and `transitions`.

## Required Environment Model

Model environment state with explicit fields for:

- OS (`macos`, `linux`, `windows`)
- terminal (`bash`, `zsh`, `powershell`, `cmd`)
- installed software (`gh`, `aw`, and related versions)
- login status (`gh auth status` equivalent, including pre-authenticated Codespaces sessions)
- agent authentication material (`hasApiKey`, `hasCopilotRequestToken`)
- Actions model inference provider configuration (`github`, `anthropic`, `openai`)
- provider-specific Actions secrets (`COPILOT_GITHUB_TOKEN`, `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`)
- workflow permission gate for GitHub inference (`permissions.copilot-requests: write`), including enterprise org-billing behavior and regular org-owned repo fallbacks
- gh token scope (`user`, `org`)
- account type (`personal`, `enterprise-managed`)
- deployment type (`github.com`, `ghec`, `ghes`)
- workspace context (`codespaces`, `local`)

## Approach

1. Represent environment as immutable state snapshots.
2. Define workshop instructions as transitions with:
   - preconditions
   - state updates
   - expected observable outputs
3. Execute deterministic replay per student persona and stop on first violated precondition.
4. Emit structured diagnostics for each failure:
   - step id
   - failed assumption
   - current state
   - remediation hint

## Validation Rules

- Use JavaScript for simulator implementation.
- Keep transition logic deterministic and testable.
- Ensure every instruction checks assumptions before mutating state.
- Distinguish platform-specific command behavior across OS/terminal combinations.
- Distinguish auth/account/deployment constraints (`github.com` vs `ghec` vs `ghes`).
- Model org-scoped Codespaces token behavior where `gh extension install GitHub/gh-aw` can return HTTP 403 and requires install script remediation.

## Output Contract

Return concise JSON-friendly results that workflows can aggregate:

- completion status per student
- first failing step (if any)
- failure reason category
- normalized remediation action
- per-step at-risk counts and conditional dropout rates
- 95% intervals for Monte Carlo sampling uncertainty

Treat population distributions and transition coefficients as assumptions rather than observed learner data. Report that the confidence intervals exclude model and population-assumption uncertainty.

If assumptions hold for a full replay, mark the run successful and include the final state summary.

## Agent-Evaluated Content Assumptions

When an agent evaluates whether current workshop pages establish simulator state, pass the results with `--agent-insights`. Each step insight may include:

- `evaluatedContentHash`: the step's `contentHash` from a simulator run over the current pages
- `evaluations`: named, single-claim records with an `answer` of `YES`, `NO`, or `UNKNOWN` and `file:line` evidence

The simulator ignores evaluations whose content hash no longer matches the mapped workshop pages. Journey code must map known evaluation IDs to specific state fields; never apply arbitrary agent-provided state patches. Keep probability adjustments separate from state assumptions so a favorable score cannot bypass a failed prerequisite.