agent-bober 0.11.6 → 0.15.0

package/skills/bober.code-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: bober-code-review
+description: Use when completing a sprint, after evaluator pass — spawns bober-code-reviewer subagent to audit the sprint diff against the contract and anti-pattern catalog, producing an advisory ReviewResult written to .bober/reviews/<contractId>-review.md.
+argument-hint: "[contract-id]"
+---
+
+> Adapted from [obra/superpowers](https://github.com/obra/superpowers) — MIT License.
+> Original: skills/requesting-code-review/.
+> Adaptations: agent name (bober-code-reviewer), advisory-only contract, ReviewResult JSON schema, anti-pattern citations from .bober/anti-patterns/.
+
+# bober.code-review — Advisory Code Review Orchestrator
+
+You are the **orchestrator** for a standalone code review run. You do NOT review the code yourself. You spawn the code reviewer as a subagent using the **Agent tool**, then process and save its results to `.bober/reviews/<contractId>-review.md`.
+
+The code reviewer subagent runs in its own isolated context window. It receives ONLY the information you explicitly pass in its prompt.
+
+**Integration with bober pipeline:** In the automated pipeline, bober-code-reviewer is spawned automatically after `runEvaluatorAgent` returns `passed: true` in `src/orchestrator/pipeline.ts`. This skill is for standalone runs — when you want to trigger a review manually outside the normal pipeline flow.
+
+## When to Request Review
+
+**Mandatory in pipeline:** The orchestrator triggers code review automatically after each sprint evaluator pass. You do not need to invoke this skill for normal pipeline runs.
+
+**Use this skill manually when:**
+- You completed a sprint manually (outside the pipeline) and want advisory feedback
+- You want to re-review a sprint with a different anti-pattern focus
+- You want to review a specific file range that the pipeline did not cover
+
+## What the Reviewer Checks
+
+**What to check — findings the reviewer WILL surface:**
+
+- **DRY violations**: New code that duplicates an existing utility verbatim. Cite the duplicate location with file:line evidence.
+- **YAGNI violations**: Abstractions added for future use cases not in the contract. Config options wired but never read.
+- **Dead code**: Functions defined but never called; exports with zero import sites in the diff.
+- **Missing tests**: Changed behavior with no new test coverage; tests that only check the happy path.
+- **Anti-pattern matches** from `.bober/anti-patterns/`:
+  - Testing Mock Behavior, Test-Only Methods in Production → `.bober/anti-patterns/testing-anti-patterns.md`
+  - Arbitrary-delay waiting (`setTimeout`/`sleep`) → `.bober/anti-patterns/condition-based-waiting.md`
+  - Symptom-fix instead of root-cause → `.bober/anti-patterns/root-cause-tracing.md`
+  - Single-layer validation (missing defense-in-depth) → `.bober/anti-patterns/defense-in-depth.md`
+- **Silent error swallowing**: `catch {}` with no log or rethrow; errors absorbed without surfacing
+- **TypeScript `any` types** without a comment explaining why
+
+**What NOT to flag — the reviewer MUST drop these:**
+
+- Style preferences (indentation, line length, trailing commas when file is internally consistent)
+- Naming opinions when the name is consistent with the surrounding file
+- Theoretical risks without an observed trigger (speculation without evidence)
+- Decisions the planner already resolved — re-litigating settled choices is scope creep
+- Pre-existing code that was NOT changed in this sprint
+
+## Acting on Feedback
+
+Because the review is advisory (it never blocks sprint completion), severity signals what to do NEXT:
+
+- **Critical**: Warrants a dedicated fix sprint. The finding has file:line evidence and an observed trigger. Prioritize addressing this before the next feature sprint.
+- **Important**: Address before shipping this feature broadly. Worth tracking in the backlog.
+- **Minor**: Note for future housekeeping. Do not delay other work for these.
+
+Even Critical findings do NOT trigger a generator retry. The sprint is complete. The review surfaces information for planning the next sprint.
+
+## Process Flow
+
+### Step 1: Identify the Target Contract
+
+**If a contract ID was provided as an argument:**
+- Load the contract from `.bober/contracts/<contractId>.json`
+- Verify the contract status is `passed` — review runs after evaluator pass
+
+**If no contract ID was provided:**
+- Find the most recently passed contract from `.bober/contracts/`
+- If no passed contracts exist, tell the user there is nothing to review
+
+Read the contract and its parent PlanSpec.
+
+### Step 2: Gather Context
+
+Read `bober.config.json` for commands and evaluator config.
+Read `.bober/principles.md` if it exists.
+
+Check the git status:
+```bash
+git log --oneline -5
+git diff HEAD~1 --stat
+```
+
+### Step 3: Spawn the Code Reviewer Subagent
+
+Use the **Agent tool** to spawn a code reviewer subagent.
+
+```
+Agent tool call:
+  description: "Code Review: <sprint title>"
+  subagent_type: bober-code-reviewer
+  mode: auto
+  prompt: <the full prompt below>
+```
+
+**Build the reviewer prompt with ALL of these sections:**
+
+```
+You are the Bober Code Reviewer subagent. You have been spawned to advisory-review a sprint that already passed evaluation.
+
+## Sprint Contract
+<paste the full SprintContract JSON from .bober/contracts/<contractId>.json>
+
+## Evaluation Result (Already Passed)
+<paste the EvaluationRunResult JSON — key fields: passed: true, summary, score>
+
+## Project Configuration
+Commands:
+<paste the commands section from bober.config.json>
+
+## Project Root
+<absolute path to the project root>
+
+## Context
+- Contract ID: <contractId>
+- Spec ID: <specId>
+- Review is ADVISORY ONLY — findings do not block completion or trigger retries
+
+## Anti-Pattern Catalog
+The catalog index is at .bober/anti-patterns/README.md. Consult it BEFORE classifying severity.
+Catalogued anti-patterns:
+- Testing anti-patterns → .bober/anti-patterns/testing-anti-patterns.md
+- Condition-based waiting → .bober/anti-patterns/condition-based-waiting.md
+- Root-cause tracing → .bober/anti-patterns/root-cause-tracing.md
+- Defense in depth → .bober/anti-patterns/defense-in-depth.md
+
+## Your Task
+Review the sprint diff. Produce a ReviewResult JSON. Output ONLY the JSON — no text outside it.
+```
+
+### Step 4: Process and Save the Result
+
+When the subagent returns:
+
+1. Parse the ReviewResult JSON from its response
+2. Render the markdown review document (6 required sections):
+
+```markdown
+# Code Review: <contractId>
+
+## Summary
+
+<paste summary field>
+
+## Critical
+
+<for each finding in critical array: description + evidence>
+<if empty: "No critical findings.">
+
+## Important
+
+<for each finding in important array>
+<if empty: "No important findings.">
+
+## Minor
+
+<for each finding in minor array>
+<if empty: "No minor findings.">
+
+## Approved Areas
+
+<for each item in approvedAreas: bullet>
+<if empty: "No areas specifically called out.">
+```
+
+3. Save to `.bober/reviews/<contractId>-review.md`
+4. Report a summary to the user: counts of critical/important/minor findings
+
+## Red Flags - STOP
+
+- About to spawn the reviewer before checking that the sprint status is `passed`
+- About to save a review for a contract that never passed evaluation
+- About to treat Critical findings as blocking (they are advisory — the sprint is done)
+- About to skip reading `.bober/anti-patterns/README.md` before the reviewer prompt
+
+## Rationalization Prevention
+
+| Excuse | Reality |
+|--------|---------|
+| "The sprint passed, so there is nothing to review" | Passing evaluation is a correctness bar, not a quality bar. Code review adds a separate signal. |
+| "Critical findings mean I should trigger a rework" | No. Advisory means advisory. The sprint is complete. Plan a fix sprint if needed. |
+| "The reviewer ran out of context — I will skip saving the file" | Save what you have. An empty review with just a Summary is better than no record. |
+| "Different words so rule doesn't apply" | Spirit over letter. |

package/skills/bober.debug/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: bober-debug
+description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes
+---
+
+> Verbatim port from [obra/superpowers](https://github.com/obra/superpowers) — MIT License.
+> Original: skills/systematic-debugging/SKILL.md.
+> Adaptations: skill name (bober.debug), tool name references where bober has equivalents.
+
+# Systematic Debugging
+
+## Overview
+
+Random fixes waste time and create new bugs. Quick patches mask underlying issues.
+
+**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.
+
+**Violating the letter of this process is violating the spirit of debugging.**
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+If you haven't completed Phase 1, you cannot propose fixes.
+
+## When to Use
+
+Use for ANY technical issue:
+- Test failures
+- Bugs in production
+- Unexpected behavior
+- Performance problems
+- Build failures
+- Integration issues
+
+**Use this ESPECIALLY when:**
+- Under time pressure (emergencies make guessing tempting)
+- "Just one quick fix" seems obvious
+- You've already tried multiple fixes
+- Previous fix didn't work
+- You don't fully understand the issue
+
+**Don't skip when:**
+- Issue seems simple (simple bugs have root causes too)
+- You're in a hurry (rushing guarantees rework)
+- Manager wants it fixed NOW (systematic is faster than thrashing)
+
+## The Four Phases
+
+You MUST complete each phase before proceeding to the next.
+
+### Phase 1: Root Cause Investigation
+
+**BEFORE attempting ANY fix:**
+
+1. **Read Error Messages Carefully**
+   - Don't skip past errors or warnings
+   - They often contain the exact solution
+   - Read stack traces completely
+   - Note line numbers, file paths, error codes
+
+2. **Reproduce Consistently**
+   - Can you trigger it reliably?
+   - What are the exact steps?
+   - Does it happen every time?
+   - If not reproducible → gather more data, don't guess
+
+3. **Check Recent Changes**
+   - What changed that could cause this?
+   - Git diff, recent commits
+   - New dependencies, config changes
+   - Environmental differences
+
+4. **Gather Evidence in Multi-Component Systems**
+
+   **WHEN system has multiple components (CI → build → signing, API → service → database):**
+
+   **BEFORE proposing fixes, add diagnostic instrumentation:**
+   ```
+   For EACH component boundary:
+     - Log what data enters component
+     - Log what data exits component
+     - Verify environment/config propagation
+     - Check state at each layer
+
+   Run once to gather evidence showing WHERE it breaks
+   THEN analyze evidence to identify failing component
+   THEN investigate that specific component
+   ```
+
+   **Example (multi-layer system):**
+   ```bash
+   # Layer 1: Workflow
+   echo "=== Secrets available in workflow: ==="
+   echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}"
+
+   # Layer 2: Build script
+   echo "=== Env vars in build script: ==="
+   env | grep IDENTITY || echo "IDENTITY not in environment"
+
+   # Layer 3: Signing script
+   echo "=== Keychain state: ==="
+   security list-keychains
+   security find-identity -v
+
+   # Layer 4: Actual signing
+   codesign --sign "$IDENTITY" --verbose=4 "$APP"
+   ```
+
+   **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗)
+
+5. **Trace Data Flow**
+
+   **WHEN error is deep in call stack:**
+
+   See `root-cause-tracing.md` in this directory for the complete backward tracing technique.
+
+   **Quick version:**
+   - Where does bad value originate?
+   - What called this with bad value?
+   - Keep tracing up until you find the source
+   - Fix at source, not at symptom
+
+### Phase 2: Pattern Analysis
+
+**Find the pattern before fixing:**
+
+1. **Find Working Examples**
+   - Locate similar working code in same codebase
+   - What works that's similar to what's broken?
+
+2. **Compare Against References**
+   - If implementing pattern, read reference implementation COMPLETELY
+   - Don't skim - read every line
+   - Understand the pattern fully before applying
+
+3. **Identify Differences**
+   - What's different between working and broken?
+   - List every difference, however small
+   - Don't assume "that can't matter"
+
+4. **Understand Dependencies**
+   - What other components does this need?
+   - What settings, config, environment?
+   - What assumptions does it make?
+
+### Phase 3: Hypothesis and Testing
+
+**Scientific method:**
+
+1. **Form Single Hypothesis**
+   - State clearly: "I think X is the root cause because Y"
+   - Write it down
+   - Be specific, not vague
+
+2. **Test Minimally**
+   - Make the SMALLEST possible change to test hypothesis
+   - One variable at a time
+   - Don't fix multiple things at once
+
+3. **Verify Before Continuing**
+   - Did it work? Yes → Phase 4
+   - Didn't work? Form NEW hypothesis
+   - DON'T add more fixes on top
+
+4. **When You Don't Know**
+   - Say "I don't understand X"
+   - Don't pretend to know
+   - Ask for help
+   - Research more
+
+### Phase 4: Implementation
+
+**Fix the root cause, not the symptom:**
+
+1. **Create Failing Test Case**
+   - Simplest possible reproduction
+   - Automated test if possible
+   - One-off test script if no framework
+   - MUST have before fixing
+   - Use the `superpowers:test-driven-development` skill for writing proper failing tests
+
+2. **Implement Single Fix**
+   - Address the root cause identified
+   - ONE change at a time
+   - No "while I'm here" improvements
+   - No bundled refactoring
+
+3. **Verify Fix**
+   - Test passes now?
+   - No other tests broken?
+   - Issue actually resolved?
+
+4. **If Fix Doesn't Work**
+   - STOP
+   - Count: How many fixes have you tried?
+   - If < 3: Return to Phase 1, re-analyze with new information
+   - **If ≥ 3: STOP and question the architecture (step 5 below)**
+   - DON'T attempt Fix #4 without architectural discussion
+
+5. **If 3+ Fixes Failed: Question Architecture**
+
+   **Pattern indicating architectural problem:**
+   - Each fix reveals new shared state/coupling/problem in different place
+   - Fixes require "massive refactoring" to implement
+   - Each fix creates new symptoms elsewhere
+
+   **STOP and question fundamentals:**
+   - Is this pattern fundamentally sound?
+   - Are we "sticking with it through sheer inertia"?
+   - Should we refactor architecture vs. continue fixing symptoms?
+
+   **Discuss with your human partner before attempting more fixes**
+
+   This is NOT a failed hypothesis - this is a wrong architecture.
+
+## Red Flags - STOP and Follow Process
+
+If you catch yourself thinking:
+- "Quick fix for now, investigate later"
+- "Just try changing X and see if it works"
+- "Add multiple changes, run tests"
+- "Skip the test, I'll manually verify"
+- "It's probably X, let me fix that"
+- "I don't fully understand but this might work"
+- "Pattern says X but I'll adapt it differently"
+- "Here are the main problems: [lists fixes without investigation]"
+- Proposing solutions before tracing data flow
+- **"One more fix attempt" (when already tried 2+)**
+- **Each fix reveals new problem in different place**
+
+**ALL of these mean: STOP. Return to Phase 1.**
+
+**If 3+ fixes failed:** Question the architecture (see Phase 4.5)
+
+## your human partner's Signals You're Doing It Wrong
+
+**Watch for these redirections:**
+- "Is that not happening?" - You assumed without verifying
+- "Will it show us...?" - You should have added evidence gathering
+- "Stop guessing" - You're proposing fixes without understanding
+- "Ultrathink this" - Question fundamentals, not just symptoms
+- "We're stuck?" (frustrated) - Your approach isn't working
+
+**When you see these:** STOP. Return to Phase 1.
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "Issue is simple, don't need process" | Simple issues have root causes too. Process is fast for simple bugs. |
+| "Emergency, no time for process" | Systematic debugging is FASTER than guess-and-check thrashing. |
+| "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. |
+| "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. |
+| "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. |
+| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. |
+| "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. |
+| "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. |
+
+## Quick Reference
+
+| Phase | Key Activities | Success Criteria |
+|-------|---------------|------------------|
+| **1. Root Cause** | Read errors, reproduce, check changes, gather evidence | Understand WHAT and WHY |
+| **2. Pattern** | Find working examples, compare | Identify differences |
+| **3. Hypothesis** | Form theory, test minimally | Confirmed or new hypothesis |
+| **4. Implementation** | Create test, fix, verify | Bug resolved, tests pass |
+
+## When Process Reveals "No Root Cause"
+
+If systematic investigation reveals issue is truly environmental, timing-dependent, or external:
+
+1. You've completed the process
+2. Document what you investigated
+3. Implement appropriate handling (retry, timeout, error message)
+4. Add monitoring/logging for future investigation
+
+**But:** 95% of "no root cause" cases are incomplete investigation.
+
+## Supporting Techniques
+
+These techniques are part of systematic debugging and available in this directory:
+
+- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger
+- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause
+- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling
+
+**Related skills:**
+- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1)
+- **bober.verify** - Verify fix worked before claiming success
+
+## Real-World Impact
+
+From debugging sessions:
+- Systematic approach: 15-30 minutes to fix
+- Random fixes approach: 2-3 hours of thrashing
+- First-time fix rate: 95% vs 40%
+- New bugs introduced: Near zero vs common