@stanco323/oh-my-claude-code 4.10.3

package/skills/self-improve/scripts/plot_progress.py

@@ -0,0 +1,128 @@
+#!/usr/bin/env python3
+"""
+Progress visualization for the self-improvement loop.
+Reads raw_data.json and generates progress.png.
+
+Usage:
+    python3 plot_progress.py --data /path/to/raw_data.json --output /path/to/progress.png
+    python3 plot_progress.py --tracking-dir /path/to/.omc/self-improve/tracking/
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+
+def load_data(data_path: str) -> list:
+    path = Path(data_path)
+    if not path.exists():
+        print(f"Warning: {data_path} not found. No visualization generated.")
+        return []
+    with open(path) as f:
+        return json.load(f)
+
+
+def plot_with_matplotlib(data: list, output_path: str):
+    try:
+        import matplotlib
+        matplotlib.use('Agg')
+        import matplotlib.pyplot as plt
+    except ImportError:
+        print("Warning: matplotlib not available. Generating text summary instead.")
+        generate_text_summary(data, output_path)
+        return
+
+    iterations = sorted(set(d['iteration'] for d in data))
+    winners = [d for d in data if d.get('is_winner')]
+    losers = [d for d in data if not d.get('is_winner')]
+
+    fig, ax = plt.subplots(figsize=(12, 6))
+
+    if losers:
+        ax.scatter(
+            [d['iteration'] for d in losers],
+            [d['benchmark_score'] for d in losers],
+            c='lightgray', alpha=0.5, s=30, label='Candidates', zorder=2
+        )
+
+    if winners:
+        ax.plot(
+            [d['iteration'] for d in winners],
+            [d['benchmark_score'] for d in winners],
+            'b-o', linewidth=2, markersize=8, label='Winners', zorder=3
+        )
+
+        families = list(set(d.get('approach_family', 'unknown') for d in winners))
+        colors = plt.cm.Set2(range(len(families)))
+        family_color = dict(zip(families, colors))
+        for d in winners:
+            family = d.get('approach_family', 'unknown')
+            ax.annotate(
+                family[:4],
+                (d['iteration'], d['benchmark_score']),
+                textcoords="offset points", xytext=(0, 10),
+                fontsize=7, ha='center', color=family_color.get(family, 'black')
+            )
+
+    ax.set_xlabel('Iteration')
+    ax.set_ylabel('Benchmark Score')
+    ax.set_title('Self-Improvement Progress')
+    ax.legend(loc='best')
+    ax.grid(True, alpha=0.3)
+
+    plt.tight_layout()
+    plt.savefig(output_path, dpi=150)
+    plt.close()
+    print(f"Visualization saved to: {output_path}")
+
+
+def generate_text_summary(data: list, output_path: str):
+    """Fallback when matplotlib is not available."""
+    winners = [d for d in data if d.get('is_winner')]
+    summary_path = Path(output_path).with_suffix('.txt')
+
+    lines = ["Self-Improvement Progress Summary", "=" * 40, ""]
+    for w in winners:
+        lines.append(
+            f"Iteration {w['iteration']}: score={w['benchmark_score']:.4f} "
+            f"family={w.get('approach_family', '?')} plan={w.get('plan_id', '?')}"
+        )
+
+    if winners:
+        scores = [w['benchmark_score'] for w in winners]
+        lines.append("")
+        lines.append(f"Best: {max(scores):.4f}  Worst: {min(scores):.4f}  "
+                      f"Delta: {max(scores) - min(scores):.4f}")
+
+    with open(summary_path, 'w') as f:
+        f.write('\n'.join(lines))
+    print(f"Text summary saved to: {summary_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description='Self-improvement progress visualization')
+    parser.add_argument('--data', help='Path to raw_data.json')
+    parser.add_argument('--output', help='Path to output image')
+    parser.add_argument('--tracking-dir', help='Path to tracking/ directory (auto-discovers data and output)')
+    args = parser.parse_args()
+
+    if args.tracking_dir:
+        data_path = str(Path(args.tracking_dir) / 'raw_data.json')
+        output_path = str(Path(args.tracking_dir) / 'progress.png')
+    elif args.data and args.output:
+        data_path = args.data
+        output_path = args.output
+    else:
+        print("Usage: plot_progress.py --tracking-dir /path/ OR --data /path/raw_data.json --output /path/progress.png")
+        sys.exit(1)
+
+    data = load_data(data_path)
+    if not data:
+        sys.exit(0)
+
+    plot_with_matplotlib(data, output_path)
+
+
+if __name__ == '__main__':
+    main()

package/skills/self-improve/scripts/validate.sh

@@ -0,0 +1,315 @@
+#!/usr/bin/env bash
+# validate.sh — Sealed file enforcement + plan schema validation for self-improvement loop.
+# Usage:
+#   ./validate.sh --worktree /path plan.json    # worktree mode + plan validation
+#   ./validate.sh plan.json                     # plan schema validation only
+#   ./validate.sh                               # sealed file check only
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_DIR="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# Settings path must be provided or discovered from .omc/self-improve/config/
+SETTINGS=""
+
+# Parse arguments
+WORKTREE_PATH=""
+POSITIONAL_ARGS=()
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --worktree)
+            WORKTREE_PATH="$2"
+            shift 2
+            ;;
+        --settings)
+            SETTINGS="$2"
+            shift 2
+            ;;
+        *)
+            POSITIONAL_ARGS+=("$1")
+            shift
+            ;;
+    esac
+done
+set -- "${POSITIONAL_ARGS[@]+"${POSITIONAL_ARGS[@]}"}"
+
+# Auto-discover settings if not provided
+if [[ -z "${SETTINGS}" ]]; then
+    # Walk up from worktree or CWD to find .omc/self-improve/config/settings.json
+    SEARCH_DIR="${WORKTREE_PATH:-$(pwd)}"
+    while [[ "${SEARCH_DIR}" != "/" ]]; do
+        if [[ -f "${SEARCH_DIR}/.omc/self-improve/config/settings.json" ]]; then
+            SETTINGS="${SEARCH_DIR}/.omc/self-improve/config/settings.json"
+            break
+        fi
+        SEARCH_DIR="$(dirname "${SEARCH_DIR}")"
+    done
+fi
+
+GIT_DIR="${WORKTREE_PATH:-$(pwd)}"
+
+err() { echo "ERROR: $*" >&2; }
+ok()  { echo "OK: $*"; }
+
+require_jq() {
+    if ! command -v jq &>/dev/null; then
+        err "jq is not installed. Install with: brew install jq (macOS) or apt-get install jq (Linux)"
+        exit 1
+    fi
+}
+
+check_sealed_files() {
+    require_jq
+
+    if [[ -z "${SETTINGS}" || ! -f "${SETTINGS}" ]]; then
+        ok "No settings file found — skipping sealed file check."
+        return 0
+    fi
+
+    has_sealed=$(jq -r 'if (.sealed_files | type) == "array" and (.sealed_files | length) > 0 then "yes" else "no" end' "${SETTINGS}" 2>/dev/null || echo "no")
+
+    if [[ "${has_sealed}" != "yes" ]]; then
+        ok "No sealed files configured — skipping."
+        return 0
+    fi
+
+    if ! git -C "${GIT_DIR}" rev-parse --git-dir &>/dev/null 2>&1; then
+        ok "Not a git repository — skipping sealed file check."
+        return 0
+    fi
+
+    local modified_files_str=""
+    if [[ -n "${WORKTREE_PATH}" ]]; then
+        # Find the correct baseline: the improvement branch this experiment branched from.
+        # Try improve/* branches first, then fall back to main/master.
+        local base_commit
+        local improve_branch
+        improve_branch=$(git -C "${GIT_DIR}" branch -a --list 'improve/*' 2>/dev/null | head -1 | tr -d ' *' || true)
+        if [[ -z "${improve_branch}" ]]; then
+            improve_branch=$(git -C "${GIT_DIR}" symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||' || echo "main")
+        fi
+        base_commit=$(git -C "${GIT_DIR}" merge-base HEAD "${improve_branch}" 2>/dev/null || echo "HEAD~1")
+        modified_files_str=$(git -C "${GIT_DIR}" diff --name-only "${base_commit}" 2>/dev/null || true)
+        local uncommitted
+        uncommitted=$(git -C "${GIT_DIR}" diff --name-only 2>/dev/null || true)
+        if [[ -n "${uncommitted}" ]]; then
+            modified_files_str="${modified_files_str}"$'\n'"${uncommitted}"
+        fi
+    else
+        modified_files_str=$(git -C "${GIT_DIR}" diff --name-only HEAD 2>/dev/null || true)
+        local staged
+        staged=$(git -C "${GIT_DIR}" diff --name-only --cached 2>/dev/null || true)
+        if [[ -n "${staged}" ]]; then
+            modified_files_str="${modified_files_str}"$'\n'"${staged}"
+        fi
+    fi
+
+    if [[ -n "${modified_files_str}" ]]; then
+        modified_files_str=$(echo "${modified_files_str}" | sort -u)
+    fi
+
+    if [[ -z "${modified_files_str}" ]]; then
+        ok "No modified files detected."
+        return 0
+    fi
+
+    violations=""
+    while IFS= read -r sealed; do
+        [[ -z "${sealed}" ]] && continue
+        while IFS= read -r modified; do
+            [[ -z "${modified}" ]] && continue
+            if [[ "${sealed}" == */ ]]; then
+                [[ "${modified}" == "${sealed}"* ]] && violations="${violations} ${modified}"
+            else
+                [[ "${modified}" == "${sealed}" ]] && violations="${violations} ${modified}"
+            fi
+        done <<< "${modified_files_str}"
+    done < <(jq -r '.sealed_files[]' "${SETTINGS}" 2>/dev/null)
+
+    if [[ -n "${violations}" ]]; then
+        err "Sealed file(s) were modified:${violations}"
+        exit 1
+    fi
+
+    local modified_count
+    modified_count=$(echo "${modified_files_str}" | wc -l | tr -d ' ')
+    ok "Sealed file check passed (${modified_count} modified, none sealed)."
+}
+
+check_plan_schema() {
+    local plan_file="$1"
+    require_jq
+
+    if [[ ! -f "${plan_file}" ]]; then
+        err "Plan file not found: ${plan_file}"
+        exit 1
+    fi
+
+    local required_fields="plan_id planner_id round hypothesis approach_family critic_approved target_files steps expected_outcome history_reference"
+    local missing=""
+
+    for field in ${required_fields}; do
+        val=$(jq -r --arg f "${field}" '.[$f]' "${plan_file}" 2>/dev/null)
+        if [[ "${val}" == "null" || -z "${val}" ]]; then
+            missing="${missing} ${field}"
+        fi
+    done
+
+    if [[ -n "${missing}" ]]; then
+        err "Plan is missing required fields:${missing}"
+        exit 1
+    fi
+    ok "Plan contains all required fields."
+
+    # approach_family validation is handled by the critic (supports custom families
+    # from harness.md). validate.sh only checks structural schema, not taxonomy.
+
+    # Validate hypothesis is a single string
+    hypothesis_type=$(jq -r '.hypothesis | type' "${plan_file}" 2>/dev/null)
+    if [[ "${hypothesis_type}" != "string" ]]; then
+        err "hypothesis must be a string (got ${hypothesis_type})"
+        exit 1
+    fi
+    ok "One-hypothesis check passed."
+
+    # Validate steps non-empty
+    steps_len=$(jq '.steps | length' "${plan_file}" 2>/dev/null || echo "0")
+    if [[ "${steps_len}" -eq 0 ]]; then
+        err "steps must be a non-empty array"
+        exit 1
+    fi
+    ok "Steps validated (${steps_len} step(s))."
+}
+
+check_result_schema() {
+    local result_file="$1"
+    require_jq
+
+    if [[ ! -f "${result_file}" ]]; then
+        err "Result file not found: ${result_file}"
+        exit 1
+    fi
+
+    local required_fields="executor_id plan_id benchmark_score status timestamp benchmark_raw"
+    local missing=""
+
+    for field in ${required_fields}; do
+        val=$(jq -r --arg f "${field}" '.[$f]' "${result_file}" 2>/dev/null)
+        if [[ "${val}" == "null" || -z "${val}" ]]; then
+            if [[ "${field}" == "benchmark_raw" ]]; then
+                exists=$(jq --arg f "${field}" 'has($f)' "${result_file}" 2>/dev/null || echo "false")
+                if [[ "${exists}" != "true" ]]; then
+                    missing="${missing} ${field}"
+                fi
+            elif [[ "${field}" == "benchmark_score" ]]; then
+                exists=$(jq --arg f "${field}" 'has($f)' "${result_file}" 2>/dev/null || echo "false")
+                if [[ "${exists}" != "true" ]]; then
+                    missing="${missing} ${field}"
+                fi
+            else
+                missing="${missing} ${field}"
+            fi
+        fi
+    done
+
+    if [[ -n "${missing}" ]]; then
+        err "Result is missing required fields:${missing}"
+        exit 1
+    fi
+    ok "Result contains all required fields."
+
+    # Validate status enum
+    local status
+    status=$(jq -r '.status' "${result_file}" 2>/dev/null)
+    case "${status}" in
+        success|regression|error|timeout) ;;
+        *)
+            err "Invalid status '${status}'. Must be one of: success, regression, error, timeout"
+            exit 1
+            ;;
+    esac
+    ok "Status '${status}' is valid."
+
+    # Check failure_analysis on non-success status
+    if [[ "${status}" != "success" ]]; then
+        local fa_type
+        fa_type=$(jq -r '.failure_analysis | type' "${result_file}" 2>/dev/null)
+        if [[ "${fa_type}" != "object" ]]; then
+            err "failure_analysis must be a non-null object when status is '${status}' (got ${fa_type})"
+            exit 1
+        fi
+
+        local fa_fields="what why category lesson"
+        local fa_missing=""
+        for field in ${fa_fields}; do
+            val=$(jq -r --arg f "${field}" '.failure_analysis[$f]' "${result_file}" 2>/dev/null)
+            if [[ "${val}" == "null" || -z "${val}" ]]; then
+                fa_missing="${fa_missing} ${field}"
+            fi
+        done
+
+        if [[ -n "${fa_missing}" ]]; then
+            err "failure_analysis is missing required fields:${fa_missing}"
+            exit 1
+        fi
+        ok "failure_analysis is complete for non-success status."
+
+        # Validate failure category enum
+        local fa_category
+        fa_category=$(jq -r '.failure_analysis.category' "${result_file}" 2>/dev/null)
+        local valid_categories="oom timeout regression logic_error scope_error infrastructure benchmark_parse_error sealed_file_violation"
+        local cat_valid=0
+        for cat in ${valid_categories}; do
+            if [[ "${fa_category}" == "${cat}" ]]; then
+                cat_valid=1
+                break
+            fi
+        done
+
+        if [[ ${cat_valid} -eq 0 ]]; then
+            err "failure_analysis.category '${fa_category}' is not valid. Must be one of: ${valid_categories}"
+            exit 1
+        fi
+        ok "failure_analysis.category '${fa_category}' is valid."
+    fi
+
+    # Validate sub_scores if present
+    local has_sub_scores
+    has_sub_scores=$(jq 'has("sub_scores")' "${result_file}" 2>/dev/null || echo "false")
+    if [[ "${has_sub_scores}" == "true" ]]; then
+        local sub_scores_type
+        sub_scores_type=$(jq -r '.sub_scores | type' "${result_file}" 2>/dev/null)
+        if [[ "${sub_scores_type}" == "object" ]]; then
+            local invalid_values
+            invalid_values=$(jq -r '.sub_scores | to_entries[] | select(.value != null and (.value | type) != "number") | .key' "${result_file}" 2>/dev/null)
+            if [[ -n "${invalid_values}" ]]; then
+                err "sub_scores contains non-numeric values for keys: ${invalid_values}"
+                exit 1
+            fi
+            local sub_scores_count
+            sub_scores_count=$(jq '.sub_scores | length' "${result_file}" 2>/dev/null)
+            ok "sub_scores is a valid object (${sub_scores_count} dimension(s))."
+        elif [[ "${sub_scores_type}" != "null" ]]; then
+            err "sub_scores must be an object or null (got ${sub_scores_type})"
+            exit 1
+        fi
+    fi
+}
+
+main() {
+    echo "=== self-improve validate.sh ==="
+    check_sealed_files
+
+    if [[ ${#POSITIONAL_ARGS[@]} -ge 1 ]]; then
+        check_plan_schema "${POSITIONAL_ARGS[0]}"
+    fi
+
+    if [[ ${#POSITIONAL_ARGS[@]} -ge 2 ]]; then
+        check_result_schema "${POSITIONAL_ARGS[1]}"
+    fi
+
+    echo "=== All checks passed ==="
+}
+
+main

package/skills/self-improve/si-benchmark-builder.md

@@ -0,0 +1,79 @@
+# Self-Improvement Benchmark Builder
+
+## Input Contract
+
+Arguments passed via prompt context:
+- `repo_path`: Absolute path to the target repository
+- `goal_path`: Path to goal.md with defined objective and metric
+- `settings_path`: Path to settings.json
+- `agent_settings_path`: Path to agent-settings.json
+- `tracking_path`: Path to tracking/ directory
+
+## Role
+
+You build a benchmark for the self-improvement loop. The benchmark must produce a measurable score that the loop can optimize against. Prefer adapting existing evaluation over building from scratch.
+
+## Prerequisites
+
+- Target repo exists and is cloned
+- Goal is defined (si_setting_goal is true)
+- goal.md has a defined objective and metric
+
+## Workflow
+
+### Phase 1 — Understand the Goal
+Read goal.md. Extract metric name, direction, target value, scope.
+
+### Phase 2 — Repo Survey
+Explore the target repo for existing evaluation:
+- Test suites (pytest, jest, go test, cargo test)
+- Benchmark scripts (benchmark.*, eval.*, score.*)
+- CI evaluation (.github/workflows/)
+- Performance tests, metrics in code
+
+Classify: Ready to use | Partially usable | Nothing exists
+
+### Phase 3 — Interview (only if needed)
+If approach is unclear, ask up to 3 questions. Hard cap.
+
+### Phase 4 — Design
+Requirements:
+- **JSON output preferred**: Last line of stdout as `{"primary": 85.2, "sub_scores": {"dim_a": 0.92}}`
+- **Deterministic**: Same code → same score (fixed seeds)
+- **Fast**: Under 5 minutes ideally
+- **Self-contained**: No external services
+- **Honest**: Measures actual quality
+
+### Phase 5 — Implement
+Build the benchmark. Place it in the target repo (scripts/benchmark.py or benchmark.py).
+Must exit 0 on success, non-zero on error. Print score as last stdout line.
+
+### Phase 6 — Validate
+Run the benchmark 3 times:
+```
+Run 1: {x}
+Run 2: {y}
+Run 3: {z}
+Variance: {(max-min)/mean * 100}%
+```
+All 3 must complete. Variance must be < 5%.
+
+### Phase 7 — Record and Configure
+Update settings.json:
+- `benchmark_command`: the shell command
+- `benchmark_format`: "json", "number", or "pass_fail"
+- `primary_metric`: key name in JSON output (default: "primary")
+
+**Add benchmark script to `sealed_files`** — prevents the loop from modifying it.
+
+Record baseline to tracking/baseline.json:
+```json
+{ "baseline_score": <mean_score>, "recorded_at": "<ISO 8601>" }
+```
+
+Update agent-settings.json:
+- `si_setting_benchmark` → true
+- `best_score` → mean_score
+
+### Phase 8 — Handoff
+Report: benchmark command, score, variance, and next step.

package/skills/self-improve/si-goal-clarifier.md

@@ -0,0 +1,93 @@
+# Self-Improvement Goal Clarifier
+
+## Input Contract
+
+Arguments passed via context:
+- `repo_path`: Absolute path to the target repository
+- `config_path`: Path to .omc/self-improve/config/
+- `agent_settings_path`: Path to agent-settings.json
+
+## Role
+
+You are an interviewer. Turn a vague improvement idea into a crystal-clear, measurable goal through targeted questioning. One question per round, always targeting the weakest dimension.
+
+## Prerequisites
+
+- Target repo exists and is cloned
+- If goal.md already has a complete goal, ask: "A goal is already defined. Refine or start fresh?"
+
+## Clarity Dimensions
+
+Score each 0-100 after every round:
+
+| Dimension | What it measures |
+|-----------|-----------------|
+| **Objective** | What exactly should improve? Specific enough to act on? |
+| **Metric** | How do we measure it? Well-defined and automatable? |
+| **Target** | What score are we aiming for? Realistic? |
+| **Scope** | Which files/modules in/out of bounds? |
+
+**Ambiguity score** = 100 - average(all dimensions)
+
+## Workflow
+
+### Phase 1 — Repo Scan (silent)
+Explore the target repo: README, main source, tests, configs. Identify what it does, existing metrics, improvement opportunities. Use this to inform questions.
+
+### Phase 2 — Fast-Path Check
+If user provides fully formed goal (objective, metric, target, scope all clear), skip interview. Go to Phase 4.
+
+### Phase 3 — Interview Rounds
+Each round:
+1. Score all 4 dimensions
+2. Display scoreboard:
+   ```
+   === Round {n} ===
+   Objective:  {score}/100
+   Metric:     {score}/100
+   Target:     {score}/100
+   Scope:      {score}/100
+   Ambiguity:  {score}%
+   ```
+3. Ask ONE question targeting the lowest-scoring dimension. Use repo context.
+4. Wait for response. Update scores. Repeat.
+
+**Exit when ambiguity <= 20%** (all dimensions >= 80).
+**Soft cap: 8 rounds**. **Hard cap: 12 rounds**.
+
+### Phase 4 — Write Goal
+Write `.omc/self-improve/config/goal.md`:
+```markdown
+# Improvement Goal
+
+## Objective
+{specific objective}
+
+## Target Metric
+- **Metric name**: {name}
+- **Target value**: {value}
+- **Direction**: higher_is_better | lower_is_better
+
+## Scope
+- **In scope**: {files, modules}
+- **Out of scope**: {exclusions}
+
+## Milestones (optional)
+| Milestone | Target | Strategy Focus |
+|-----------|--------|----------------|
+
+## Experiment Ideas (optional)
+{ideas from interview}
+```
+
+Update settings.json: `benchmark_direction`, `target_value`
+Set `si_setting_goal` → true in agent-settings.json
+
+### Phase 5 — Handoff
+Print summary and suggest next step (benchmark builder if needed).
+
+## Constraints
+- ONE question per round
+- Never assume — ask
+- Use repo evidence in questions
+- Partial updates only when writing settings JSON

package/skills/self-improve/si-researcher.md

@@ -0,0 +1,73 @@
+# Self-Improvement Researcher
+
+## Input Contract
+
+Arguments passed via prompt context:
+- `iteration`: Current iteration number (1-indexed)
+- `repo_path`: Absolute path to the target repository
+- `goal_path`: Path to goal.md
+- `history_path`: Path to iteration_history/ directory
+- `briefs_path`: Path to research_briefs/ directory
+
+## Role
+
+You are the **knowledge gatherer** for the self-improvement loop. Your job is to explore the target repository and search externally to produce a structured **research brief** before planners begin work. You run once per iteration, first.
+
+Your output — a research brief JSON — is the foundation all N planners read before generating hypotheses.
+
+## Inputs
+
+Read all of the following before producing output:
+
+- Goal file — improvement objective, target metric, scope constraints, experiment ideas
+- Iteration history — ALL prior records (winners, losers, lessons)
+- Prior research briefs — avoid redundant research
+- Target repository — source files, tests, configs, documentation
+
+## Workflow
+
+1. **Read the goal**: Extract primary metric, target score, scope constraints, user ideas
+2. **Read all iteration history**: Build a map of what has been tried, what worked, what failed
+3. **Check for user ideas**: Treat as highest-priority input
+4. **Deep-dive the target repository**:
+   - README, main source, tests, configs, dependencies
+   - Known bottlenecks (TODO/FIXME comments, profile outputs)
+   - Test coverage gaps, configuration defaults, outdated dependencies
+5. **Determine research strategy** based on iteration state:
+   - First iteration → broad exploration across all approach families
+   - After failures → avoid repeating documented failures
+   - Strategy exhaustion (same family 3+ wins) → shift to unexplored families
+   - Near target (within 5%) → fine-grained, low-risk changes
+6. **Search externally** when needed: papers, benchmarks, similar projects, official docs
+7. **Rank ideas**: high confidence first, then medium, then low. 3-10 ideas.
+8. **Write the research brief** as JSON
+
+## Output
+
+Write to the path specified by the orchestrator. JSON format:
+
+```json
+{
+  "iteration": 1,
+  "researcher_id": "researcher",
+  "repo_analysis_summary": "What the codebase does, current metric state, what has been tried, biggest gap",
+  "ideas": [
+    {
+      "title": "Short action-oriented name",
+      "source": "Specific origin — file names, issue numbers, paper titles",
+      "evidence": "Concrete evidence — line numbers, config values, benchmark numbers",
+      "approach_family": "architecture|training_config|data|infrastructure|optimization|testing|documentation|other",
+      "confidence": "high|medium|low",
+      "estimated_impact": "3-5% or unknown"
+    }
+  ]
+}
+```
+
+## Quality Standards
+
+- Every idea has specific, citable evidence
+- No idea repeats a documented failure without explaining the difference
+- Ideas span at least 2 different approach families
+- Ideas sorted: high confidence first
+- Valid JSON matching the schema