@event4u/agent-config 1.9.1

package/.agent-src/commands/review-changes.md

@@ -0,0 +1,130 @@
+---
+name: review-changes
+skills: [code-review, subagent-orchestration, judge-bug-hunter, judge-security-auditor, judge-test-coverage, judge-code-quality]
+description: Self-review local changes before creating a PR — dispatches to four specialized judges (bug, security, tests, quality) and consolidates verdicts
+disable-model-invocation: true
+---
+
+# review-changes
+
+## Instructions
+
+Review all uncommitted and committed-but-not-pushed changes against
+the default branch (`main`) by dispatching to four specialized judge
+sub-skills and consolidating their verdicts.
+
+### 1. Gather the diff
+
+- `git diff origin/main..HEAD --stat` — overview of changed files
+- `git diff origin/main..HEAD` — full committed-but-not-pushed diff
+- `git diff --stat` + `git diff` — unstaged changes on top
+
+If both diffs are empty, **stop** — nothing to review.
+
+### 2. Resolve the judge model
+
+Read `.agent-settings.yml`:
+
+- `subagents.judge_model` → empty = one tier above the session model
+
+Unknown alias → stop. Never silently fall back.
+
+### 3. Dispatch to the four judges
+
+Each judge receives **the same diff plus the task context** (ticket,
+PR body, commit messages) and runs independently. The judges are:
+
+| Sub-skill | Focus |
+|---|---|
+| [`judge-bug-hunter`](../skills/judge-bug-hunter/SKILL.md) | Correctness, null-safety, edge cases, races, error handling |
+| [`judge-security-auditor`](../skills/judge-security-auditor/SKILL.md) | AuthZ/AuthN, injection, secrets, unsafe deserialization, SSRF, XSS |
+| [`judge-test-coverage`](../skills/judge-test-coverage/SKILL.md) | Missing assertions, uncovered branches, over-mocking, regression-test gaps |
+| [`judge-code-quality`](../skills/judge-code-quality/SKILL.md) | Naming, SRP, DRY, dead code, consistency with codebase conventions |
+
+Pick dispatch mode based on diff size and environment:
+
+- **Sequential** (default, simplest) — run bug-hunter → security-auditor
+  → test-coverage → code-quality, collect each verdict
+- **Parallel** — if `subagents.max_parallel` in `.agent-settings.yml` is
+  ≥ 4 and subagent dispatch is available, run all four concurrently
+  following the `do-in-parallel` pattern in
+  [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md);
+  the four judges operate on the same diff but produce independent
+  reports, so no shared-state risk
+
+Each judge returns its own `Judge / Model / Target / Verdict /
+Issues` block in the format defined by that skill.
+
+### 4. Consolidate
+
+Produce one combined report:
+
+- List each judge's verdict side by side
+- Merge issues into a single severity-sorted table (🔴 → 🟡 → 🟢),
+  tagged with the judge that raised each one
+- Highlight any finding that multiple judges flagged — those are the
+  highest-confidence items
+
+### 5. Decide next steps
+
+- If **any** judge returned `reject` → stop; the approach must change
+  before proceeding
+- If **any** judge returned `revise` → fix 🔴 findings automatically,
+  ask before fixing 🟡 findings, report 🟢 as suggestions
+- If all four returned `apply` → the diff is ready; report and stop
+
+### 6. Quality tools (optional)
+
+After the consolidated report, ask:
+
+```
+> 1. Yes — run quality tools (formatter, static analyzer, linters)
+> 2. No — review done
+```
+
+If yes, hand off to the project's quality workflow (e.g. `/quality-fix`
+or the equivalent configured command).
+
+## Backward compatibility
+
+- Invocation is unchanged: `/review-changes` with no arguments still
+  reviews the full uncommitted-plus-committed-not-pushed diff
+- A user who invokes `/review-changes` on a diff that has no test
+  files still gets coverage feedback — `judge-test-coverage` treats
+  "production changed, no test changed" as its primary finding
+- Project-specific syntax checks (e.g. `php -l`, linter pre-pass) are
+  out of scope for the judges and belong in the optional step 6
+  quality tools hand-off
+
+## Use this command when
+
+- Preparing a self-review before opening a PR
+- Stress-testing a local branch with the same four lenses a reviewer
+  would apply
+- Sanity-checking a diff before handing it to `/create-pr`
+
+## Do NOT
+
+- NEVER apply fixes without showing the consolidated report first
+- NEVER skip a judge because the diff "looks fine" — each judge must
+  produce its own verdict
+- NEVER merge two judges' outputs into a single block — the user
+  needs to see which lens raised each finding
+- NEVER commit or push from this command — review only
+- NEVER run on an empty diff; fail fast
+
+## See also
+
+- [`subagent-orchestration`](../skills/subagent-orchestration/SKILL.md) — dispatch and model-pairing rules
+- [`/do-and-judge`](do-and-judge.md) — implementer + judge loop for a single change
+- [`/judge`](judge.md) — standalone judge, no review-changes dispatch
+- [`code-review`](../skills/code-review/SKILL.md) — human-oriented review patterns (tone, feedback handling)
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#reviewer) — Reviewer mode output contract (Summary / Risks / Findings / Required actions / Verdict)
+
+## References
+
+- **LLM-as-a-Judge** — [arxiv.org/abs/2306.05685](https://arxiv.org/abs/2306.05685)
+  MT-Bench and Chatbot Arena — judging LLM outputs with LLM judges.
+  This command adapts the pattern by dispatching to four specialized
+  judges (bug, security, tests, quality) instead of a single generic
+  judge, and consolidating their verdicts.

package/.agent-src/commands/review-routing.md

@@ -0,0 +1,111 @@
+---
+name: review-routing
+skills: [review-routing, reviewer-awareness, review-routing-awareness]
+description: Compute reviewer roles and matched historical bug patterns for the current diff, using project-local ownership-map.yml and historical-bug-patterns.yml
+disable-model-invocation: true
+---
+
+# review-routing
+
+## Instructions
+
+Produce a review-routing block for the current diff — owner-mapped
+reviewer roles plus any matched historical bug patterns — so the author
+knows *who* to request and *what* to test before opening a PR.
+
+Dispatches to [`review-routing`](../skills/review-routing/SKILL.md) for
+the core resolution logic. The rules
+[`reviewer-awareness`](../rules/reviewer-awareness.md) and
+[`review-routing-awareness`](../rules/review-routing-awareness.md) govern
+the output format and data handling.
+
+### 1. Gather the diff
+
+- **Default** — use `git diff --name-only origin/main...HEAD` (or the
+  configured trunk branch from `.agent-settings.yml`).
+- **Explicit** — if the user provides a base and head ref, honour them.
+- **Empty diff** — stop with _"no changes, routing skipped"_.
+
+### 2. Dispatch to the skill
+
+Invoke [`review-routing`](../skills/review-routing/SKILL.md) with the
+changed-file list. The skill:
+
+1. Loads `ownership-map.yml` and `historical-bug-patterns.yml` (both
+   optional, package-agnostic paths).
+2. Matches every file against ownership globs (first match wins).
+3. Walks every pattern against the diff.
+4. Computes overall severity (`high` wins).
+5. Returns the structured block.
+
+If neither data file exists, the skill returns the generic fallback
+from [`reviewer-awareness`](../rules/reviewer-awareness.md). That is
+valid output — do not invent owners.
+
+### 3. Present the result
+
+Paste the skill's structured block verbatim under a short header:
+
+```
+## Review Routing (from project data)
+```
+
+Append, if present:
+
+- **Staleness warning** — ownership map > 6 months old.
+- **Required tests** — extracted from matched historical patterns, as a
+  follow-up checklist the author must honour before claiming completion
+  ([`verify-before-complete`](../rules/verify-before-complete.md)).
+
+### 4. Decide next step
+
+After the block, ask:
+
+```
+> 1. Add this routing block to my PR description
+> 2. Request these reviewers now (via gh / GitLab CLI)
+> 3. Re-run after I update the ownership map
+> 4. Stop here — routing block is the deliverable
+```
+
+- On **1**: hand off to
+  [`create-pr-description`](../skills/create-pr-description/SKILL.md).
+- On **2**: respect CODEOWNERS — request the *roles* resolved to people
+  by the consumer's own mapping, never invent usernames.
+- On **3**: the user wants to curate the map first. Stop.
+- On **4**: save the block, stop.
+
+## Use this command when
+
+- About to open a PR and unsure who should review it.
+- Preparing a PR description and want owner-mapped reviewers in it.
+- Running a sanity check against historical patterns before claiming
+  completion.
+- CI needs the routing block for a sticky PR comment.
+
+## Do NOT
+
+- NEVER invent owners for paths not in the ownership map — use the
+  generic fallback and say so.
+- NEVER emit individual GitHub usernames in the routing block; the
+  block contains **roles**, CODEOWNERS contains **people**.
+- NEVER downgrade a historical-pattern match because "the author said
+  it's fine" — pattern severity is set in the YAML, not negotiated per
+  PR.
+- NEVER modify `ownership-map.yml` or `historical-bug-patterns.yml` as
+  a side effect of this command.
+- NEVER run this command on a PR with zero changed files — it produces
+  meaningless noise.
+
+## See also
+
+- [`review-routing`](../skills/review-routing/SKILL.md) — the resolver
+- [`reviewer-awareness`](../rules/reviewer-awareness.md) — role vocabulary
+- [`review-routing-awareness`](../rules/review-routing-awareness.md) —
+  data-source rules
+- [`review-routing-data-format`](../guidelines/agent-infra/review-routing-data-format.md)
+  — YAML schemas
+- [`create-pr-description`](../skills/create-pr-description/SKILL.md) —
+  consumes the routing block
+- [`verify-before-complete`](../rules/verify-before-complete.md) —
+  consumes the `required_test` list

package/.agent-src/commands/roadmap-create.md

@@ -0,0 +1,110 @@
+---
+name: roadmap-create
+skills: [agent-docs-writing]
+description: Interactively create a new roadmap file in agents/roadmaps/
+disable-model-invocation: true
+---
+
+# roadmap-create
+
+## Instructions
+
+### 1. Determine location
+
+Ask the user (in their language) where the roadmap should be created:
+
+> 1. Project root (`agents/roadmaps/`)
+> 2. In a module (`app/Modules/{Name}/agents/roadmaps/`)
+
+If the user picks a module → ask which module (list available modules if needed).
+Create the `agents/roadmaps/` directory if it doesn't exist at the chosen location.
+
+### 2. Read the roadmap template
+
+- Read `.augment/templates/roadmaps.md` for the roadmap structure.
+- Use its structure as the basis for the new roadmap.
+
+### 3. Gather content interactively
+
+Ask the user (in their language) step by step:
+
+1. **Title / goal**: What is the goal of this roadmap? (one sentence)
+2. **Context**: What context is important? (module, affected classes, Jira tickets, etc.)
+3. **Phases**: What phases does the roadmap have? (e.g. "Phase 1: Preparation, Phase 2: Migration, Phase 3: Cleanup")
+4. For each phase → What steps belong in Phase {N}?
+
+After each input, show what you've captured and ask the user (in their language) to confirm or adjust.
+
+**Important:** The user may answer in any language, but the roadmap file must be written in **English**.
+Translate user input to English when writing the file.
+
+### 4. Build the roadmap file
+
+Use the template structure:
+
+```markdown
+# Roadmap: {title}
+
+> {One sentence goal}
+
+## Prerequisites
+
+- [ ] Read `AGENTS.md` and relevant module docs
+- [ ] {any specific prerequisites}
+
+## Context
+
+{Context from user input}
+
+## Phase 1: {name}
+
+- [ ] **Step 1:** {description}
+- [ ] **Step 2:** {description}
+- [ ] ...
+
+## Phase 2: {name}
+
+- [ ] **Step 1:** {description}
+- [ ] ...
+
+## Acceptance Criteria
+
+- [ ] {criteria}
+- [ ] All quality gates pass (PHPStan, Rector, tests)
+
+## Notes
+
+{Optional notes}
+```
+
+### 5. Review loop
+
+Show the complete roadmap to the user and ask (in their language) if anything should be added or changed.
+
+- If yes → apply changes, show again.
+- Repeat until the user says it's done.
+
+### 6. Save the file
+
+- Generate a filename from the title: kebab-case, e.g. `optimize-webhook-jobs.md`.
+- Save to the chosen location.
+- Show the final path.
+
+### 7. Update the progress dashboard
+
+Run `task roadmap-progress` so the new roadmap shows up in
+`agents/roadmaps-progress.md`. Mention the new overall count to the user.
+
+### 8. Offer execution
+
+After saving, ask the user (in their language) whether to start executing the roadmap immediately.
+
+If yes → switch to the `roadmap-execute` command workflow with the newly created file.
+
+### Rules
+
+- **Do NOT auto-generate content** — always ask the user for input.
+- **Do NOT commit or push.**
+- **Write the roadmap in English** (per project convention for `.md` files).
+- Follow the roadmap template from `.augment/templates/roadmaps.md`.
+- Keep the file focused: 500–1000 lines max. If larger, suggest splitting.

package/.agent-src/commands/roadmap-execute.md

@@ -0,0 +1,68 @@
+---
+name: roadmap-execute
+skills: [agent-docs-writing]
+description: Read and interactively execute a roadmap from agents/roadmaps/
+disable-model-invocation: true
+---
+
+# roadmap-execute
+
+## Instructions
+
+### 1. Find the roadmap
+
+- List all roadmap files: `agents/roadmaps/*.md` (project root) and `app/Modules/*/agents/roadmaps/*.md` (modules).
+- Exclude `template.md`.
+- If only one roadmap exists → use it (confirm with user).
+- If multiple exist → present a numbered list and let the user choose.
+- If none exist → tell the user and suggest running `roadmap-create`.
+
+### 2. Read and understand the roadmap
+
+- Read the full roadmap file.
+- Identify the **phases** and **steps/tasks** within each phase.
+- Determine which steps are already completed (look for checkboxes `[x]`, status markers, or "done" notes).
+- Present a summary to the user:
+  > "Roadmap: {title}"
+  > "Phase 1: {name} — 3/5 Schritte erledigt"
+  > "Phase 2: {name} — noch nicht begonnen"
+  > "Next open step: {step description}"
+
+### 3. Execute step by step
+
+For each open step:
+
+1. **Summarize** what needs to be done (in the user's language).
+2. **Analyze** the codebase to understand what's needed for this step.
+3. **Present a plan** — what files to change, what approach to take.
+4. **Ask for confirmation**: "Should I implement this step?"
+   - If yes → implement, run quality checks, mark step as done in the roadmap file.
+   - If no / skip → move to the next step.
+   - If the user wants to stop → stop and summarize progress.
+
+### 4. After each step
+
+- Update the roadmap file: mark the completed step (e.g. `[x]` or add a completion note).
+- Run quality tools if code was changed (PHPStan at minimum).
+- Run `task roadmap-progress` so `agents/roadmaps-progress.md` reflects the new state.
+- Ask: "Continue with the next step?"
+
+### 5. After all steps in a phase
+
+- Summarize what was accomplished in the phase.
+- Ask: "Phase {N} complete. Continue with Phase {N+1}?"
+
+### 6. When done (or stopped)
+
+- Summarize total progress: steps completed, steps remaining.
+- Update the roadmap file with the current status.
+- Run `task roadmap-progress` one last time so the dashboard matches the final state.
+- **If ALL steps are done** → trigger the completion & archiving workflow from the `roadmap-management` skill.
+
+### Rules
+
+- **Do NOT commit or push** — only apply local changes and update the roadmap file.
+- **Always ask before implementing** a step — never auto-execute.
+- **Run quality checks** after each code change.
+- If a step is unclear or too large, suggest breaking it down further.
+- If a step reveals a problem not covered in the roadmap, flag it to the user.

package/.agent-src/commands/rule-compliance-audit.md

@@ -0,0 +1,139 @@
+---
+name: rule-compliance-audit
+description: Audit rule trigger quality, simulate activation, detect overlaps, and find never-activating rules
+disable-model-invocation: true
+---
+
+# rule-compliance-audit
+
+## Instructions
+
+### 1. Inventory all rules
+
+Read every `.md` file in `.agent-src.uncompressed/rules/`. For each rule, extract:
+
+- **Name** (filename without `.md`)
+- **Type** (`always` or `auto`)
+- **alwaysApply** (`true` or `false`)
+- **Description** (the trigger description)
+
+Display:
+
+```
+═══════════════════════════════════════════════
+  🔍 RULE COMPLIANCE AUDIT
+═══════════════════════════════════════════════
+
+  Rules: {total} ({always_count} always, {auto_count} auto)
+```
+
+### 2. Trigger quality check (auto-rules only)
+
+For each auto-rule, evaluate the `description` field:
+
+**Strong trigger** ✅ — contains:
+- Specific keywords a user would type (e.g., "PHPStan", "commit", "Docker")
+- Concrete action verbs (e.g., "creating", "editing", "running")
+- Specific file types or paths (e.g., ".augment/", "Blade views")
+
+**Weak trigger** ⚠️ — has ANY of:
+- Only abstract nouns ("quality", "best practices", "patterns")
+- No concrete keywords that match user prompts
+- Overlaps significantly with another rule's description
+- Too broad ("when working with code")
+
+Display per rule:
+
+```
+  ✅  {name}: "{description}" — keywords: {extracted keywords}
+  ⚠️  {name}: "{description}" — WEAK: {reason}
+```
+
+### 3. Trigger simulation
+
+For each auto-rule, generate **3 realistic user prompts** that SHOULD activate the rule.
+Then check: does the description contain enough keywords to match?
+
+Display:
+
+```
+───────────────────────────────────────────────
+TRIGGER SIMULATION
+───────────────────────────────────────────────
+
+  {rule-name}:
+    Description: "{description}"
+    Test prompts:
+      1. "{prompt}" → {✅ would match | ⚠️ might miss}
+      2. "{prompt}" → {✅ would match | ⚠️ might miss}
+      3. "{prompt}" → {✅ would match | ⚠️ might miss}
+```
+
+Only show rules where at least 1 prompt might miss.
+
+### 4. Overlap detection
+
+Compare all rule descriptions pairwise. Flag pairs where:
+- >50% keyword overlap
+- Same domain but different scope (one should be merged or narrowed)
+
+```
+───────────────────────────────────────────────
+OVERLAP ANALYSIS
+───────────────────────────────────────────────
+
+  ⚠️  {rule-a} ↔ {rule-b}: overlapping keywords: {list}
+     Recommendation: {merge | narrow scope | keep separate because...}
+```
+
+If no overlaps found: `✅  No significant overlaps detected.`
+
+### 5. Always-rule health check
+
+For each always-rule, check:
+- **Size** — >100 lines = ⚠️ (token cost on every request)
+- **Specificity** — does it apply to ALL tasks? If not, should it be auto instead?
+
+```
+───────────────────────────────────────────────
+ALWAYS-RULE HEALTH
+───────────────────────────────────────────────
+
+  {name}: {line_count} lines — {✅ healthy | ⚠️ large (>100 lines) | ⚠️ could be auto}
+```
+
+### 6. Summary and recommendations
+
+```
+═══════════════════════════════════════════════
+  📊 AUDIT SUMMARY
+═══════════════════════════════════════════════
+
+  Total rules:        {total}
+  Strong triggers:    {count} ✅
+  Weak triggers:      {count} ⚠️
+  Overlapping pairs:  {count}
+  Large always-rules: {count}
+
+  Recommendations:
+  {numbered list of concrete actions}
+```
+
+Present recommendations as numbered options:
+
+```
+> 1. Fix weak trigger: {rule} — suggested description: "{improved}"
+> 2. Narrow overlap: {rule-a} vs {rule-b} — {action}
+> 3. Convert to auto: {rule} — only applies to {specific context}
+> 4. No changes needed ✅
+```
+
+Wait for user to pick which recommendations to apply.
+
+## Rules
+
+- **Do NOT modify any files** until the user approves recommendations.
+- **Do NOT run any scripts** — this is a pure analysis command.
+- **Be honest about uncertainty** — if a trigger might or might not match, say "might miss".
+- **Always-rules are expensive** — flag any that could safely be auto.
+- **Auto-rules that never activate are dead weight** — flag them clearly.

package/.agent-src/commands/tests-create.md

@@ -0,0 +1,73 @@
+---
+name: tests-create
+skills: [pest-testing]
+description: Write meaningful tests for the changes in the current branch
+disable-model-invocation: true
+---
+
+# tests-create
+
+## Instructions
+
+### 1. Detect the test framework
+
+- Check if **Pest** is installed: look for `pestphp/pest` in `composer.json` or `vendor/bin/pest`.
+    - If Pest is available → write **Pest tests**.
+- If Pest is not installed → write **PHPUnit tests**.
+- Check existing tests in the project (`tests/` directory) to match the style and conventions already in use.
+
+### 2. Identify what changed
+
+- Run `git diff origin/main..HEAD --name-only` or `git diff origin/master..HEAD --name-only` (depending on project) to get all changed
+  files.
+- Focus on **PHP files with business logic** — skip config files, migrations, views, etc.
+- Read each changed file and understand what was added or modified.
+
+### 3. Understand the code before writing tests
+
+- Use `codebase-retrieval` to understand the classes, their dependencies, and how they're used.
+- Read existing tests for the same or related classes to match patterns.
+- Understand what the method is supposed to do, not just what it does.
+
+### 4. Write meaningful tests
+
+**DO write tests that:**
+
+- Test the **actual business logic** and expected behavior.
+- Cover **edge cases**: null values, empty strings, boundary values, invalid input.
+- Test **error handling**: what happens when things go wrong?
+- Test **different code paths**: if/else branches, early returns, fallback behavior.
+- Verify **return values and side effects** that matter.
+- Use descriptive test names that explain the scenario (e.g. `it returns fallback status when input is empty`).
+
+**Do NOT write tests that:**
+
+- Assert trivial things like parameter count, method existence, or class name.
+- Just repeat the implementation as assertions (testing that `1+1` returns `2` when the code literally does `1+1`).
+- Test framework internals or getter/setter boilerplate.
+- Test private methods directly — test through the public API.
+- Have no real assertion value (e.g. "it does not throw" without meaningful setup).
+
+### 5. Test structure
+
+- One test file per class/service being tested.
+- Place tests in the matching directory structure under `tests/` (mirror the source structure).
+- Group related tests with `describe` blocks (Pest) or separate test methods (PHPUnit).
+- Use data providers for testing multiple input/output combinations.
+- Mock external dependencies (database, HTTP, file system) — don't test infrastructure.
+
+### 6. Verify
+
+- Run the tests locally in the PHP container to make sure they pass.
+- If a test fails, fix it — don't just delete it.
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Quality over quantity** — 5 meaningful tests beat 20 trivial ones.
+- If a class is hard to test (too many dependencies, global state), flag it and suggest a refactoring approach instead of writing brittle
+  tests.
+
+## See also
+
+- [`role-contracts`](../guidelines/agent-infra/role-contracts.md#tester) — Tester mode output contract (Behaviour under test / Edge cases / Negative paths / Reproduction / Coverage gaps)

package/.agent-src/commands/tests-execute.md

@@ -0,0 +1,58 @@
+---
+name: tests-execute
+skills: [pest-testing]
+description: Run PHP tests inside the Docker container
+disable-model-invocation: true
+---
+
+# tests-execute
+
+## Instructions
+
+### 1. Detect the test runner
+
+Check in this order — use the **first match**:
+
+1. **Makefile** exists → look for test targets (`make test`, `make test-unit`, etc.)
+2. **Taskfile.yml** exists → look for test tasks (`task test`, `task test-unit`, etc.)
+3. **`artisan` exists** → Laravel project → `php artisan test`
+4. **`vendor/bin/pest` exists** → Pest → `vendor/bin/pest`
+5. **Fallback** → PHPUnit → `vendor/bin/phpunit`
+
+**Prefer Makefile/Taskfile targets** over raw commands — they handle container access,
+environment variables, and parallel settings automatically.
+
+### 2. Run the tests
+
+- If using Makefile/Taskfile targets → run from host (they handle Docker internally).
+- If using raw commands → execute **inside the PHP Docker container** (`docker compose exec -T <service> ...`).
+  Detect the PHP service name from `docker-compose.yml` / `compose.yaml` (see `rules/docker-commands.md`).
+- If the user provided a specific test file or filter, pass it through:
+  - Pest/Artisan: `--filter="test name"` or `tests/path/to/TestFile.php`
+  - PHPUnit: `--filter="test name"` or `tests/path/to/TestFile.php`
+- If no specific test is requested, run the full test suite.
+
+### 3. Analyze results
+
+- If all tests pass → report success with a short summary.
+- If tests fail:
+  - Show the failing test name, expected vs actual values, and the relevant code.
+  - Analyze the failure — is it a bug in the code or a bug in the test?
+  - **Ask the user** with numbered options:
+    ```
+    > 1. Fix the code — the test is correct
+    > 2. Fix the test — the code is correct
+    > 3. Skip — I'll handle this myself
+    ```
+  - If the user says fix it, apply the fix and re-run.
+
+### 4. Re-run until green
+
+- After any fix, re-run the failing tests to verify.
+- Repeat until all tests pass.
+
+### Rules
+
+- **Do NOT commit or push.**
+- **Always ask before changing test assertions** — the test might be correct and the code wrong.
+- If tests are slow (>2 min), suggest running only the affected test file instead of the full suite.