@pikaa-ai/pikaa 0.3.22 → 0.3.24

package/skills/waypoint-bio/SKILL.md

@@ -1,273 +0,0 @@
----
-name: waypoint-bio
-description: Use when working with Outpost Bio's open microbiome foundation models - the Waypoint checkpoints (Waypoint-6m, Waypoint-45m, Waypoint-170m), the Atlas pretraining corpus, the Compass eight-task benchmark, or the `waypoint` CLI from the `waypoint-bio` package. Covers embedding microbiome samples, fine-tuning on taxonomic abundance data, benchmarking a checkpoint on Compass, pretraining a GPT-2 model on taxonomic abundance profiles, and converting MetaPhlAn, Kraken2, QIIME 2, or MGnify abundance tables into waypoint format.
-license: MIT
-compatibility: Requires Python 3.10+ with `waypoint-bio` (pulls torch, transformers, datasets, peft, scikit-learn). Needs network access and a Hugging Face token with access granted to the gated outpost-bio repos. A GPU is strongly recommended for pretraining and benchmarking.
-metadata:
-  version: "1.0"
-  skill-author: K-Dense Inc.
-  upstream-version: "waypoint-bio 1.0.2 (PyPI); GitHub main 1.0.4"
-  last-reviewed: "2026-08-17"
-  openclaw:
-    primaryEnv: HF_TOKEN
-    envVars:
-      - name: HF_TOKEN
-        required: true
-        description: Hugging Face read token with access to the gated outpost-bio/Waypoint-*, outpost-bio/Atlas, and outpost-bio/Compass repos.
----
-
-# Waypoint: Outpost Bio's Open Microbiome Foundation Models
-
-## Overview
-
-Outpost Bio open-sourced three artefacts under Apache 2.0, described in
-[Treloar et al., bioRxiv 2026.05.02.722381](https://www.biorxiv.org/content/10.64898/2026.05.02.722381v2):
-
-| Artefact | What it is | Hugging Face |
-| --- | --- | --- |
-| **Waypoint** | GPT-2-style causal LMs over taxonomic tokens, 6M–170M params | `outpost-bio/Waypoint-6m`, `-45m`, `-170m` |
-| **Atlas** | 539,308 microbiome samples scraped from MGnify (485,377 pretrain / 53,931 benchmark) | `outpost-bio/Atlas` |
-| **Compass** | Eight downstream tasks over four studies | `outpost-bio/Compass` |
-
-The unifying idea: a microbiome sample is a *sentence*. Each taxon is one token, tokens are ordered
-by descending abundance z-score, and the model is trained with next-token prediction. A pretrained
-checkpoint then supplies sample-level embeddings or a fine-tuning backbone for prediction tasks.
-
-All of it is driven by one CLI, `waypoint`, with five subcommands: `prepare-dataset`, `embed`,
-`finetune`, `benchmark`, `pretrain`.
-
-## When to use
-
-- Embedding 16S/shotgun taxonomic profiles into fixed-size vectors for clustering, visualisation, or
-  a downstream classifier.
-- Fine-tuning a Waypoint checkpoint to predict a phenotype, treatment, or continuous readout from
-  community composition.
-- Scoring your own microbiome model against Compass so the number is comparable to the paper.
-- Pretraining a taxonomic language model on Atlas or on your own corpus.
-- Converting profiler output (MetaPhlAn, Kraken2/Bracken, QIIME 2, MGnify TSVs) into the input format
-  these tools expect.
-
-**Do not reach for this** when you have fewer than ~1,000 labelled samples — see
-[Scientific caveats](#scientific-caveats). A random forest on relative abundances is the better tool
-there, and the paper says so.
-
-## Setup
-
-```bash
-pip install waypoint-bio       # installs the `waypoint` command
-```
-
-Atlas, Compass, and every Waypoint checkpoint are **gated**. Access is auto-approved, but you must
-click through once per repo and then authenticate:
-
-1. Request access on each repo page you need: [Waypoint-6m](https://huggingface.co/outpost-bio/Waypoint-6m),
-   [Waypoint-45m](https://huggingface.co/outpost-bio/Waypoint-45m),
-   [Waypoint-170m](https://huggingface.co/outpost-bio/Waypoint-170m),
-   [Atlas](https://huggingface.co/datasets/outpost-bio/Atlas),
-   [Compass](https://huggingface.co/datasets/outpost-bio/Compass).
-2. Authenticate locally:
-
-   ```bash
-   hf auth login          # or: export HF_TOKEN=hf_...
-   ```
-
-A 401/403 from any subcommand almost always means access was never requested on that specific repo —
-a token alone is not enough. Use a read-scoped token. The tokenizer loads via
-`trust_remote_code=True`, so pin a `revision` if you need the remote code fixed across runs.
-
-## The waypoint data format
-
-Everything except `prepare-dataset` consumes **waypoint format**: a `.parquet` / `.csv` / `.tsv`
-whose rows are samples, with two aligned list-columns plus any label columns you need.
-
-| Column | Type | Notes |
-| --- | --- | --- |
-| `Taxa` | `list[str]` | Full lineage strings, `;`-separated: `k__Bacteria; p__Firmicutes; ...; g__Lactobacillus` |
-| `Relative Abundances` | `list[float]` | Same length as `Taxa`, same order |
-| *(any)* | scalar | Targets, covariates, or a `Split` column |
-
-Prefer parquet. CSV/TSV stores the lists as `repr` strings and round-trips through `ast.literal_eval`.
-
-**Give full lineages, not bare names.** The tokenizer extracts the genus segment (`g__`) from each
-lineage and falls back to the most specific higher rank when genus is missing. Bare names disable
-that fallback entirely.
-
-## Workflow
-
-### 1. Get your data into waypoint format
-
-If you already have a sample × taxa (or taxa × sample) abundance matrix with lineage labels:
-
-```bash
-waypoint prepare-dataset \
-    --input abundance_matrix.tsv \
-    --metadata sample_labels.csv \
-    --output dataset.parquet
-```
-
-Orientation is auto-detected from the first column header (`taxonomy`, `lineage`, `taxon`, `otu`,
-`#otu id` ⇒ taxa-as-rows); override with `--orientation`. Rows are normalised to sum to 1 unless you
-pass `--no_normalize`, and zeros are dropped unless you pass `--keep_zeros`.
-
-`prepare-dataset` cannot read profiler output directly — MetaPhlAn uses `|` separators, Kraken2
-reports encode the hierarchy as indentation, and QIIME 2/SILVA prefixes the domain `d__` instead of
-`k__` (which the tokenizer silently ignores). Use the bundled converter for those:
-
-```bash
-python scripts/profiler_to_waypoint.py \
-    --input merged_metaphlan.tsv --format metaphlan \
-    --output dataset.parquet
-
-python scripts/profiler_to_waypoint.py \
-    --input reports/*.kreport --format kraken \
-    --output dataset.parquet
-
-python scripts/profiler_to_waypoint.py \
-    --input feature-table.tsv --format qiime2 \
-    --output dataset.parquet
-```
-
-See `references/data-preparation.md` for every input layout, rank handling, and the `d__`/`|` gotchas.
-
-### 2. Check vocabulary coverage before anything else
-
-Waypoint's vocabulary is fixed at pretraining time from Atlas. Taxa absent from it become `<unk>` and
-are **silently dropped** by `waypoint embed`; the paper names this as the models' main limitation. A
-sample whose taxa are all out-of-vocabulary yields a degenerate `[BOS][EOS]` embedding.
-
-```bash
-python scripts/vocab_coverage.py --model outpost-bio/Waypoint-6m --data dataset.parquet
-```
-
-It reports per-sample and abundance-weighted coverage and flags samples below a threshold. Treat
-median abundance-weighted coverage under ~0.8 as a reason to re-examine your taxonomy labels before
-trusting any downstream number.
-
-### 3. Embed samples
-
-```bash
-waypoint embed \
-    --model outpost-bio/Waypoint-6m \
-    --data dataset.parquet \
-    --output embeddings.parquet
-```
-
-Output is indexed by sample ID with columns `dim_0 … dim_{H-1}` (`H` = 256 for 6m, 512 for 45m,
-768 for 170m). Defaults: `--pooling last_token`, `--batch_size 32`, `--max_length 512`, device
-auto-detected (`cuda` → `mps` → `cpu`).
-
-Keep `--pooling last_token` unless you have a reason to change it: it matches how the checkpoints
-were pretrained and how `benchmark` and `finetune` pool. `mean` is a reasonable alternative for
-unsupervised use; `first_token`/`cls_token` return the BOS position and carry little signal in a
-causal LM.
-
-### 4. Fine-tune on your labels
-
-```bash
-# classification
-waypoint finetune \
-    --model outpost-bio/Waypoint-45m \
-    --data dataset.parquet \
-    --output_dir outputs/ft_disease \
-    --task_type classification \
-    --target "Disease Status" \
-    --config configs/finetune_classification.yaml
-
-# regression, with a categorical covariate one-hot appended to the pooled embedding
-waypoint finetune \
-    --model outpost-bio/Waypoint-45m \
-    --data dataset.parquet \
-    --output_dir outputs/ft_degradation \
-    --task_type regression \
-    --target "Degradation Rate" \
-    --covariate_column Drug \
-    --config configs/finetune_regression.yaml
-```
-
-Config paths resolve against the bundled `waypoint_bio/configs/` tree, so `configs/...` works from
-any directory without cloning.
-
-Defaults worth overriding for small datasets: `warmup_steps: 1000` (drop to ~50 so warmup finishes
-before early stopping), `num_epochs: 1` in the shipped configs (raise it — early stopping on
-validation loss is what actually terminates training), and `use_lora: true` when VRAM is tight
-(~1% of parameters trained; adapters are merged back before saving, so the checkpoint stays a plain
-`AutoModel`).
-
-Splits default to a random 80/10/10. **Set `split_column` to a `Split` column whenever samples are
-correlated** — repeated measures, one donor sampled over time, technical replicates — or a random
-split leaks and the test score is meaningless.
-
-Outputs land in `--output_dir`: `best_model/` (loadable by `embed`/`benchmark`),
-`test_metrics.json`, `training_log.csv` + `.html`, and `finetune_results.json`.
-
-### 5. Benchmark on Compass
-
-```bash
-waypoint benchmark --model outpost-bio/Waypoint-6m --output_dir outputs/benchmark
-waypoint benchmark --model outputs/pretrain/best_model --tasks 1 6 --output_dir outputs/smoke
-```
-
-Fine-tunes a fresh head per task and writes `benchmark_results.json`. Classification tasks score
-macro-F1; the one regression task scores R² clamped to [0, 1]; `final_score` is the unweighted mean
-across tasks. Full task table, metric keys, and result-file schema: `references/compass-benchmark.md`.
-
-### 6. Pretrain
-
-```bash
-waypoint pretrain \
-    --model_config configs/models/gpt2-45m.yaml \
-    --pretrain_config configs/pretraining.yaml \
-    --output_dir outputs/pretrain_45m
-```
-
-Downloads Atlas, builds a taxonomic tokenizer from the corpus, computes per-token abundance
-mean/std for z-score ordering, then trains with next-token prediction and early stopping. Add
-`--data my_corpus.parquet` to pretrain on your own waypoint-format corpus instead, and
-`--max_samples N` for a smoke test.
-
-Nine architectures ship, from `gpt2-6m.yaml` (8 layers, 256 hidden) to `gpt2-170m.yaml` (24 layers,
-768 hidden); per-head dimension is fixed at 64 throughout. `references/cli-reference.md` has the
-full table and every config key.
-
-## Scientific caveats
-
-These are load-bearing. Ignoring them produces numbers that look fine and mean nothing.
-
-- **Below ~1,000 labelled examples, Waypoint underperforms a random forest on raw abundances.** The
-  paper's crossover against the RF baseline sits near **10,000** training examples. Fit the baseline
-  first; only adopt the transformer if it wins on your data.
-- **Out-of-vocabulary taxa are dropped, not flagged.** Every Compass dataset carries some. Run
-  `scripts/vocab_coverage.py` and report the coverage alongside your results.
-- **45M, not 170M, was the best benchmark model.** Pretraining loss keeps falling with scale, but
-  downstream Compass score does not — start at 6m or 45m and only scale up if it demonstrably helps.
-- **Genus-level tokenisation is the default**, so species-level distinctions are collapsed. Changing
-  `taxon_rank` requires re-pretraining, not just re-tokenising.
-- **Compositional data.** Relative abundances are constrained to sum to 1; differences in one taxon
-  induce apparent changes in others. This affects interpretation of any per-taxon attribution.
-- **Batch and study effects dominate microbiome data.** Atlas spans MGnify pipelines v1.0–v5.0 and
-  four sequencing modalities. Never let a study or run boundary coincide with your label boundary.
-- **Not a clinical or diagnostic tool.** The model cards state this explicitly.
-
-## References
-
-- `references/cli-reference.md` — every subcommand flag, every config key, the model-size table.
-- `references/compass-benchmark.md` — the eight tasks, filters, metrics, `benchmark_results.json` schema.
-- `references/data-preparation.md` — waypoint format, profiler conversions, taxonomy string rules.
-- `references/python-api.md` — using the tokenizer, datasets, heads, and checkpoints from Python.
-
-## Scripts
-
-- `scripts/profiler_to_waypoint.py` — MetaPhlAn / Kraken2 / QIIME 2 / generic lineage tables → waypoint format.
-- `scripts/vocab_coverage.py` — tokenizer coverage report for a waypoint-format file.
-
-## Upstream
-
-Code [github.com/Outpost-Bio/waypoint](https://github.com/Outpost-Bio/waypoint) ·
-package `waypoint-bio` ·
-paper [bioRxiv 2026.05.02.722381](https://www.biorxiv.org/content/10.64898/2026.05.02.722381v2) ·
-community [Waypoint Slack](https://join.slack.com/t/outpostbio-waypoint/shared_invite/zt-3w6ivgtba-WJOCkdxiISxQpwVq9ZZxTA) ·
-contact `waypoint@outpost.bio`.
-
-Cite Treloar, N. J., Ur-Rehman, S., Yang, J., & Outpost Bio (2026). *Learning the Language of the
-Microbiome with Transformers.* bioRxiv. Per-artefact DOIs are listed at
-[outpost.bio/citations](https://www.outpost.bio/citations).

package/skills/what-if-oracle/SKILL.md

@@ -1,184 +0,0 @@
----
-name: what-if-oracle
-description: Run structured What-If scenario analysis with 4–6 branch possibility exploration (best, likely, worst, wild card, contrarian, second-order). Use when the user asks speculative what-if questions about uncertain futures, strategic forks, contingency planning, or stress-testing a decision before committing.
-license: CC BY-NC-SA 4.0
-metadata:
-  version: "1.1"
-  skill-author: AHK Strategies (ashrafkahoush-ux)
-  upstream: https://github.com/ashrafkahoush-ux/claude-consciousness-skills
-  research-doi: 10.5281/zenodo.18736841, 10.5281/zenodo.18807387
----
-
-# What-If Oracle — Possibility Space Explorer
-
-A structured system for exploring uncertain futures through rigorous multi-branch scenario analysis. Instead of one prediction, the Oracle maps the full **possibility space** — branching timelines where each path has its own logic, probability, and consequences.
-
-Based on the What-If Paradigm: the idea that speculative questions ("What if X?") are not idle daydreaming but a **fundamental computing operation** — the mind's way of simulating futures before committing resources to one.
-
-Published research: [The What-If Paradigm (DOI: 10.5281/zenodo.18736841)](https://doi.org/10.5281/zenodo.18736841) | [IDNA v2 / Unified Digital Consciousness Theory (DOI: 10.5281/zenodo.18807387)](https://doi.org/10.5281/zenodo.18807387)
-
-## When to Use This Skill
-
-Use the Oracle when the user:
-
-- Asks "what if…", "what would happen if…", or "explore the possibilities"
-- Faces a fork-in-the-road decision with no obvious answer
-- Wants best-case / worst-case / likely-case analysis with probabilities
-- Needs contingency planning, risk mapping, or strategic option comparison
-- Wants to stress-test an idea or think through second-order consequences
-
-For domain-specific framing (startup, tech architecture, crisis response, etc.), see [references/scenario-templates.md](references/scenario-templates.md).
-
-## Core Principle: 0·IF·1
-
-Every scenario analysis has three elements:
-
-- **0** — The unexpressed state (what hasn't happened yet, the potential)
-- **1** — The expressed state (what IS, the current reality)
-- **IF** — The conditional bond (the decision, event, or change that transforms 0 into 1)
-
-The quality of the analysis depends on the precision of the IF. A vague "what if things go wrong?" produces vague results. A precise "what if our primary supplier raises prices 30% in Q3?" produces actionable intelligence.
-
-## How to Run the Oracle
-
-### Phase 1 — Frame the Question
-
-Take the user's What-If question and sharpen it:
-
-**Decompose into components:**
-
-- **The Variable:** What specific thing changes? (one variable per analysis)
-- **The Magnitude:** By how much? (quantify if possible)
-- **The Timeframe:** Over what period?
-- **The Context:** What's the current state before the change?
-
-**If the question is vague, sharpen it:**
-
-- "What if AI takes over?" → "What if 40% of current knowledge-work tasks are automated by AI within 3 years in [specific industry]?"
-- "What if we fail?" → "What if monthly revenue stays below $5K for 6 consecutive months starting now?"
-
-Present the sharpened question to the user for confirmation before proceeding.
-
-### Phase 2 — Map the Possibility Space
-
-Generate **4-6 scenario branches** using this framework:
-
-| Branch             | Definition                                                                   | Purpose                                            |
-| ------------------ | ---------------------------------------------------------------------------- | -------------------------------------------------- |
-| **Ω Best Case**    | Everything goes right. Key assumptions all validate. Lucky breaks occur.     | Define the ceiling — what's the maximum upside?    |
-| **α Likely Case**  | Most probable path given current evidence. No major surprises.               | Anchor expectations in reality                     |
-| **Δ Worst Case**   | Key assumptions fail. Two things go wrong simultaneously.                    | Define the floor — what's the maximum downside?    |
-| **Ψ Wild Card**    | An unexpected variable enters that nobody is tracking. Black swan territory. | Stress-test for the unimaginable                   |
-| **Φ Contrarian**   | The opposite of the consensus view turns out to be true.                     | Challenge groupthink and reveal hidden assumptions |
-| **∞ Second Order** | The first-order effects trigger cascading consequences nobody predicted.     | Map the ripple effects                             |
-
-### Phase 3 — Analyze Each Branch
-
-For each scenario branch, provide:
-
-```
-╔══════════════════════════════════════════════╗
-║  BRANCH: [Ω/α/Δ/Ψ/Φ/∞] — [Branch Name]    ║
-╠══════════════════════════════════════════════╣
-║  Probability: [X%]                           ║
-║  Timeframe: [When this could materialize]    ║
-║  Confidence: [HIGH/MEDIUM/LOW]               ║
-╠══════════════════════════════════════════════╣
-║  NARRATIVE:                                  ║
-║  [2-3 sentences describing how this          ║
-║   scenario unfolds step by step]             ║
-║                                              ║
-║  KEY ASSUMPTIONS:                            ║
-║  • [What must be true for this to happen]    ║
-║  • [And this]                                ║
-║                                              ║
-║  TRIGGER CONDITIONS:                         ║
-║  • [Early signal that this branch is         ║
-║    becoming reality]                         ║
-║  • [Second signal]                           ║
-║                                              ║
-║  CONSEQUENCES:                               ║
-║  → Immediate: [What happens first]           ║
-║  → 30 days: [What follows]                   ║
-║  → 6 months: [Where it leads]               ║
-║                                              ║
-║  REQUIRED RESPONSE:                          ║
-║  [What action to take if this branch         ║
-║   activates — specific, actionable]          ║
-║                                              ║
-║  WHAT MOST PEOPLE MISS:                      ║
-║  [The non-obvious insight about this         ║
-║   scenario that conventional analysis        ║
-║   would overlook]                            ║
-╚══════════════════════════════════════════════╝
-```
-
-### Phase 4 — Synthesis
-
-After analyzing all branches, provide:
-
-**Probability Distribution:**
-
-```
-Ω Best Case ····· [██████░░░░] 15%
-α Likely Case ··· [████████░░] 45%
-Δ Worst Case ···· [██████░░░░] 20%
-Ψ Wild Card ····· [███░░░░░░░]  8%
-Φ Contrarian ···· [████░░░░░░]  7%
-∞ Second Order ·· [███░░░░░░░]  5%
-```
-
-**Robust Actions:** What actions are beneficial across MULTIPLE branches? These are the no-regret moves — do them regardless of which future materializes.
-
-**Hedge Actions:** What preparations protect against the worst branches without sacrificing upside?
-
-**Decision Triggers:** What specific, observable signals should cause you to update which branch is most likely? Define the tripwires.
-
-**The 1% Insight:** What is the one thing about this situation that almost everyone analyzing it would miss? The non-obvious pattern, the hidden assumption, the overlooked variable.
-
-## Golden Ratio Weighting
-
-When evidence exists, weight primary scenarios using the golden ratio:
-
-- **Primary future (most likely):** 61.8% of attention/resources
-- **Alternative future:** 38.2% of attention/resources
-
-This prevents both overcommitment to a single path and dilution across too many contingencies. Nature uses this ratio for branching (trees, rivers, blood vessels). Strategic planning can too.
-
-## Modes
-
-### Quick Oracle (2-3 minutes)
-
-3 branches only: Best, Likely, Worst. Short narratives. For fast decisions.
-
-### Deep Oracle (5-10 minutes)
-
-All 6 branches. Full analysis with consequences, triggers, and synthesis. For high-stakes decisions.
-
-### Scenario Chain
-
-Take the output of one Oracle analysis and feed it into another. "If Branch Δ happens, what are the possibilities WITHIN that branch?" Recursive depth for complex strategic planning.
-
-### Reverse Oracle
-
-Start from a desired outcome and work backward: "What conditions must be true for X to happen? What's the most likely path TO that outcome?" Useful for goal-setting and strategy design.
-
-### Competitive Oracle
-
-Analyze the same What-If from multiple stakeholder perspectives: "If we launch this product, what does the possibility space look like from OUR perspective vs. THEIR perspective vs. THE MARKET's perspective?"
-
-## What This Is NOT
-
-- Not a prediction — it's a possibility map. The Oracle doesn't claim to know the future; it helps you prepare for multiple futures.
-- Not a crystal ball — probabilities are estimates based on available evidence, not certainties.
-- Not a substitute for action — the best scenario analysis in the world is worthless without subsequent decision and execution.
-
-## Reference Files
-
-| File | Purpose |
-| ---- | ------- |
-| [references/scenario-templates.md](references/scenario-templates.md) | Domain-specific templates (startup, tech, finance, crisis, etc.) and probability calibration |
-
-## License
-
-© 2026 Ashraf Hussein Kahoush / AHK Strategies. Licensed under CC BY-NC-SA 4.0. Free for personal, educational, and research use. Commercial use requires a license from the author.

package/skills/writing-plans/SKILL.md

@@ -1,15 +0,0 @@
----
-name: writing-plans
-description: "Formulate atomic, phased implementation plans for multi-step tasks before touching source code."
-risk: low
-source: built-in
----
-
-# Writing Implementation Plans
-
-## Guidelines
-
-1. **Understand requirements**: Clarify ambiguities before finalizing plan structure.
-2. **Break into atomic steps**: Each step should be testable independently.
-3. **Specify file paths**: List exact target files and functions to modify.
-4. **Define verification criteria**: Every task must have an automated test or verification step.

package/skills/xlsx/SKILL.md

@@ -1,110 +0,0 @@
----
-name: xlsx
-description: "Create, edit, analyze, or convert Excel spreadsheets (.xlsx, .xlsm, .xltx) where the workbook file is the primary deliverable. Use for formulas, formatting, financial models, multi-sheet workbooks, and tabular cleanup exported to Excel. Also applies to .csv/.tsv when the user wants spreadsheet output. Do NOT use for Word documents, HTML reports, standalone Python scripts, database pipelines, or Google Sheets API work."
-allowed-tools: Read Write Edit Bash Grep Glob
-license: Proprietary. LICENSE.txt has complete terms
-metadata:
-  version: "2.2"
-  skill-author: Anthropic, PBC
-  adapted-by: K-Dense Inc.
-  source: https://github.com/anthropics/skills/tree/main/skills/xlsx
-compatibility: Requires Python 3.8+, LibreOffice (soffice on PATH), and gcc only when Unix sockets are restricted
----
-
-# XLSX creation, editing, and analysis
-
-| Task | Approach |
-|---|---|
-| **Create** or **edit** with formulas/formatting | `openpyxl` — see gotchas below |
-| **Bulk data** in or out | `pandas` (`read_excel`, `to_excel`) |
-| **Quick look** at a sheet | `markitdown file.xlsx` — `## SheetName` per sheet; reads `.xlsm` too. No cell coordinates, so don't plan edits from it |
-| **Read** a model (formulas *and* values) | two `load_workbook` passes — see gotchas |
-
-> `openpyxl`, `pandas`, and `markitdown` are preinstalled — do not run `uv pip install` first; write the script and import directly. Only if an import fails (or the `markitdown` command is missing): `uv pip install` the missing package.
-
-> Script paths below are relative to this skill's directory.
-
-## Requirements for every output
-
-- **Professional font** (Arial, Times New Roman) throughout, unless the user says otherwise.
-- **Zero formula errors.** Never ship while `recalc.py` reports `errors_found`. If you think an error predates you, prove it: load the *original* with `data_only=True` and look at that cell. An error you introduced looks exactly like one you inherited.
-- **Use formulas, never hardcoded results.** Write `sheet['B10'] = '=SUM(B2:B9)'`, not the Python-computed total. The sheet must recalculate when its inputs change.
-- **Follow the user's spec literally.** Exact tab names, exact column headers, and the formula they spelled out. A redesign that computes something else fails, however elegant.
-- **Document every assumption and hardcoded number** where the reader will see it — a cell comment, or an adjacent cell at a table's end. Cite a real source when one exists (`Source: Company 10-K, FY2024, Page 45, Revenue Note, [SEC EDGAR URL]`); when the number came from the user, say so plainly.
-- **A workbook *you create* for someone to fill in** needs a short legend naming which cells to edit, and one example row of realistic values showing the expected format. Never add such a row to a file you were asked to edit.
-- **Editing an existing file: match its conventions exactly.** They override every guideline here. Find its designated input cells first — a distinct font color, fill, or shading marks them — write only there, and leave every existing formula untouched.
-
-## Recalculate (mandatory whenever the file contains formulas)
-
-openpyxl writes formulas as strings with **no cached values**. Until you recalculate, every
-formula cell reads back as `None` to anything reading cached values — `pandas`,
-`load_workbook(data_only=True)`, and most previewers.
-
-```bash
-python scripts/recalc.py output.xlsx [timeout_seconds]   # default 30
-```
-
-LibreOffice computes every formula, the file is **rewritten in place**, and you get JSON:
-`status` (`success` | `errors_found`), `total_formulas`, `total_errors`, and an
-`error_summary` naming up to 100 cells per error type (`locations_truncated` says how many it
-withheld — trust `total_errors`, not the length of the list). Fix what it names and run it
-again. **JSON with an `error` key instead of a `status` means nothing was recalculated**, and
-only that case exits non-zero — `errors_found` exits 0, so never treat a clean exit as a clean
-workbook.
-
-**A green recalc proves your formulas *evaluate*, not that they are *right*.** An off-by-one
-range or a reference to the wrong row yields a clean, error-free file with wrong numbers.
-Write 2–3 formulas first and check they pull the values you expect, before building out a grid.
-
-**A workbook that links to another file loses those links** if you re-save it with openpyxl and
-then recalculate. Such a formula reads `='[1]Returns Analysis'!$B$2` — the `[1]` is an index
-into the workbook's external-reference list, naming a *separate file on disk*, not a sheet.
-That file is rarely present here, so the cell's cached value is the only thing holding its
-data. openpyxl strips that value on save; LibreOffice then has to resolve the reference for
-real, fails, writes `#NAME?`, and deletes every link. `recalc.py` refuses to run in that state
-— copy those cells' values out of the original before you save over them (`--force` overrides,
-and accepts the loss).
-
-## Choosing formulas that survive verification
-
-LibreOffice implements fewer functions than Excel, and one it cannot evaluate becomes a
-literal `#NAME?` baked into the file you deliver.
-
-- **Prefer Excel-2007-era functions** — `SUMIFS`, `INDEX`, `MATCH`, `IFERROR`, `SUMPRODUCT` — which need no prefix.
-- **Six post-2007 functions work, but only with an `_xlfn.` prefix**, because openpyxl writes your formula into the XML verbatim and Excel stores post-2007 names prefixed (its UI hides the prefix): `_xlfn.TEXTJOIN`, `_xlfn.CONCAT`, `_xlfn.IFS`, `_xlfn.SWITCH`, `_xlfn.MAXIFS`, `_xlfn.MINIFS`. Written bare, each yields `#NAME?`.
-- **Never use `XLOOKUP`, `XMATCH`, `SORT`, `FILTER`, `UNIQUE`, or `SEQUENCE`.** The runtime's LibreOffice cannot evaluate them under *any* prefix. Newer builds do evaluate them, but they are spilling array functions and an openpyxl-written file has no spill metadata, so only the top-left cell of the range gets a value — and `recalc.py` reports `total_errors: 0` on the truncated result. Use `INDEX`/`MATCH` for lookups, and sort, filter, and de-duplicate in Python before writing the cells.
-- A formula LibreOffice could not parse is written back **lowercased** — a quick tell beside a `#NAME?`.
-
-## openpyxl gotchas
-
-- **Reading a model takes two loads.** `data_only=True` yields cached values with the formulas gone; the default yields formula strings with no values. One pass cannot give you both.
-- **`data_only=True` is destructive if you save.** That workbook has no formulas left, so saving replaces every one with a literal — permanently.
-- **`data_only=True` on a file openpyxl just wrote returns `None` everywhere** — run `recalc.py` first. (A formula whose result is `""` also reads back as `None`.)
-- **Merged cells: write the top-left anchor only.** Every other cell in the range is a `MergedCell` whose `.value` is read-only.
-- **`.xlsm` loses its macros unless you pass `keep_vba=True`** to `load_workbook`.
-- **A sheet name containing a space must be quoted** in a cross-sheet reference: `='Assumptions Inputs'!$B$5`. Unquoted, it evaluates to `#VALUE!`.
-
-## Financial models
-
-Unless the user says otherwise, or the existing file already does something else.
-
-**Color:** blue text (`0,0,255`) for hardcoded inputs and scenario levers · black for formulas ·
-green (`0,128,0`) for links to another sheet · red (`255,0,0`) for links to another file ·
-yellow fill (`255,255,0`) for key assumptions and cells the user should fill in.
-
-**Numbers:** currency `$#,##0`, with the unit named in the header (`Revenue ($mm)`) · zeros
-render as `-`, including in percentages (`$#,##0;($#,##0);-`) · negatives in parentheses ·
-percentages `0.0%`, **stored as fractions** (`0.15` renders `15.0%`; storing `15` renders
-`1500.0%`) · valuation multiples `0.0x` · years as text (`"2024"`, never `2,024`).
-
-**Structure:** every assumption in its own labeled cell, referenced by the formulas that use it
-(`=B5*(1+$B$6)`, never `=B5*1.05`) · formulas consistent across every projection period, since a
-lone edited cell mid-row is the commonest silent error · guard denominators that can be zero.
-
-## Dependencies
-
-`openpyxl`, `pandas`, `markitdown` (pip, preinstalled — install only if an import fails or the command is missing) · LibreOffice (`soffice`, auto-configured for sandboxed environments via `scripts/office/soffice.py`)
-
----
-
-*This skill is created and maintained by [Anthropic](https://github.com/anthropics/skills/tree/main/skills/xlsx). Vendored here unmodified except for frontmatter metadata; see LICENSE.txt for terms.*