codewhale.history 2.10.1 → 2.11.1

package/README.md

@@ -21,6 +21,8 @@ tools_for_codewhale/
 ```
 
 ## Install
+### IMPORTANT
+If you already have codewhale.history installed in a folder and want to update to the lastest version in that folder, delete the .codewhale/instructions.md file before running `npm install -g codewhale.history`
 
 ```bash
 npm install -g codewhale.history
@@ -88,6 +90,7 @@ current project. Two independent dimensions across five difficulty levels:
 - **Standard** (default) — Code comprehension or line reconstruction.
 - **SOLID** (`teach me solid`) — Anti-pattern detection and design restoration.
 - **Spec** (`teach me spec`) — Spec-to-code traceability using office docs as source.
+- **BA-Gates** (`teach me ba`) — BA documentation quality analysis (ambiguity, AC completeness, edge case coverage).
 
 | Trigger | Response | Theme | What happens |
 |---------|----------|-------|-------------|
@@ -97,6 +100,8 @@ current project. Two independent dimensions across five difficulty levels:
 | `teach me solid interactive` | interactive | solid | Degraded code; you edit to fix it |
 | `teach me spec` | passive | spec | Spec or code presented; you trace the link |
 | `teach me spec interactive` | interactive | spec | Trace spec to code; you edit code to match |
+| `teach me ba` | passive | ba-gates | BA doc fragment; you identify quality gate violations |
+| `teach me ba interactive` | interactive | ba-gates | BA doc with issues; you edit to fix them |
 
 **Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
 `drill me`
@@ -110,6 +115,7 @@ current project. Two independent dimensions across five difficulty levels:
 | Response | `teach me interactive` | Edit the file instead of describing |
 | Theme | `teach me solid` | Anti-pattern detection — fix degraded design |
 | Theme | `teach me spec` | Spec-to-code traceability via office docs |
+| Theme | `teach me ba` | BA documentation quality analysis |
 | Scope | `teach me services/` | Narrow to a specific file or folder |
 | Concept | `teach me decorators` | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |
 
@@ -125,7 +131,7 @@ current project. Two independent dimensions across five difficulty levels:
 
 **Mid-round commands:** `hint` (get a nudge) · `skip` (see the answer) ·
 `next` (draw a new snippet) · `level N` · `easier` · `harder` ·
-`interactive` · `passive` · `solid` · `spec` · `done` (verify work) · `stop`
+`interactive` · `passive` · `solid` · `spec` · `ba` · `done` (verify work) · `stop`
 
 **At the end** you get a session summary: rounds completed, mode, files covered,
 what you're strong on, what to review, and a suggested next level.
@@ -142,6 +148,17 @@ spec?" or "what spec does this code satisfy?" — testing whether you truly
 understand how requirements map to implementation. In interactive mode, you
 edit the code to satisfy the spec; in passive mode, you describe the link.
 
+In **BA-Gates theme**: the model runs a two-pass analysis over your BA documentation
+files (`.docx`, `.pptx`, `.xlsx`, `.md`, `.feature`, `.txt`). Pass 1 uses regex
+triage to flag fragments against three quality gates — **Ambiguity**
+(unmeasurable terms, passive states), **Acceptance Criteria Completeness**
+(missing structure, unverifiable outcomes), and **Edge Case Coverage** (missing
+negative scenarios, error states). Pass 2 runs an LLM interpretation per
+fragment at round time to generate quiz material and concrete improvement
+options. You identify which gates a fragment triggers and describe the developer
+impact. On skip or strike-3, the model presents 2–3 domain-specific rewrites per
+issue with a best-fit recommendation.
+
 ## Requirements
 - Node.js (for the `codewhale-history` command)
 - [CodeWhale](https://codewhale.net/en/docs)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codewhale.history",
-  "version": "2.10.1",
+  "version": "2.11.1",
   "description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
   "bin": {
     "codewhale-history": "./_list_sessions.js",

package/skills/teach-me/SKILL.md

@@ -1,23 +1,28 @@
 ---
 name: teach-me
-description: Interactive code-teaching quiz. Selects random snippets from the current project and quizzes the user on application logic and language semantics. Triggered by 'teach me', 'quiz me', 'test my knowledge', 'code quiz', or 'drill me'. Supports difficulty levels 1–5 and three modes: passive (explain), interactive (reconstruct), and solid (anti-pattern detection).
+description: Interactive code-teaching quiz. Selects random snippets from the current project and quizzes the user on application logic, language semantics, or BA documentation quality. Triggered by 'teach me', 'quiz me', 'test my knowledge', 'code quiz', or 'drill me'. Supports difficulty levels 1–5 and four themes: passive (explain), interactive (reconstruct), solid (anti-pattern detection), spec (spec-to-code traceability), and ba-gates (BA documentation quality analysis).
 ---
 
 # Teach Me — Interactive Code Quiz
 
-An interactive teaching session that randomly selects code snippets from the
+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`):
+**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 |
 |---------|----------|-------|-------------|
@@ -27,6 +32,8 @@ current project. Two independent dimensions combine to form each exercise:
 | `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.
@@ -54,13 +61,18 @@ Optionally followed by modifiers:
 - `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 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.
@@ -423,13 +435,345 @@ 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] | `path/to/file.py` (lines A–B)
+## Round N — Level X · [passive|interactive] · [concept|solid|spec|ba-gates] | `path/to/file.py` (lines A–B)
 
 ```python
  42  def calculate_position_size(
@@ -459,7 +803,7 @@ Guidelines:
 - 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, or `· decorators` etc. for targeted concept) appears when applicable; omit during free-play standard rounds
+- 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,
@@ -580,6 +924,19 @@ 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
@@ -632,7 +989,7 @@ If the user's answer **meets** expectations (any attempt):
 - Reveal the file context
 - Ask "Another round?"
 
-#### Feedback structure (success or strike-3)
+#### Feedback structure (success or strike-3 — standard/spec modes)
 
 ```
 **What you got right:**
@@ -648,12 +1005,23 @@ 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. Move to next round. |
+| `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). |
@@ -662,13 +1030,14 @@ nailed everything at-level, say so and highlight the nuance they caught.
 | `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. |
-| `done` / `check my work` | (Interactive/SOLID/Spec mode) Signal that work is complete. Triggers verification. |
+| `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 / stop)"
+"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:
@@ -694,6 +1063,22 @@ 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>`
@@ -742,6 +1127,10 @@ criteria for the Mechanics axis:
 - **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
 
@@ -768,3 +1157,15 @@ After each round, confirm:
 - (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