@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/anndata/SKILL.md

@@ -1,431 +0,0 @@
----
-name: anndata
-description: Data structure for annotated matrices in single-cell analysis. Use when working with .h5ad files or integrating with the scverse ecosystem. This is the data format skill—for analysis workflows use scanpy; for probabilistic models use scvi-tools; for population-scale queries use cellxgene-census.
-license: BSD-3-Clause license
-allowed-tools: Read Write Edit Bash
-compatibility: Requires Python 3.11+ and uv. Examples target AnnData 0.12.16, with experimental APIs clearly marked where used.
-metadata:
-  version: "1.1"
-  skill-author: K-Dense Inc.
----
-
-# AnnData
-
-## Overview
-
-AnnData is a Python package for handling annotated data matrices, storing experimental measurements (X) alongside observation metadata (obs), variable metadata (var), and multi-dimensional annotations (obsm, varm, obsp, varp, uns). Originally designed for single-cell genomics through Scanpy, it now serves as a general-purpose framework for any annotated data requiring efficient storage, manipulation, and analysis.
-
-## When to Use This Skill
-
-Use this skill when:
-- Creating, reading, or writing AnnData objects
-- Working with h5ad, zarr, or other genomics data formats
-- Performing single-cell RNA-seq analysis
-- Managing large datasets with sparse matrices or backed mode
-- Concatenating multiple datasets or experimental batches
-- Subsetting, filtering, or transforming annotated data
-- Integrating with scanpy, scvi-tools, or other scverse ecosystem tools
-
-## Installation
-
-Requires Python 3.11+. Current stable release: 0.12.16 (released 2026-05-18).
-
-```bash
-uv pip install "anndata==0.12.16"
-
-# Lazy I/O and dask-backed operations
-uv pip install "anndata[dask,lazy]==0.12.16"
-
-# Development / docs (contributors)
-uv pip install "anndata[dev,test,doc]==0.12.16"
-```
-
-Use unpinned installs only when intentionally tracking the latest compatible release.
-
-Current API notes:
-- Use `anndata.io` for non-native `read_*` and `write_*` helpers. Top-level `anndata.read_h5ad` and `anndata.read_zarr` remain supported.
-- Avoid deprecated APIs: `ad.read`, `AnnData.concatenate()`, `AnnData.*_keys()`, and `anndata.__version__`. Prefer `ad.read_h5ad`, `ad.concat`, mapping `.keys()`, and `importlib.metadata.version("anndata")`.
-- Treat `anndata.experimental` APIs as useful but unstable. Prefer them for large-data workflows only when their current caveats are acceptable.
-
-## Quick Start
-
-### Creating an AnnData object
-```python
-import anndata as ad
-import numpy as np
-import pandas as pd
-
-# Minimal creation
-X = np.random.rand(100, 2000)  # 100 cells × 2000 genes
-adata = ad.AnnData(X)
-
-# With metadata
-obs = pd.DataFrame({
-    'cell_type': ['T cell', 'B cell'] * 50,
-    'sample': ['A', 'B'] * 50
-}, index=[f'cell_{i}' for i in range(100)])
-
-var = pd.DataFrame({
-    'gene_name': [f'Gene_{i}' for i in range(2000)]
-}, index=[f'ENSG{i:05d}' for i in range(2000)])
-
-adata = ad.AnnData(X=X, obs=obs, var=var)
-```
-
-### Reading data
-```python
-# Native formats (read_h5ad/read_zarr remain at top-level)
-adata = ad.read_h5ad('data.h5ad')
-adata = ad.read_h5ad('large_data.h5ad', backed='r')  # lazy load for large files
-adata = ad.read_zarr('data.zarr')
-
-# Other formats: prefer anndata.io (top-level imports are deprecated)
-from anndata.io import read_csv, read_loom, read_mtx
-
-adata = read_csv('data.csv')
-adata = read_loom('data.loom')
-
-# 10X Genomics: use scanpy (not anndata) — see scanpy skill
-import scanpy as sc
-adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')
-adata = sc.read_10x_mtx('filtered_feature_bc_matrix/')
-```
-
-### Writing data
-```python
-# Write h5ad file
-adata.write_h5ad('output.h5ad')
-
-# Write with compression
-adata.write_h5ad('output.h5ad', compression='gzip')
-
-# Write other formats
-adata.write_zarr('output.zarr')
-adata.write_csvs('output_dir/')
-```
-
-### Basic operations
-```python
-# Subset by conditions
-t_cells = adata[adata.obs['cell_type'] == 'T cell']
-
-# Subset by indices
-subset = adata[0:50, 0:100]
-
-# Add metadata
-adata.obs['quality_score'] = np.random.rand(adata.n_obs)
-adata.var['highly_variable'] = np.random.rand(adata.n_vars) > 0.8
-
-# Access dimensions
-print(f"{adata.n_obs} observations × {adata.n_vars} variables")
-```
-
-## Core Capabilities
-
-### 1. Data Structure
-
-Understand the AnnData object structure including X, obs, var, layers, obsm, varm, obsp, varp, uns, and raw components.
-
-**See**: `references/data_structure.md` for comprehensive information on:
-- Core components (X, obs, var, layers, obsm, varm, obsp, varp, uns, raw)
-- Creating AnnData objects from various sources
-- Accessing and manipulating data components
-- Memory-efficient practices
-
-### 2. Input/Output Operations
-
-Read and write data in various formats with support for compression, backed mode, and cloud storage.
-
-**See**: `references/io_operations.md` for details on:
-- Native formats (h5ad, zarr)
-- Alternative formats (CSV, MTX, Loom, 10X, Excel)
-- Backed mode for large datasets
-- Remote data access
-- Format conversion
-- Performance optimization
-
-Common commands:
-```python
-from anndata.io import read_mtx
-
-# Read/write h5ad
-adata = ad.read_h5ad('data.h5ad', backed='r')
-adata.write_h5ad('output.h5ad', compression='gzip')
-
-# 10X Genomics (via scanpy)
-import scanpy as sc
-adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')
-
-# Read MTX format
-adata = read_mtx('matrix.mtx').T
-```
-
-### 3. Concatenation
-
-Combine multiple AnnData objects along observations or variables with flexible join strategies.
-
-**See**: `references/concatenation.md` for comprehensive coverage of:
-- Basic concatenation (axis=0 for observations, axis=1 for variables)
-- Join types (inner, outer)
-- Merge strategies (same, unique, first, only)
-- Tracking data sources with labels
-- Lazy concatenation (AnnCollection)
-- On-disk concatenation for large datasets
-
-Common commands:
-```python
-# Concatenate observations (combine samples)
-adata = ad.concat(
-    [adata1, adata2, adata3],
-    axis=0,
-    join='inner',
-    label='batch',
-    keys=['batch1', 'batch2', 'batch3']
-)
-
-# Concatenate variables (combine modalities)
-adata = ad.concat([adata_rna, adata_protein], axis=1)
-
-# Lazy collection over backed AnnData objects (experimental)
-from anndata.experimental import AnnCollection
-
-backed_adatas = [
-    ad.read_h5ad(path, backed='r')
-    for path in ['data1.h5ad', 'data2.h5ad']
-]
-collection = AnnCollection(
-    backed_adatas,
-    join_obs='outer',
-    join_vars='inner',
-    label='dataset'
-)
-```
-
-### 4. Data Manipulation
-
-Transform, subset, filter, and reorganize data efficiently.
-
-**See**: `references/manipulation.md` for detailed guidance on:
-- Subsetting (by indices, names, boolean masks, metadata conditions)
-- Transposition
-- Copying (full copies vs views)
-- Renaming (observations, variables, categories)
-- Type conversions (strings to categoricals, sparse/dense)
-- Adding/removing data components
-- Reordering
-- Quality control filtering
-
-Common commands:
-```python
-# Subset by metadata
-filtered = adata[adata.obs['quality_score'] > 0.8]
-hv_genes = adata[:, adata.var['highly_variable']]
-
-# Transpose
-adata_T = adata.T
-
-# Copy vs view
-view = adata[0:100, :]  # View (lightweight reference)
-copy = adata[0:100, :].copy()  # Independent copy
-
-# Convert strings to categoricals
-adata.strings_to_categoricals()
-```
-
-### 5. Best Practices
-
-Follow recommended patterns for memory efficiency, performance, and reproducibility.
-
-**See**: `references/best_practices.md` for guidelines on:
-- Memory management (sparse matrices, categoricals, backed mode)
-- Views vs copies
-- Data storage optimization
-- Performance optimization
-- Working with raw data
-- Metadata management
-- Reproducibility
-- Error handling
-- Integration with other tools
-- Common pitfalls and solutions
-
-Key recommendations:
-```python
-# Use sparse matrices for sparse data
-from scipy.sparse import csr_matrix
-adata.X = csr_matrix(adata.X)
-
-# Convert strings to categoricals
-adata.strings_to_categoricals()
-
-# Use backed mode for large files
-adata = ad.read_h5ad('large.h5ad', backed='r')
-
-# Store raw before filtering
-adata.raw = adata.copy()
-adata = adata[:, adata.var['highly_variable']]
-```
-
-## Integration with Scverse Ecosystem
-
-AnnData serves as the foundational data structure for the scverse ecosystem:
-
-### Scanpy (Single-cell analysis)
-```python
-import scanpy as sc
-
-# Preprocessing
-sc.pp.filter_cells(adata, min_genes=200)
-sc.pp.normalize_total(adata, target_sum=1e4)
-sc.pp.log1p(adata)
-sc.pp.highly_variable_genes(adata, n_top_genes=2000)
-
-# Dimensionality reduction
-sc.pp.pca(adata, n_comps=50)
-sc.pp.neighbors(adata, n_neighbors=15)
-sc.tl.umap(adata)
-sc.tl.leiden(adata)
-
-# Visualization
-sc.pl.umap(adata, color=['cell_type', 'leiden'])
-```
-
-### Muon (Multimodal data)
-```python
-import muon as mu
-
-# Combine RNA and protein data
-mdata = mu.MuData({'rna': adata_rna, 'protein': adata_protein})
-```
-
-### PyTorch integration
-```python
-from anndata.experimental import AnnLoader
-
-# Create DataLoader for deep learning
-dataloader = AnnLoader(adata, batch_size=128, shuffle=True)
-
-for batch in dataloader:
-    X = batch.X
-    # Train model
-```
-
-## Common Workflows
-
-### Single-cell RNA-seq analysis
-```python
-import anndata as ad
-import scanpy as sc
-
-# 1. Load data (10X via scanpy; anndata handles h5ad/zarr natively)
-adata = sc.read_10x_h5('filtered_feature_bc_matrix.h5')
-
-# 2. Quality control
-adata.obs['n_genes'] = (adata.X > 0).sum(axis=1)
-adata.obs['n_counts'] = adata.X.sum(axis=1)
-adata = adata[adata.obs['n_genes'] > 200]
-adata = adata[adata.obs['n_counts'] < 50000]
-
-# 3. Store raw
-adata.raw = adata.copy()
-
-# 4. Normalize and filter
-sc.pp.normalize_total(adata, target_sum=1e4)
-sc.pp.log1p(adata)
-sc.pp.highly_variable_genes(adata, n_top_genes=2000)
-adata = adata[:, adata.var['highly_variable']]
-
-# 5. Save processed data
-adata.write_h5ad('processed.h5ad')
-```
-
-### Batch integration
-```python
-# Load multiple batches
-adata1 = ad.read_h5ad('batch1.h5ad')
-adata2 = ad.read_h5ad('batch2.h5ad')
-adata3 = ad.read_h5ad('batch3.h5ad')
-
-# Concatenate with batch labels
-adata = ad.concat(
-    [adata1, adata2, adata3],
-    label='batch',
-    keys=['batch1', 'batch2', 'batch3'],
-    join='inner'
-)
-
-# Apply batch correction
-import scanpy as sc
-sc.pp.combat(adata, key='batch')
-
-# Continue analysis
-sc.pp.pca(adata)
-sc.pp.neighbors(adata)
-sc.tl.umap(adata)
-```
-
-### Working with large datasets
-```python
-# Open in backed mode
-adata = ad.read_h5ad('100GB_dataset.h5ad', backed='r')
-
-# Filter based on metadata (no data loading)
-high_quality = adata[adata.obs['quality_score'] > 0.8]
-
-# Load filtered subset
-adata_subset = high_quality.to_memory()
-
-# Process subset
-process(adata_subset)
-
-# Or process in chunks
-chunk_size = 1000
-for i in range(0, adata.n_obs, chunk_size):
-    chunk = adata[i:i+chunk_size, :].to_memory()
-    process(chunk)
-```
-
-## Troubleshooting
-
-### Out of memory errors
-Use backed mode or convert to sparse matrices:
-```python
-# Backed mode
-adata = ad.read_h5ad('file.h5ad', backed='r')
-
-# Sparse matrices
-from scipy.sparse import csr_matrix
-adata.X = csr_matrix(adata.X)
-```
-
-### Slow file reading
-Use compression and appropriate formats:
-```python
-# Optimize for storage
-adata.strings_to_categoricals()
-adata.write_h5ad('file.h5ad', compression='gzip')
-
-# Use Zarr for cloud storage; v3 writes are opt-in in anndata 0.12
-import anndata as ad
-
-ad.settings.zarr_write_format = 3
-ad.settings.auto_shard_zarr_v3 = True  # experimental; independent of zarr_write_format
-adata.write_zarr('file.zarr', chunks=(1000, 1000))
-```
-
-### Index alignment issues
-Always align external data on index:
-```python
-# Wrong
-adata.obs['new_col'] = external_data['values']
-
-# Correct
-adata.obs['new_col'] = external_data.set_index('cell_id').loc[adata.obs_names, 'values']
-```
-
-## Additional Resources
-
-- **Official documentation**: https://anndata.readthedocs.io/
-- **Scanpy tutorials**: https://scanpy.readthedocs.io/
-- **Scverse ecosystem**: https://scverse.org/
-- **GitHub repository**: https://github.com/scverse/anndata
-

