copilot.tools 1.0.0

package/skills/teach-me/SKILL.md

@@ -0,0 +1,1188 @@
+---
+name: teach-me
+description: Interactive code-teaching quiz with selectable themes (standard, SOLID, spec-to-code, BA documentation). Triggered by `/teach-me`, `teach me`, `quiz me`, or `test my knowledge`. Supports difficulty levels 1–5 and multiple response modes.
+user-invocable: true
+argument-hint: "Optional modifiers: level 1-5, interactive, solid, spec, ba, python, async, etc."
+---
+
+Copyright (C) 2026 Celestial Consulting Ltd
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+# Teach Me — Interactive Code Quiz
+
+An interactive teaching session that randomly selects code snippets or BA documentation fragments from the
+current project. Two independent dimensions combine to form each exercise:
+
+**Response mode** (how you answer — mid-session commands `passive` / `interactive`):
+- **`passive`** (default) — You describe your answer in the console.
+- **`interactive`** — You edit the actual file, then say `done` for verification.
+
+**Content theme** (what the exercise is about — trigger keywords `solid`, `spec`, `ba`):
+- **Standard** (default) — Code comprehension or line reconstruction.
+- **`solid`** / **`SOLID`** — Anti-pattern detection and design restoration.
+- **`spec`** — Spec-to-code traceability. Exercise shapes alternate randomly:
+  spec → code (show a requirement, ask what code implements it) or code → spec
+  (show code, ask what requirement it satisfies).
+- **`ba`** / **`ba-gates`** / **`requirements`** — BA documentation quality analysis.
+  Scans requirements documents (.docx, .pptx, .xlsx, .md, .feature, .txt) and
+  quizzes on three quality gates: ambiguity, acceptance criteria completeness,
+  and edge case coverage. Uses two-pass analysis: regex triage then LLM
+  interpretation per fragment. On skip, presents concrete improvement options.
+
+| Trigger | Response | Theme | What happens |
+|---------|----------|-------|-------------|
+| `teach me` | passive | standard | Present code; you explain what it does and how it works |
+| `teach me interactive` | interactive | standard | Lines removed from file; you restore them, say `done` |
+| `teach me solid` | passive | solid | Code rewritten with anti-patterns; you describe design fixes |
+| `teach me solid interactive` | interactive | solid | Code rewritten with anti-patterns; you edit the file to restore good design, say `done` |
+| `teach me spec` | passive | spec | Present spec or code; you describe the link between them |
+| `teach me spec interactive` | interactive | spec | Spec-to-code traceability; you edit code to satisfy a spec, say `done` |
+| `teach me ba` | passive | ba-gates | Present BA doc fragment; you identify quality gate violations |
+| `teach me ba interactive` | interactive | ba-gates | BA doc with quality issues; you edit the doc to fix them, say `done` |
+
+Level, scope, language, and concept modifiers combine freely with any
+combination above.
+
+## Session Trigger
+
+Activate when the user says any of:
+
+- `teach me`
+- `quiz me`
+- `test my knowledge`
+- `code quiz`
+- `drill me`
+- `explain this codebase`
+
+Optionally followed by modifiers:
+
+- `teach me python` — restrict to a specific language
+- `teach me level 3` / `teach me l3` — set difficulty (1–5)
+- `teach me <file or module>` — narrow scope to a specific file, directory, or module
+- `teach me <concept>` — target a specific language concept. Examples:
+  `teach me decorators`, `teach me async`, `teach me generators`,
+  `teach me context managers`, `teach me comprehensions`,
+  `teach me error handling`, `teach me type hints`, `teach me threading`
+- `teach me interactive` — edit the file (instead of describing)
+- `teach me solid` / `teach me SOLID` — anti-pattern restoration theme
+- `teach me spec` — spec-to-code traceability theme
+- `teach me ba` / `teach me ba-gates` / `teach me requirements` — BA documentation quality analysis theme
+- `quiz me on requirements` / `ba quality check` — alternative ba-gates triggers
+
+Modifiers combine freely: `teach me decorators level 4`,
+`teach me async services/`, `teach me generators l2`,
+`teach me level 2 interactive`, `teach me interactive decorators`,
+`teach me solid level 3`, `teach me SOLID`,
+`teach me solid interactive`,
+`teach me spec`, `teach me spec interactive`,
+`teach me ba`, `teach me ba level 3`,
+`teach me ba interactive`, `teach me ba <file>`,
+`teach me requirements level 4`
+
+If no level is specified, default to **level 3** and adjust based on
+performance across rounds.
+
+## Session Lifecycle
+
+### 1. Discovery — Map the Project
+
+Before presenting the first snippet:
+
+```
+A. Use file_search or list_dir to find source directories.
+B. Use grep_files to count function/class definitions per file.
+C. Build a mental index: file path → rough function/class count.
+D. Determine the primary language(s) from file extensions.
+E. Report: "Found ~N candidates across M files. Starting at level X. Ready."
+```
+
+If the user specified a scope, apply it during discovery. If the user
+specified a language, filter by extension.
+
+### 2. Selection — Pick a Snippet
+
+Randomly select a file from the index, then randomly select a function,
+method, or logical block from that file. **Re-read the file before each round**
+to ensure the snippet reflects the current on-disk state — the code may have
+changed since the session started. Use these rules:
+
+#### Good Snippets (select these)
+- Functions or methods 5–55 lines long (after stripping docstrings and blank lines)
+- Classes with 10–60 lines of method bodies
+- Blocks containing: decorators, comprehensions, generators, context managers,
+  async/await, error handling, design patterns, algorithm implementations,
+  non-obvious control flow, or domain-specific logic
+- Code that can be understood with at most one level of external context
+
+#### Avoid (skip these)
+- Pure getters/setters/properties (single-line `return self._x`)
+- Imports, module-level constants, config dicts, `__init__.py` with only imports
+- Boilerplate: `if __name__ == "__main__"`, argument parsers, logging setup
+- Dunder methods that only delegate
+- Functions shorter than 5 effective lines or longer than 60 lines
+- Code that requires reading 3+ other files to understand
+
+#### Difficulty → Line Ranges
+
+| Level | Lines  | Suitable patterns |
+|-------|--------|-------------------|
+| 1     | 5–15   | Straight-line logic, `if`/`else`, basic function calls |
+| 2     | 8–20   | Loops, list/dict operations, simple `try`/`except` |
+| 3     | 12–30  | Comprehensions, decorators, `with` statements, multiple branches |
+| 4     | 18–45  | Generators, `async`/`await`, descriptors, threading, closures |
+| 5     | 25–55  | Metaclasses, complex async patterns, multi-threading with synchronization, architectural glue code |
+
+#### No-repeats rule
+Track which snippets have been shown this session (file + line range).
+Do not repeat a snippet unless the user explicitly asks or all candidates
+are exhausted. Prefer cycling through files before returning to the same
+file.
+
+#### Concept Targeting
+
+When the user targets a specific concept, filter snippets to ensure they
+contain that concept. After selecting a random candidate, verify it with
+`grep_files` on the file for the concept signal. If the candidate doesn't
+match, pick another random snippet (retry up to 10 times; if still no
+match, relax the filter and note the fallback to the user).
+
+| Trigger phrase | Signal to verify in the snippet |
+|---|---|
+| `decorators` | `@` immediately above a `def` line |
+| `async` | `async def` or `await` |
+| `generators` | `yield` |
+| `context managers` | `with` statement or `__enter__`/`__exit__` |
+| `comprehensions` | `for ... in` inside `[`, `{`, or `(` |
+| `error handling` | `try:`, `except`, or `finally` |
+| `type hints` | `:` type annotation in function signatures or variable assignments |
+| `threading` | `Thread(`, `Lock(`, `Queue(`, or `threading.` |
+
+### 2b. Interactive (Standard) — Line Reconstruction
+
+When response mode is `interactive` (and theme is standard), each round follows
+a different flow from passive explanation. The model removes lines from the
+file and the user restores them.
+
+#### Lines Removed by Level
+
+| Level | Snippet lines | Lines removed |
+|-------|--------------|---------------|
+| 1     | 5–15         | 1             |
+| 2     | 8–20         | 1–2           |
+| 3     | 12–30        | 1–2           |
+| 4     | 18–45        | 2–3           |
+| 5     | 25–55        | 2–3           |
+
+#### Lines to Remove — Selection Heuristic
+
+- **Remove:** assignment statements, conditional branches, loop bodies, return
+  statements, function calls — lines that carry semantic weight and that
+  downstream lines depend on. Removing them should break the function.
+- **Never remove:** imports, blank lines, closing braces/brackets/parens,
+  decorator lines, function/class signatures, docstrings, comments.
+- Replace each removed span with a single placeholder comment:
+  `# ... N lines removed ...`
+- After removing lines from the file, **save the original lines** in memory for
+  later diffing against the user's restoration.
+
+#### Interactive Mode Per-Round Flow
+
+0. **Snapshot git state.** Run `git status --porcelain <file>` before touching
+   it. Note whether the file was clean or already had uncommitted changes.
+1. **Select** a snippet using the standard rules (section 2).
+2. **Save** the original lines in memory.
+3. **Remove** 1–3 lines from the actual file on disk using `edit_file`.
+4. **Present** the gapped snippet with the placeholder and the original line
+   numbers.
+5. **Instruct:** "Open `<file>`, restore the missing logic at the gap.
+   Say `done` or `check my work` when ready."
+6. **Wait.** Do not evaluate, hint, or proceed until the user signals
+   completion.
+7. **Re-read** the file. Diff the user's restored lines against the saved
+   original.
+8. **Feedback** (see Interactive Evaluation below). After feedback, restore
+   the file with `git checkout -- <file>` for a byte-perfect reset. If the
+   file had pre-existing uncommitted changes (from step 0), restore the
+   original lines manually via `edit_file` instead and warn the user.
+
+#### Thinking Suppression (Interactive Mode)
+
+During steps 1–4 (selection through presentation), use **Skip** thinking
+depth — emit no reasoning_content at all. Do not include the selected
+snippet, the original lines, or which lines are being removed. The
+thinking block is visible to the user and spoils the exercise before it
+begins. Resume normal thinking depth at step 5 (after presentation).
+
+The `edit_file` diff output is unavoidably visible in the transcript
+(CodeWhale transparency), but thinking control keeps the primary leak
+closed.
+
+#### Interactive Mode Presentation Format
+
+```
+---
+## Round N — Level X · interactive · concept | `path/to/file.py` (lines A–B)
+
+```python
+ 48      risk_amount = capital * (risk_per_trade / 100)
+ 49      # ... 2 lines removed ...
+ 50      return max(shares, 0)
+```
+
+⚠️ **Interactive — Reconstruction.** 2 lines have been removed (originally
+lines 49–50). Open `path/to/file.py`, find the placeholder, and restore the
+missing logic. When you're done, say **`done`** or **`check my work`**.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+### 2c. SOLID Theme — Anti-Pattern Reconstruction
+
+When content theme is `solid` (or `SOLID`), the model rewrites working code to
+be deliberately anti-pattern-ridden — breaking SOLID principles, DRY, cohesion,
+and abstraction — while keeping the code functional. The user must restore
+good design.
+
+SOLID theme works with both response modes:
+- **passive + solid** (`teach me solid`): User describes design fixes in console.
+- **interactive + solid** (`teach me solid interactive`): User edits the file.
+
+The per-round flow below covers both; where they differ, both variants are noted.
+
+#### Scope by Level
+
+| Level | Scope | Anti-patterns introduced |
+|-------|-------|--------------------------|
+| 1 | Single method, 5–15 lines | 2 (e.g., bad naming + duplication) |
+| 2 | Single method, 8–20 lines | 3–4 (add tight coupling, god method creep) |
+| 3 | Method + immediate collaborators, 12–30 lines each | 4–5 across methods (tight coupling, WET, poor cohesion) |
+| 4 | Small class, 18–45 lines of method bodies | 5–6 systemic anti-patterns |
+| 5 | Full class or multiple related classes, 25–55+ lines | Architectural: Singleton abuse, dependency inversion violation, shotgun surgery |
+
+#### Anti-Pattern Catalog
+
+The model chooses from this catalog when deconstructing code. Select
+anti-patterns appropriate to the language and scope:
+
+**STUPID principles (broken SOLID):**
+- **S**ingleton abuse — unnecessary global/static state
+- **T**ight coupling — hardcoded dependencies, `new` inside methods, no DI
+- **U**ntestable — no seams, side effects mixed with logic, `new Date()` inline
+- **P**remature optimization — complex code for imaginary performance needs
+- **I**ndescriptive naming — single-letter vars (`x`, `tmp`, `data`), misleading names
+- **D**uplication — copy-pasted logic blocks, WET (Write Everything Twice)
+
+**Broken design principles:**
+- Single Responsibility violation — one function/method does 3+ unrelated things
+- Open/Closed violation — `if isinstance()` chains or giant `switch` for extensibility
+- Interface Segregation violation — fat interfaces with unused methods
+- Dependency Inversion violation — high-level modules depending on low-level details
+- Leaky abstraction — exposing implementation details through the API
+- God object — one class/method that knows and does everything
+- Shotgun surgery — one change requires touching many files/methods
+
+#### SOLID Theme Per-Round Flow
+
+0. **Snapshot git state.** Run `git status --porcelain <file>` before touching it.
+1. **Select** a snippet using the standard rules (section 2). For levels 3–5,
+   read enough context (callers, callees, class definition) to rewrite coherently.
+2. **Save** the original code in memory (full selected scope).
+3. **Deconstruct** the code. Rewrite the file with `write_file` (full file) or
+   `edit_file` (targeted) to introduce anti-patterns. The code MUST still
+   compile/run and produce the same behavior as the original.
+4. **Present** the deconstructed code. State the scope, the number of
+   anti-patterns introduced, but do NOT name or annotate them — the user must
+   find them.
+5. **Instruct** (depends on response mode):
+   - *Interactive:* "Open `<file>`, fix the [N] anti-patterns. Say `done`."
+   - *Passive:* "Describe how you'd improve this code — what anti-patterns do
+     you see, and how would you fix them?"
+6. **Wait.** Do not evaluate until the user signals completion (`done` or answer).
+7. **Evaluate** (depends on response mode):
+   - *Interactive:* Re-read the file. Compare against saved original.
+   - *Passive:* Evaluate the user's description against the anti-patterns
+     that were introduced. No file re-read needed.
+8. **Feedback** (see SOLID Evaluation below).
+9. **Restore.** After feedback, `git checkout -- <file>` for a byte-perfect
+   reset. If pre-existing uncommitted changes (step 0), warn the user. For
+   passive mode, no file was modified by the user, but the deconstructed
+   code the model wrote must still be restored.
+
+#### Thinking Suppression (SOLID Mode)
+
+Same as interactive mode: use **Skip** thinking during steps 1–5 (selection
+through presentation). Resume normal depth at step 6. Never include the
+original code or the specific anti-patterns chosen in your reasoning.
+
+#### SOLID Mode Presentation Format
+
+```
+---
+## Round N — Level X · passive · solid | `path/to/file.py` (lines A–B)
+
+```python
+ 42  class ReportGenerator:
+ 43      def process(self, data):
+ 44          x = data.strip()
+ 45          # Parse + validate + format all in one method
+ 46          if ',' in x:
+ 47              parts = x.split(',')
+ 48              if len(parts) != 3: return None
+ 49              result = f"{parts[0].upper()}: {parts[1]} - {parts[2]}"
+ 50          elif '|' in x:
+ 51              parts = x.split('|')
+ 52              if len(parts) != 3: return None
+ 53              result = f"{parts[0].upper()}: {parts[1]} - {parts[2]}"
+ 54          else:
+ 55              return None
+ 56          # Save + notify all in one place
+ 57          db = DatabaseConnection()  # hardcoded dependency
+ 58          db.save(result)
+ 59          EmailSender().send("admin@corp.com", "Report", result)
+ 60          return result
+```
+
+⚠️ **SOLID Mode.** This code still works, but contains ~5 anti-patterns
+(violating SOLID, DRY, and cohesion principles). Open
+`path/to/file.py` and restore good design. When you're done, say
+**`done`** or **`check my work`**.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+### 2d. Spec Theme — Spec-to-Code Traceability
+
+When content theme is `spec`, the exercise bridges office documents (`.docx`,
+`.pptx`, `.xlsx`) and source code. Each round randomly alternates between two
+exercise shapes.
+
+#### Discovery (Spec Theme)
+
+In addition to the standard code discovery:
+1. Scan the workspace for `.docx`, `.pptx`, and `.xlsx` files.
+2. Extract text from each using `codewhale-doc-extract <file>` (global bin).
+3. Split extracted text into spec fragments: paragraphs, requirement bullets,
+   table rows, slide contents.
+4. Build a combined index: code fragments + spec fragments.
+
+#### Exercise Shapes
+
+Randomly choose one per round (50/50):
+
+**A. Spec → Code** — "Trace forward"
+- Present a spec fragment (a requirement, acceptance criterion, or spec
+  paragraph from an office document).
+- Ask: "What code in this project implements this specification?"
+- The user identifies or describes the matching code.
+
+**B. Code → Spec** — "Trace backward"
+- Present a code snippet from the project.
+- Ask: "What requirement or specification does this code satisfy?"
+- The user identifies the matching spec from the office documents.
+
+The model must verify the link in both directions — does the code actually
+implement the spec, and does the spec actually describe the code?
+
+#### Spec Theme Per-Round Flow
+
+0. **Snapshot git state.** Run `git status --porcelain` on all source files.
+1. **Pick direction** randomly (A or B). Select a fragment from the
+   appropriate index (spec index for A, code index for B).
+2. **Present** the fragment with its source (filename for code, document name
+   + section for specs).
+3. **Instruct** (depends on response mode):
+   - *Passive:* "Trace the link. What [code implements this spec / spec does
+     this code satisfy]? Describe in detail."
+   - *Interactive:* Same prompt, but also: "If the link is broken or missing,
+     edit the code to correctly implement the spec. Say `done` when ready."
+     For interactive: run `//snapshot on` first if the workspace is NOT a git
+     repo.
+4. **Wait.** Do not evaluate until the user signals completion.
+5. **Evaluate** (depends on response mode):
+   - *Passive:* Assess the user's trace — did they correctly identify the
+     link? Is their reasoning sound?
+   - *Interactive:* Re-read the modified files. Compare against the spec.
+     Does the code now correctly implement the requirement?
+6. **Feedback** — structure:
+   ```
+   **Trace accuracy:** [Correct / Partially correct / Incorrect]
+   **What you got right:** [the link they correctly identified]
+   **What you missed:** [missed connections between spec and code]
+   ```
+7. **Restore** (interactive only). If files were modified: `git checkout -- <file>`.
+   If not a git repo, `//snapshot off` to stop backing up.
+
+#### Thinking Suppression (Spec Theme)
+
+Use **Skip** thinking during selection and presentation (steps 1–3). Resume
+normal depth at step 4. Never reveal the correct trace link in reasoning.
+
+#### Spec Theme Presentation Format
+
+```
+---
+## Round N — Level X · passive · spec | Spec → Code
+
+**From:** `QA Cinemas Requirements.pptx` — Slide 4, "Website Requirements (1)"
+
+> The QA Cinemas site needs a home page. The home page shall: Be generally
+> attractive. Be the default for the entire site. Allow site users to navigate
+> to other areas of the site. Have a picture or graphic evocative of the
+> movies or the cinema on it.
+
+**Your turn:** (Passive) What code in this project implements the QA Cinemas
+home page requirement? Trace the link — describe which file(s) and how they
+satisfy these criteria.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+### 2e. BA-Gates Theme — BA Documentation Quality Analysis
+
+When content theme is `ba-gates` (triggered by `teach me ba`, `teach me ba-gates`,
+`teach me requirements`, `quiz me on requirements`, or `ba quality check`), the model
+scans BA documentation across all supported formats and quizzes the user on three
+quality gates: **ambiguity**, **acceptance criteria completeness**, and
+**edge case coverage**. The goal is to surface documentation quality gaps and
+present concrete improvement options.
+
+BA-Gates theme supports both response modes:
+- **passive + ba-gates** (`teach me ba`): User describes gate violations in console.
+- **interactive + ba-gates** (`teach me ba interactive`): User edits the document to
+  fix the issues, says `done`.
+
+#### Discovery (BA-Gates Theme) — Two-Pass Architecture
+
+The discovery phase runs two passes: a fast heuristic triage (Pass 1) followed by
+LLM interpretation of flagged fragments (Pass 2 at round time).
+
+#### Pass 1: Regex Triage
+
+Purpose: narrow the field. Cheap, fast pattern matching to answer "which fragments
+probably have quality issues?" Not an answer — a filter.
+
+1. **Scan for BA documents.** Use `file_search` and `list_dir` to find files in the workspace:
+   - Office formats: `.docx`, `.pptx`, `.xlsx`
+   - Plaintext formats: `.md`, `.feature`, `.txt` (filter to those containing requirements/spec keywords: `feature`, `scenario`, `user story`, `requirement`, `acceptance`, `given`, `when`, `then`, `background`, `example`)
+   - Do NOT scan source code files (`.py`, `.js`, `.ts`, `.java`, `.cs`, `.go`, `.rs`, `.c`, `.cpp`, `.h`).
+
+2. **Extract text** from office files:
+   - Run `codewhale-doc-extract <file>` for `.docx` and `.pptx` files
+   - For `.xlsx` files: use `codewhale-doc-extract` to extract table data
+   - If extraction fails for any file, note it and skip that file
+
+3. **Read plaintext files** directly with `read_file`.
+
+4. **Split into fragments:**
+   - Feature blocks (Gherkin `Feature:` through the examples table)
+   - Scenario blocks (individual `Scenario:` or `Scenario Outline:` sections)
+   - Background blocks (`Background:` sections)
+   - Requirement paragraphs (standalone lines with "shall", "must", "should", "will")
+   - User story blocks (lines matching "As a... I want... So that...")
+   - Acceptance criteria lists (bullet points under a story)
+   - Example/Data tables (tabular data in `.feature` or `.md` files)
+   - Slide content (per-slide extracts from `.pptx`)
+   - Spreadsheet row groups (per-sheet or per-section from `.xlsx`)
+
+5. **Run the three heuristic gate scans** against each fragment. These are
+   pattern-based, not semantic — they catch surface signals only.
+
+   **Gate 1 — Ambiguity patterns:**
+   - Vague qualifiers: `should`, `maybe`, `perhaps`, `generally`, `typically`, `normally`, `usually`, `approximately`, `about`, `roughly`, `ideally`, `preferably`, `optionally`
+   - Unmeasurable adjectives: `fast`, `slow`, `good`, `bad`, `intuitive`, `user-friendly`, `robust`, `reliable`, `scalable`, `flexible`, `easy`, `simple`, `clean`, `nice`, `attractive`, `modern`, `efficient`, `powerful`, `seamless`, `smooth`, `responsive`, `high-quality`, `performant`
+   - Vague nouns (without specifics): `stuff`, `things`, `data`, `information`, `details`, `content`, `items`, `results`
+   - Passive/unattributed states: `is ready`, `is configured`, `is loaded`, `is set up`, `is available`, `is enabled`, `is active`
+   - Missing quantifiers: `a list of` without pagination/ordering/format spec, `results` without count or structure, `some`, `several`, `various`
+   - Ambiguous connectives: `and/or`, `etc.`, `and so on`, `...`, `such as`
+
+   **Gate 2 — AC Completeness patterns:**
+   - Missing Given/When/Then markers in scenario blocks
+   - Unmeasurable outcomes (Then steps with Gate 1 ambiguity terms, or outcomes that restate the story)
+   - Blank or empty cells in example tables
+   - Example table rows with populated input columns but empty expected-output columns
+   - Stories with body text but no AC bullet points
+
+   **Gate 3 — Edge Case patterns:**
+   - Fragment contains only positive-case examples (no error, invalid, or failure scenarios)
+   - No examples at value boundaries (zero, empty string, max length, null, negative values)
+   - Edge case scenario rows where expected outcomes are blank (acknowledged but unresolved)
+   - No examples of: empty input, no results, invalid format, expired state, concurrency, timeout
+
+6. **Build the candidate index.** Store for each flagged fragment:
+   ```
+   fragment_id → {
+     source: file + line range,
+     text: fragment content,
+     regex_flags: [which patterns matched and where],
+     gate_triggers: [which of the 3 gates fired]
+   }
+   ```
+   Discard fragments with zero gate triggers — they are not quiz candidates.
+
+7. Report: "Scanned N BA documents → M fragments. Pass 1 flagged X candidates across Y documents. Starting at level X. Ready."
+
+#### Pass 2: LLM Interpretation (at Round Time)
+
+Pass 2 runs **per fragment, at the start of each round, before presentation**.
+The regex said "this fragment has a flag." Pass 2 asks: "is this flag meaningful,
+and if so, what's the best way to quiz on it?"
+
+This is deep-thinking work. The model must understand the fragment before it can
+teach from it.
+
+When a candidate fragment is selected for a round:
+
+1. **Read the fragment in context.** Re-read the surrounding file: the full feature,
+   adjacent scenarios, the feature title and description. What is this document
+   trying to specify? What domain is it in? What would the implementing developer
+   need to know?
+
+2. **Interpret the regex flags semantically.** For each regex flag:
+   - Is this actually a problem, or a false positive? (e.g., "should" in "the user
+     should see an error message" is fine — it's an observable outcome. "Should" in
+     "the system should be fast" is a problem.)
+   - What would a developer be confused by? What would they have to guess?
+   - What would they have to go back and ask the BA about?
+   - What edge cases are implied by the domain but not stated?
+   - What's the **most important gap** — not the most numerous, but the one that
+     would cause the most rework or the most ambiguity?
+
+3. **Generate the quiz material:**
+
+   a. **Question** — framed to test whether the BA can see the gap and understand
+      why it matters. Not "spot the vague word" but "what's missing that would
+      prevent a developer from implementing this deterministically?"
+
+   b. **Expected answer** — the specific gate(s) violated, the specific fragment
+      location, and why it matters to downstream development.
+
+   c. **Strike-1 hint** — category nudge (name the gate, not the issue).
+
+   d. **Strike-2 hint** — near-explicit (name the gate AND point to the location,
+      hint at the nature of the gap).
+
+   e. **Improvement options** — 2–3 concrete, domain-specific rewrites of the
+      fragment with a "best fit" recommendation. Prefer specific data, concrete
+      assertions, and verifiable preconditions over abstract advice.
+
+   f. **What the developer would trip over** — a one-line summary of the practical
+      impact. This is revealed as part of the improvement options, not in the
+      question itself.
+
+4. **Verify the fragment is quiz-worthy.** If Pass 2 determines all regex flags
+   are false positives and there is no meaningful quality gap, discard the
+   fragment and select another. Do not fabricate issues.
+
+5. **Store the generated material** in memory for evaluation. Do NOT include it
+   in reasoning_content from this point forward — switch to Skip thinking before
+   presenting to the user.
+
+#### Difficulty Levels (BA-Gates)
+
+| Level | Fragment scope | What the regex flags | What Pass 2 interprets | What the user must do |
+|-------|---------------|---------------------|----------------------|----------------------|
+| 1 | Single requirement line or story title (1–3 lines) | 1 obvious surface flag | Confirm the flag is real; generate a direct question | Identify the gate and the flagged term |
+| 2 | Single scenario or AC block (3–10 lines) | 1–2 gate triggers | Assess false positives; pick the most meaningful gap | Identify all gate violations and the specific offending terms |
+| 3 | Full feature or story with examples (10–30 lines) | Multiple triggers across at least 2 gates | Distinguish surface flags from structural gaps; identify domain implications | All violations + explain why the most important one matters to development |
+| 4 | Multi-scenario feature or cross-document fragment (20–60 lines) | Cross-cutting patterns | Identify systemic documentation debt; what pattern recurs? | Systemic issues + propose fixes for each gate with rationale |
+| 5 | Full document or multi-document comparison | Architectural documentation debt | Structural weaknesses across the document set; what's the root cause? | Prioritised improvement plan with concrete rewrites across multiple fragments |
+
+#### BA-Gates Per-Round Flow
+
+0. **Snapshot git state.** Run `git status --porcelain` on BA document files. If the workspace is NOT a git repo, run `//snapshot on` for interactive mode.
+1. **Select** a candidate fragment from the Pass 1 index, weighted by:
+   - Prioritize fragments that trigger multiple gates over single-gate fragments
+   - Prioritize higher-confidence flags at higher difficulty levels
+   - Avoid repeating the same fragment unless all candidates are exhausted
+2. **Run Pass 2 LLM interpretation.** Deep thinking — read context, interpret flags, assess false positives, identify the most important gap, generate quiz material.
+3. **Verify quiz-worthiness.** If Pass 2 finds no meaningful gap, discard and loop to step 1.
+4. **Suppress thinking.** Switch to Skip thinking depth from this point through presentation.
+5. **Present** the fragment with its source, line/cell reference, and a gate-count hint — but do NOT reveal which gates or where.
+6. **Instruct** (depends on response mode):
+   - *Passive:* "Which of the three BA quality gates does this fragment trigger — Ambiguity, Acceptance Criteria Completeness, or Edge Case Coverage? Describe what specifically is the problem and how a developer would be affected."
+   - *Interactive:* "The document has quality issues flagged by the BA gates. Open `<file>`, find and fix the issues. Say `done` when ready." For interactive with office files (`.docx`, `.pptx`, `.xlsx`), present extracted text inline and ask the user to describe the fix since they cannot edit binaries directly.
+7. **Wait.** Do not evaluate until the user signals completion.
+8. **Evaluate** against the Pass 2 generated answer. Use the three-strikes system with the generated hints.
+9. **Feedback + Improvement Options.** On success, highlight what they got right and what they could sharpen. On skip or strike-3, present the Pass 2 generated improvement options with the "what the developer would trip over" summary.
+10. **Restore** (interactive only for plaintext files). For office files, no restoration needed.
+
+#### Thinking Suppression (BA-Gates Theme)
+
+- **Pass 2 analysis (step 2):** Use **Deep** or **High** thinking. This is where the model reasons about the fragment and generates quiz material. The thinking block will contain the generated answer — this is acceptable since the user has not yet seen the fragment.
+- **Presentation onward (steps 4–10):** Use **Skip** thinking. Never reveal the specific gates triggered, their locations, or the generated answer in reasoning once the fragment is presented.
+
+#### BA-Gates Presentation Format
+
+```
+---
+## Round N — Level X · passive · ba-gates | `timesheet.feature.txt` (lines 1–5)
+
+**From:** `timesheet.feature.txt` — Background section
+
+```gherkin
+Feature: Timesheet Calculations from FitNesse
+  Background:
+    Given the timesheet system is ready
+    And hourly rates are configured
+```
+
+⚠️ **BA-Gates Mode.** This fragment triggers one or more BA documentation quality
+gates (Ambiguity, Acceptance Criteria Completeness, or Edge Case Coverage).
+
+**Your turn:** (Passive) Which gate(s) does this fragment trigger? Describe
+what specifically is the problem and how a developer would be affected.
+
+Type `hint` for a clue, `skip` to see the full analysis and improvement options, or `stop` to end.
+---
+```
+
+#### BA-Gates Interactive Presentation Format
+
+For plaintext files (`.md`, `.feature`, `.txt`), the model does NOT edit the file — the user edits it:
+
+```
+---
+## Round N — Level X · interactive · ba-gates | `qa_cinemas_ac_scenarios.md`
+
+**From:** `qa_cinemas_ac_scenarios.md` — Scenario: "Return relevant results for valid keyword searches"
+
+```gherkin
+  Scenario Outline: Return relevant results for valid keyword searches
+    When the user clicks the search box
+    Then the placeholder text is removed
+    When the user types <keyword> into the search box
+    And clicks the Search button
+    Then the typed text remains visible in the search box
+    And <expected_result>
+```
+
+⚠️ **BA-Gates Interactive.** This fragment has quality issues. Open
+`qa_cinemas_ac_scenarios.md`, find and fix the issues. When you're done,
+say **`done`** or **`check my work`**.
+
+Type `hint` for a clue, `skip` to see the full analysis, or `stop` to end.
+---
+```
+
+For office files (`.docx`, `.pptx`, `.xlsx`), interactive mode presents the extracted text inline and asks the user to describe the fix since they cannot edit the binary directly.
+
+#### BA-Gates Evaluation
+
+Score across three dimensions aligned to the gates. Use the Pass 2 generated expected answer as the reference:
+
+| Dimension | What to check |
+|-----------|--------------|
+| **Ambiguity detection** | Did the user identify vague qualifiers, unmeasurable adjectives, passive/unverifiable states? |
+| **AC completeness** | Did the user spot missing structure, unmeasurable outcomes, blank table cells, circular AC? |
+| **Edge case coverage** | Did the user identify missing negative scenarios, boundary tests, error states, unresolved edge cases? |
+
+**Outcome levels:**
+
+| Outcome | Criteria | Feedback approach |
+|---------|----------|-------------------|
+| **Complete** | Identified all gate triggers at the current level with specific references | Highlight what they caught + 1–2 things to sharpen |
+| **Partial** | Identified some triggers, or named gates without specifics | Strike-1 or strike-2 nudge toward the missed gate |
+| **Missed** | Did not identify the primary gate trigger(s) | Strike-2 or strike-3 with full improvement options |
+
+#### Strikes in BA-Gates Mode
+
+Use the Pass 2 generated hints:
+
+**Strike 1** — Category nudge (name the gate, not the issue):
+```
+Good effort. Think about Gate 1 (Ambiguity) — are there any terms in this
+fragment that can't be measured, verified, or tested programmatically?
+```
+
+**Strike 2** — Near-explicit hint (name the gate AND point to the location):
+```
+You're getting there. Look at "the timesheet system is ready" on line 3.
+This is a passive state — what observable condition would prove readiness?
+Also check line 4 — same pattern.
+```
+
+**Strike 3** — Reveal full analysis with improvement options (see below). Move to next round automatically.
+
+#### Improvement Options on Skip or Strike-3
+
+When the user skips or reaches strike-3, present the Pass 2 generated improvement options. Structure:
+
+```
+⚑ Gate 1 — Ambiguity (2 issues)
+
+  Issue 1: "the timesheet system is ready" (line 3)
+    Problem: Passive state — no observable condition. "Ready" is not verifiable.
+    Developer impact: A developer writing the test harness can't assert
+    "readiness" without guessing what condition to check.
+
+    → Option A: "the TimesheetService health endpoint returns HTTP 200"
+    → Option B: "the time_normalizer module is initialised with a valid rate table"
+    → Option C: "the database connection pool reports status 'active'"
+    → Best fit: Option B (directly tests the component under test)
+
+  Issue 2: "hourly rates are configured" (line 4)
+    Problem: Passive state — no verifiable precondition. "Configured" is not testable.
+    Developer impact: A developer must either hardcode a rate (fragile) or ask
+    the BA what specific rate to use.
+
+    → Option A: "a rate of $25.00 exists for employee E001 in the rates table"
+    → Option B: "the /api/rates endpoint returns at least one active rate with amount > 0"
+    → Option C: "the rates configuration file contains at least one entry with key 'default_rate'"
+    → Best fit: Option A (concrete data, directly usable in the test)
+
+💡 Pattern: Replace Background preconditions with programmatically verifiable
+   states. Every Given step should map to an assertion that can pass or fail
+   deterministically in the test harness.
+---
+
+⚑ Gate 2 — Acceptance Criteria Completeness (1 issue)
+
+  Issue: Both Background steps lack verifiable structure — they are preconditions
+    but cannot be asserted against.
+  Developer impact: The test setup phase has no concrete fixture to build.
+
+  → Improve: Rewrite as:
+    Given the TimeNormaliser service is running on localhost:8080
+    And the rates table contains {"E001": 25.00, "E002": 18.50}
+    And the time_normalizer module reports status "ready"
+
+💡 Pattern: Background steps create the test fixture. Every step should
+   create a specific, named piece of state that subsequent steps can reference.
+---
+
+⚑ Gate 3 — Edge Case Coverage (1 issue)
+
+  Issue: Background section defines no edge cases for system state.
+    What happens if the system is NOT ready? If rates are NOT configured?
+  Developer impact: Error paths are undefined — a developer must guess what
+    error to return for each failure state.
+
+  → Improve: Add an edge-case scenario:
+    Scenario: Timesheet calculation fails when system is not ready
+      Given the timesheet system reports status "degraded"
+      When an employee attempts to check in at 09:00 AM
+      Then the system returns error "SYSTEM_NOT_READY"
+      And no hours are recorded
+```
+
+The improvement options MUST be concrete and domain-specific. Prefer specific data values, concrete assertions, and verifiable preconditions over abstract advice. For each issue, present 2–3 options with a "best fit" recommendation.
+
+---
+
+### 3. Presentation — Show the Snippet
+
+For each round, present the snippet with its filename:
+
+```
+---
+## Round N — Level X · [passive|interactive] · [concept|solid|spec|ba-gates] | `path/to/file.py` (lines A–B)
+
+```python
+ 42  def calculate_position_size(
+ 43      capital: float,
+ 44      risk_per_trade: float,
+ 45      entry_price: float,
+ 46      stop_loss: float
+ 47  ) -> int:
+ 48      risk_amount = capital * (risk_per_trade / 100)
+ 49      price_risk = abs(entry_price - stop_loss)
+ 50      if price_risk == 0:
+ 51          return 0
+ 52      shares = int(risk_amount / price_risk)
+ 53      return max(shares, 0)
+```
+
+**Your turn:** (Passive mode) Explain what this code does (application logic)
+AND how it works (syntax and semantics). Include any edge cases you notice.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+Guidelines:
+- Include realistic line numbers (1-based from the actual file)
+- Strip only excessive blank lines; keep natural spacing
+- Show the function/class signature with its decorators
+- Show the filename and line range in the header
+- The response mode tag (`· passive` or `· interactive`) always appears in the header
+- The theme/concept tag (`· solid` for SOLID theme, `· spec` for spec theme, `· ba-gates` for BA-Gates theme, or `· decorators` etc. for targeted concept) appears when applicable; omit during free-play standard rounds
+- If the snippet depends on one obvious external type or constant, include a
+  brief inline note
+- **Before presenting, scan for secrets.** Redact API keys, tokens, passwords,
+  connection strings with `[REDACTED]`. Skip snippets that are entirely
+  secrets or contain PII/email addresses/personal identifiers.
+
+### 4. Evaluation — Assess the Answer
+
+Evaluate across two dimensions, scaled to the current difficulty level.
+
+#### A. Application Logic (what the code does in the project)
+
+| Level | Expectation |
+|-------|-------------|
+| 1 | Names what the function does at a basic level |
+| 2 | Identifies inputs, outputs, and at least one edge case |
+| 3 | Explains the module role, failure modes, and upstream/downstream connections |
+| 4 | Identifies the design pattern, multi-component interaction, and concurrency edge cases |
+| 5 | Explains architectural role across system layers, performance implications, and subtle bugs or limitations |
+
+#### B. Language Mechanics (syntax and semantics)
+
+| Level | Expectation |
+|-------|-------------|
+| 1 | Basic types, function definition syntax, simple `if`/`else` |
+| 2 | Loop mechanics, list/dict operations, basic `try`/`except`, string formatting |
+| 3 | Comprehensions, decorator syntax and effect, `with` / context managers, type hints, exception chaining |
+| 4 | Generator mechanics (`yield`), `async`/`await` internals, descriptor protocol, closures, threading primitives |
+| 5 | Coroutine internals, metaclass programming, GIL implications, memory model, `__slots__`, MRO, weak references |
+
+#### C. Interactive Mode Evaluation
+
+When mode is `interactive`, evaluation is a diff between the user's restored
+lines and the saved original:
+
+| Outcome | Criteria | Feedback |
+|---------|----------|----------|
+| **Exact match** | Lines match character-for-character | ✅ Perfect. Note what the lines do and why they matter. |
+| **Semantic match** | Same logic, different variable names or formatting | ✅ Good — logic is correct. Note the stylistic difference. |
+| **Partial match** | Some lines correct, some missing/wrong | Point out which line(s) are correct and which need work. Treat as strike 1 or 2 depending on how much is missing. |
+| **No match** | Lines are absent or entirely wrong | Strike-1 nudge toward the missing logic. |
+
+Do not use the standard three-strikes verbal pipeline for interactive mode.
+Instead, use targeted hints about what the missing lines should compute:
+
+**Strike 1** — Category nudge:
+```
+Not quite. Think about what calculation happens between [visible line above
+the gap] and [visible line below the gap].
+```
+
+**Strike 2** — Near-explicit hint:
+```
+You need to [specific operation — e.g., "divide risk_amount by price_risk
+and guard against division by zero"].
+```
+
+**Strike 3** — Reveal the original lines and move to the next round:
+```
+Here's what was removed:
+```python
+ 49      price_risk = abs(entry_price - stop_loss)
+ 50      if price_risk == 0:
+ 51          return 0
+ 52      shares = int(risk_amount / price_risk)
+```
+
+After strike 3, restore the original lines in the file and proceed to the
+next round automatically (no "another round?" prompt).
+
+#### D. SOLID Mode Evaluation
+
+When mode is `solid`, evaluation compares the user's restored design against
+the saved original and the anti-patterns that were introduced. Score across
+these dimensions:
+
+| Dimension | What to check |
+|-----------|--------------|
+| **Anti-patterns fixed** | How many of the N introduced anti-patterns did the user address? |
+| **Design quality** | Does the restored code follow SOLID, DRY, and cohesion principles at least as well as the original? |
+| **Functional correctness** | Does the code still work? Same inputs → same outputs? |
+| **Intentionality** | Did the user identify WHY each anti-pattern was wrong, or just guess? |
+
+Feedback structure:
+
+```
+**Anti-patterns addressed:** [N/M] — [list which ones and how]
+
+**What you improved:**
+- [specific anti-pattern they fixed well]
+
+**What you missed:**
+- [anti-patterns still present or not fully addressed]
+
+**Comparison to original:**
+[How their solution compares to the original — is it equivalent, better, or
+does it introduce new issues?]
+```
+
+**Strikes in SOLID mode:**
+
+**Strike 1** — Category nudge (name the principle, not the fix):
+```
+Good effort. Think about [principle — e.g., "Single Responsibility"] —
+does this method do too many different things?
+```
+
+**Strike 2** — Near-explicit hint (name the anti-pattern):
+```
+You're close. Look at the duplication between lines 46-49 and 50-53. That's
+WET code — both branches do the same parsing. Also, `DatabaseConnection()`
+on line 57 creates tight coupling.
+```
+
+**Strike 3** — Reveal the original code and move to the next round:
+```
+Here's the original design. Compare it with yours to see what was improved.
+```
+Then restore with `git checkout -- <file>` and proceed automatically.
+
+#### E. BA-Gates Mode Evaluation
+
+When theme is `ba-gates`, evaluate the user's ability to identify and diagnose
+documentation quality issues against the Pass 2 generated expected answer:
+
+| Outcome | Criteria | Feedback approach |
+|---------|----------|-------------------|
+| **Complete** | Identified all gate triggers at the current level with specific line/cell references | Highlight what they caught + 1–2 things to sharpen |
+| **Partial** | Identified some triggers, or named gates without specifics | Strike-1 or strike-2 nudge toward the missed gate |
+| **Missed** | Did not identify the primary gate trigger(s) | Strike-2 or strike-3 with full improvement options |
+
+See section 2e (BA-Gates Theme) for the full strike system and improvement options format.
+
+#### Weighted Evaluation for Targeted Concepts
+
+When a concept is targeted (e.g., `teach me decorators`), bias the
+evaluation toward that concept:
+
+- **Mechanics axis:** The targeted concept carries extra weight. Missing
+  it is a significant gap even if other mechanics are handled well.
+- **Strike hints:** Always steer strike 1 toward the targeted concept
+  before hinting about any other missed item.
+- **Feedback ordering:** List the targeted concept first under "What you
+  missed" or "What you could sharpen."
+- **Success bar:** To "meet expectations," the user must correctly
+  explain the targeted concept at the current level's depth.
+
+#### The Three-Strikes Rule
+
+If the user's answer does **not** meet the expectations for the current
+difficulty level:
+
+**Strike 1** — Give a category-level nudge:
+```
+Good start, but at Level N I'd expect you to also notice [category — e.g.,
+"how errors are handled" or "what the decorator is doing"]. Try again —
+what about [specific nudge — e.g., "the return type on line 47"]?
+```
+
+**Strike 2** — Give a near-explicit hint:
+```
+Getting closer. One more thing — [nearly names the concept — e.g., "that
+@retry decorator wraps the function"]. Look at line X.
+```
+
+**Strike 3** — Reveal the full answer and move on:
+```
+Let me walk you through it.
+```
+Then deliver the complete evaluation (both axes) as if they had skipped.
+After the evaluation, proceed directly to the next round — do not ask
+"another round?" after a strike-3 reveal; just present the next snippet.
+
+If the user gets it on attempt 2 or 3:
+```
+There you go! Now let me fill in what else is notable.
+```
+Then provide the remaining feedback they missed, and ask "Another round?".
+
+If the user's answer **meets** expectations (any attempt):
+- Highlight 2–4 specific things they got right
+- Add 1–3 things they could sharpen (even a strong answer has nuance)
+- Reveal the file context
+- Ask "Another round?"
+
+#### Feedback structure (success or strike-3 — standard/spec modes)
+
+```
+**What you got right:**
+- [2–4 specific things correctly identified]
+
+**What you missed or could sharpen:**
+- [1–3 things, with brief explanation]
+
+**Context:** `services/position_sizer.py` — called by the OrderManager before
+placing any trade. Sits between the signal generator and the exchange adapter.
+```
+
+Keep feedback constructive. The goal is learning, not grading. If they
+nailed everything at-level, say so and highlight the nuance they caught.
+
+### CONTINUE THE SESSION
+
+**After every single round — success, skip, next, or strike-3 — you MUST
+either ask "Another round?" or present the next question automatically.
+Never deliver feedback and then stop. The session only ends when the user
+explicitly says `stop`.**
+
+- Success / `next` / `another` → ask: "Another round? (yes / no / level N / ...)"
+- Strike-3 / `skip` / `reveal` → auto-advance: present the next round header immediately
+- `stop` / `end` → deliver the end-of-session summary
+
+#### Handling commands mid-round
+
+| Command | Behavior |
+|---------|----------|
+| `hint` | Give one strike-1 level nudge (counts as an attempt in the strike system) |
+| `skip` / `reveal` | Show full evaluation immediately, then present next round without asking. |
+| `next` / `another` | Skip this snippet, draw a new one. No strike counted. |
+| `level N` / `lN` (e.g. `level 5`, `l2`) | Adjust difficulty for subsequent rounds. |
+| `easier` | Decrease level by 1 (minimum 1). |
+| `harder` | Increase level by 1 (maximum 5). |
+| `interactive` | Switch to interactive (reconstruction) mode for subsequent rounds. |
+| `passive` | Switch to passive (explanation) mode for subsequent rounds. |
+| `solid` / `SOLID` | Switch to SOLID (anti-pattern reconstruction) theme for subsequent rounds. |
+| `spec` | Switch to spec (spec-to-code traceability) theme for subsequent rounds. |
+| `ba` / `ba-gates` / `requirements` | Switch to BA-Gates (BA documentation quality) theme for subsequent rounds. |
+| `done` / `check my work` | (Interactive/SOLID/Spec/BA-Gates mode) Signal that work is complete. Triggers verification. |
+| `stop` / `end` | End session. Deliver summary. |
+
+### 5. Loop — Keep Going
+
+After a successful evaluation or a `next` skip, ask:
+"Another round? (yes / no / level N / interactive / passive / solid / spec / ba / stop)"
+
+After a strike-3 reveal, do **not** ask — proceed directly to the next
+round with:
+"Round N+1 — Level X · [mode] | `file.py`"
+
+### End-of-Session Summary
+
+When the user says `stop`:
+
+```
+## Session Summary
+
+Rounds completed: 5
+Level played: 3 · Mode: passive
+Files covered:
+  - services/position_sizer.py (rounds 1, 4)
+  - agents/news_agent.py (round 2)
+  - utils/fuzzy_dedup.py (round 3)
+  - database.py (round 5)
+
+What you're strong on: [concepts consistently identified]
+What to review:    [concepts missed across multiple rounds]
+Suggested next level: [3 → 4, or stay, or 3 → 2]
+```
+
+For BA-Gates sessions, the summary covers documents and gates instead of code files:
+```
+## Session Summary
+
+Rounds completed: 4
+Theme: ba-gates · Mode: passive · Level: 3
+Documents covered:
+  - timesheet.feature.txt (rounds 1, 3)
+  - qa_cinemas_ac_scenarios.md (round 2)
+  - QA Cinemas Requirements.pptx (round 4)
+
+Gates mastered:      Ambiguity detection (rounds 1, 4) ✓
+Gates to strengthen: Edge case coverage (rounds 2, 3)
+Suggested next level: 3 → 4
+```
+
+## Multilingual Projects
+
+If the project contains multiple languages, let the user's `teach me <lang>`
+filter govern. If no filter, sample all languages proportionally but announce
+the language in each round header. Use language-appropriate evaluation
+criteria for the Mechanics axis:
+
+- **Python:** decorators, generators, descriptors, `async`/`await`, type hints,
+  context managers, MRO, slots, data classes
+- **JavaScript/TypeScript:** closures, prototypes, `this` binding, promises,
+  async/await, destructuring, spread, arrow functions, TypeScript generics
+- **Rust:** ownership, borrowing, lifetimes, pattern matching, `Result`/`Option`,
+  traits, generics, macros
+- **Go:** goroutines, channels, interfaces, defer, error handling conventions,
+  zero values
+- **Java:** streams, generics, annotations, try-with-resources, concurrency
+  primitives, inheritance vs composition
+
+## Guardrails
+
+- **Never show secrets.** Scan every snippet before display. Redact API keys,
+  tokens, passwords, connection strings with `[REDACTED]`. Skip entire snippets
+  that are only secrets/config.
+- **Never show user data.** Skip snippets containing PII, email addresses,
+  phone numbers, or personal identifiers.
+- **One snippet per turn.** Wait for the user's response before showing the next.
+- **Respect stop immediately.** If the user says `stop`, deliver the summary —
+  do not squeeze in another round.
+- **Stay in teaching mode.** Do not fix bugs, refactor, or edit code during a
+  teaching session unless the user explicitly asks to switch modes.
+- **Interactive mode file edits.** The model MAY remove lines from files to set
+  up reconstruction exercises. The model MUST NOT add or modify lines — only
+  the user restores code.
+- **SOLID mode file rewrites.** The model MAY rewrite files to introduce
+  anti-patterns. The deconstructed code MUST still compile/run with the same
+  behavior. The model MUST NOT delete code or break functionality — only
+  degrade the design.
+- **Restore after each round.** After feedback in interactive or SOLID mode,
+  restore each touched file with `git checkout -- <file>` for a byte-perfect
+  reset. If the file had pre-existing uncommitted changes (noted in step 0),
+  restore the original lines manually via `edit_file` instead and warn the user.
+- **Restore on session end.** When the session ends, check whether any files
+  still contain `# ... N lines removed ...` placeholders or deconstructed
+  code from interactive/SOLID/spec mode. If so, restore them with
+  `git checkout -- <file>` (or `edit_file` if pre-existing changes).
+- **Spec theme snapshot.** In interactive+spec mode, run `//snapshot on`
+  before file edits if the workspace is not a git repo. Run `//snapshot off`
+  after restoration.
+- **BA-Gates theme file safety.** In interactive+ba-gates mode for plaintext files (`.md`, `.feature`, `.txt`), the model MUST NOT edit the file — the user makes the changes. For office files (`.docx`, `.pptx`, `.xlsx`), present extracted text; the user describes fixes since they cannot edit binaries directly. Run `//snapshot on` before user edits in non-git workspaces; `//snapshot off` after.
+- **BA-Gates two-pass integrity.** Pass 1 regex results are filters only — do not present them as answers. Pass 2 LLM interpretation MUST run fresh per fragment at round time. If Pass 2 determines all regex flags are false positives, discard the fragment and select another. Do not fabricate issues.
+- **BA-Gates extraction fallback.** If `codewhale-doc-extract` fails for any office file, note it and skip that file — do not attempt alternative extraction methods. Report skipped files in discovery.
+- **BA-Gates thinking discipline.** Pass 2 analysis runs with Deep/High thinking. Once presentation begins, switch to Skip thinking — never include generated answers or gate locations in reasoning_content after the fragment is shown.
+
+## Verification
+
+After each round, confirm:
+- The snippet was actually read from the file (not hallucinated)
+- The line numbers match the source
+- The mode was correctly announced in the round header
+- The feedback accurately describes what the code does
+- No secrets or PII were exposed
+- The strike count was tracked correctly
+- (Interactive mode) The original lines were saved before the edit
+- (Interactive mode) The file was re-read before evaluating the user's restoration
+- (Interactive mode) Feedback accurately describes any differences from the original
+- (Interactive mode) Gapped files were restored or the user was offered restoration on session end
+- (SOLID mode) The original code was saved before deconstruction
+- (SOLID mode) The deconstructed code is functional (same behavior, just degraded design)
+- (SOLID mode) Anti-patterns were introduced deliberately — no accidental breakage
+- (SOLID mode) The number of anti-patterns was stated in the presentation
+- (SOLID mode) Individual anti-patterns were NOT annotated or revealed before evaluation
+- (SOLID mode) The file was re-read before evaluating the user's restoration
+- (SOLID mode) Deconstructed files were restored with `git checkout` on round end
+- (Spec theme) Office docs were scanned and extracted during discovery
+- (Spec theme) Exercise direction (spec→code or code→spec) was chosen randomly each round
+- (Spec theme) The trace link was verified in both directions by the model
+- (Spec theme) Interactive mode ran `//snapshot on/off` for non-git workspaces
+- (Spec theme) Modified files were restored after the round
+- (BA-Gates theme) BA documents were scanned across all formats (.docx, .pptx, .xlsx, .md, .feature, .txt)
+- (BA-Gates theme) `codewhale-doc-extract` was used for office files; failures noted and skipped
+- (BA-Gates theme) Pass 1 regex triage ran against every fragment; fragments with zero triggers excluded
+- (BA-Gates theme) Pass 2 LLM interpretation ran per fragment at round time with Deep/High thinking
+- (BA-Gates theme) Pass 2 verified quiz-worthiness before presentation; false positives discarded
+- (BA-Gates theme) The gate-count hint was stated but specific gates were NOT revealed before evaluation
+- (BA-Gates theme) On skip or strike-3, concrete domain-specific improvement options (2–3 per issue with best-fit recommendation and developer-impact summary) were presented
+- (BA-Gates theme) Interactive mode for plaintext files did NOT edit the file — user made changes
+- (BA-Gates theme) Interactive mode for office files presented extracted text inline — user described fixes
+- (BA-Gates theme) `//snapshot on/off` was used in interactive mode for non-git workspaces
+- (BA-Gates theme) Extraction fallback was handled gracefully — skipped files were reported
+- (BA-Gates theme) Thinking suppression was maintained — Pass 2 material was not leaked into reasoning after presentation