package/skills/arbor/SKILL.md

@@ -1,152 +0,0 @@
----
-name: arbor
-description: Autonomously improve a real artifact (code, training recipe, agent harness, data pipeline, prompt) against an objective and an evaluator, using Hypothesis Tree Refinement (HTR) from the Arbor paper. Use this whenever someone wants to iteratively optimize something over many experiments without overfitting — e.g. "get my model's eval score up", "improve this agent/harness", "tune this pipeline", "beat the baseline on this benchmark", "run a search over approaches and keep the best", "do an MLE-bench / Kaggle-style optimization", or any long-horizon "make this artifact better and don't just memorize the dev set" task. Trigger it even when the user doesn't say "Arbor" or "hypothesis tree" but describes repeated experiment-and-evaluate loops, branching exploration of competing ideas, or worries about a dev/test gap. Runs Claude itself as the coordinator with subagent executors in isolated git worktrees; for the standalone `arbor` CLI tool see references/arbor-upstream.md.
-allowed-tools: Read Write Edit Bash Agent
-license: MIT license
-metadata:
-  version: "1.1"
-  skill-author: K-Dense Inc.
----
-
-# Arbor — Autonomous Optimization via Hypothesis Tree Refinement
-
-## Overview
-
-This skill runs an **Autonomous Optimization (AO)** loop: starting from an existing artifact and a measurable objective, improve it through many rounds of experiment and evaluation — without step-by-step human supervision and without overfitting to the feedback signal. It's the right tool when the bottleneck isn't writing one good change, but *organizing dozens of trials* so that lessons accumulate instead of evaporating.
-
-It implements **Hypothesis Tree Refinement (HTR)** from *Arbor* (Jin et al., 2026). The key idea: keep the research state in a persistent **hypothesis tree** rather than in conversation history. Each node binds a hypothesis, the distilled insight it produced, and a pointer to the artifact version that realizes it. You play the long-lived **coordinator** that owns this tree and decides where to search; short-lived **executor** subagents test one hypothesis each in isolated git worktrees and report back. A **held-out merge gate** admits a change only when it improves on a *test* evaluator the search never optimized against. This is what turns trial-and-error into cumulative, auditable research.
-
-Use the `scripts/tree.py` state manager for all the bookkeeping (creating nodes, writing evidence, propagating insights, pruning, the merge gate, the Observe projection). It keeps the state consistent and frees you to spend judgment on what the evidence *means*.
-
-## When to use this skill
-
-Reach for Arbor when the task is **iterative improvement of a concrete artifact under an evaluator**:
-- Model training: optimizer/architecture/recipe changes to lower loss or hit a target in fewer steps.
-- Harness/agent engineering: raising pass rate or accuracy of an agent loop, search harness, or tool-use scaffold.
-- Data synthesis: improving a generation/filtering pipeline judged by downstream model behavior.
-- Benchmark optimization: MLE-bench / Kaggle-style "improve the submission" tasks.
-- Prompt/system optimization where you can score outputs automatically.
-
-The distinguishing signals: there's an **artifact you can modify**, an **objective**, a way to **score** candidates, and you expect to run **many experiments**. If the user only wants a single fix or a one-shot answer, this is overkill — just do the work directly. If they want open-ended ideation with no evaluator, use `hypothesis-generation` or `scientific-brainstorming` instead.
-
-## The AO setup — pin this down first
-
-Before any experiments, establish the task tuple `(M_0, O, E_dev, E_test)`. Getting this right matters more than any later decision, so confirm it explicitly:
-
-- **M_0 — initial material**: the artifact to improve (a repo, a script, a config, a prompt). Make sure it's under git and currently runs.
-- **O — objective**: the natural-language goal and the metric *direction* (maximize accuracy? minimize loss/steps?).
-- **E_dev — development evaluator**: a command you can run freely during search to score a candidate. Fast, repeatable.
-- **E_test — held-out test evaluator**: a *separate* evaluator (different seeds, different split, or a larger run) used only at the merge gate. It must not be used as a search oracle — that's the whole point.
-
-If the user hasn't given you a clean dev/test split, **construct one and say so**. The dev/test separation is the mechanism that catches overfitting: a candidate that wins on dev but not on test isn't a success, it's a warning that you're exploiting the feedback signal. Without it, autonomous search reliably overfits.
-
-Initialize the run:
-
-```bash
-python scripts/tree.py init \
-  --objective "Improve BrowseComp answer accuracy on the search harness" \
-  --dev-eval "python eval.py --split dev --n 50" \
-  --test-eval "python eval.py --split test --n 300" \
-  --material "." --metric-direction max --branching 3 --max-depth 2 --budget 12
-```
-
-`--branching` is how many sibling hypotheses you propose per parent; `--max-depth 2` keeps directions at depth 1 and concrete interventions at depth 2 (the paper's default); `--budget` is the number of coordinator cycles. Start small (10–20 cycles) — structured search beats brute force, and you can extend if progress is still being made.
-
-## The coordinator loop
-
-You run repeated cycles of six steps. This is the heart of HTR; do not collapse it into ad-hoc editing. Run `python scripts/tree.py cycle` once per cycle to track the budget.
-
-### 1. Observe
-Begin every cycle by re-grounding in the tree, not in your memory of the conversation:
-
-```bash
-python scripts/tree.py observe
-```
-
-This prints the objective, global insights, the active frontier (selectable hypotheses), executed nodes with their evidence, pruned lessons (negative constraints), and the current best artifact. Treating the tree as the source of truth is what keeps you coherent over a long run, after context compression has thrown away the details.
-
-### 2. Ideate
-Pick a promising parent and propose a few child hypotheses under it. **Condition on the tree's evidence** — this is the difference between Arbor and random search:
-- Validated insights are assumptions you can build on.
-- Pruned nodes are dead ends to avoid.
-- A "half-right" result is a *starting point for a sharper hypothesis*, not a reason to abandon the direction.
-
-Each hypothesis should be a **falsifiable claim about how changing the artifact will move the metric**, not a vague intention. Depth-1 nodes are broad directions ("the search harness loses correct answers it already retrieved"); depth-2 nodes are concrete, executable interventions ("run K=5 independent rollouts and aggregate by evidence dossier instead of majority vote").
-
-```bash
-python scripts/tree.py add-node --parent n0 --hypothesis "Verification, not retrieval, is the bottleneck: candidates are found but discarded"
-python scripts/tree.py add-node --parent n4 --hypothesis "Decompose the question into atomic constraints and verify each independently"
-```
-
-### 3. Select
-Choose which pending leaves to run next. **Selection is not pure score-maximization** — pick a hypothesis because it has strong prior evidence, because it would resolve an ambiguity its siblings exposed, or because its failure would clarify an important assumption. Frontier control under delayed feedback rewards informative experiments, not just promising ones.
-
-### 4. Dispatch
-Run each selected hypothesis as an **executor subagent in an isolated worktree** (use the Agent tool with `isolation: "worktree"`, or have the executor create one with `git worktree add`). Isolation matters: parallel experiments must not clobber each other or the current best, and exploratory changes stay quarantined until they pass the merge gate.
-
-Dispatch siblings **in parallel** (multiple Agent calls in one message) when they're independent — comparative evidence within one direction is exactly what makes later pruning and abstraction possible.
-
-Give each executor a tight, **hypothesis-bound** brief. See `references/executor-brief.md` for the full template. The contract that makes HTR work: **the executor may not change the hypothesis when the metric stalls.** It repairs its own code and reruns, but `h_n` is fixed — otherwise the returned score is no longer evidence about the assigned node and the tree's semantics break. The executor returns exactly four things:
-- **dev_score** — the dev evaluator result (for selection);
-- **result** — a factual summary of what happened;
-- **insight** — the distilled, reusable lesson (*why* the result supports, weakens, or bounds the hypothesis);
-- **branch_ref** — the git branch/commit/worktree path holding the artifact.
-
-Mark a node `running` before dispatch (`tree.py set-status --node n5 --status running`) so the Observe projection stays accurate.
-
-### 5. Backpropagate
-When an executor returns, write its report into the node, then **abstract the lesson upward**:
-
-```bash
-python scripts/tree.py set-evidence --node n5 --dev-score 70.0 \
-  --result "K=5 dossier aggregation recovers answers in minority rollouts" \
-  --insight "Correct answers often appear in a minority of rollouts; aggregation beats majority vote" \
-  --branch-ref "wt/n5"
-
-python scripts/tree.py propagate --node n5 \
-  --insight "Candidate coverage, not verification, limits this direction" --to-root
-```
-
-This is the step that makes the tree more than a log. A leaf-level observation ("data-interface mismatch") should become a direction-level constraint and, if it generalizes, a global prior that shapes future ideation. **Insight propagation is the component that drives most of HTR's gains** — in the paper's MLE-Bench Lite ablation, a tree *without* insight feedback scored even lower than a flat experiment queue with no tree at all (54.5% vs. 63.6% any-medal, against 81.8% for the full system). Hierarchy alone isn't enough: the semantic memory is what matters. So spend real thought on the abstraction; don't just copy the leaf insight upward verbatim.
-
-### 6. Decide
-Decide what to do with the new evidence: keep expanding a direction, prune a falsified subtree, or attempt to merge a candidate.
-
-- **Prune** dead ends, recording *why* — the reason becomes a negative constraint:
-  ```bash
-  python scripts/tree.py prune --node n7 --reason "search-augmented judge overfits dev questions; no test transfer"
-  ```
-- **Merge gate** — promote a candidate to the new best **only if it improves on `E_test`**. Run the test evaluator in a *fresh* worktree (not the dev worktree, to avoid leakage), then:
-  ```bash
-  python scripts/tree.py merge --node n5 --test-score 67.67 --branch-ref "wt/n5"
-  ```
-  If the gate rejects it, that's informative: a high-dev / low-test candidate is evidence the direction may be exploiting the dev signal rather than producing a transferable improvement. Record that lesson; don't quietly promote it anyway.
-
-Repeat until the budget is spent, the frontier is exhausted, or progress has clearly stalled.
-
-## Finishing the run
-
-When you stop, produce a short report (see `references/report-template.md`) covering:
-- the final best artifact, its test score, and its delta over `M_0`;
-- the tree (`python scripts/tree.py status`) as the audit trail of what was tried;
-- the main hypothesis shifts — how task understanding deepened across the run (early nodes test broad mechanisms; later nodes find their limits; ancestor insights compress these into the constraints behind the final design);
-- merged vs. explored: many nodes improve dev, far fewer pass the test gate — report that gap honestly rather than overstating dev wins.
-
-Always leave `M_best` as a real, runnable artifact on a named branch, and tell the user how to check it out.
-
-## Principles that make this work (not rote rules)
-
-These come from the paper's analysis; understanding *why* matters more than following them mechanically.
-
-- **The tree is the memory; conversation is not.** Over a long horizon your context gets compressed. Re-Observe each cycle so decisions rest on durable evidence, not a lossy summary.
-- **Structured search, not more sampling.** Arbor's gains come from how the budget is *organized* — maintaining competing hypotheses, comparing siblings, carrying lessons forward — not from spending more tokens. Don't fan out aimlessly; each experiment should be conditioned on what the tree already knows.
-- **Dev guides, test admits.** Use dev feedback freely to steer exploration, but never let a dev win into the final artifact without test confirmation. The dev/test disagreement is itself a signal worth reading.
-- **Executors are hypothesis-bound.** Local engineering flexibility (edit, debug, rerun) is fine; silently changing the hypothesis to chase a better number is not — it destroys the meaning of the evidence.
-- **Failures are constraints, not noise.** A falsified hypothesis tells you what the solution must avoid. Pruned-with-a-reason is more valuable than pruned-and-forgotten.
-
-## Reference files
-
-- `references/htr-methodology.md` — deeper explanation of HTR, the node structure, the six steps, and the paper's empirical lessons (ablations, transfer, cost). Read when you want the rationale behind a design choice.
-- `references/executor-brief.md` — the template for the brief you hand each executor subagent.
-- `references/report-template.md` — the final-report structure.
-- `references/arbor-upstream.md` — how to install and run the standalone `arbor` CLI from RUC-NLPIR/Arbor instead of orchestrating it natively, and when to prefer each.