lightcone-cli 0.2.0__py3-none-any.whl

lightcone/cli/claude/lightcone/skills/lc-build/scripts/setup-lc-build.sh

@@ -0,0 +1,240 @@
+#!/bin/bash
+# Setup script for lc-build skill
+# Two modes: --validate (pre-planning) and --activate (post-approval)
+
+set -euo pipefail
+
+MODE=""
+UNIVERSE="baseline"
+MAX_ITERATIONS=25
+MAX_ITERATIONS_EXPLICIT=false
+while [[ $# -gt 0 ]]; do
+    case "$1" in
+        --validate) MODE="validate"; shift ;;
+        --activate) MODE="activate"; shift ;;
+        --resume) MODE="resume"; shift ;;
+        --universe)
+            UNIVERSE="$2"
+            shift 2
+            ;;
+        --max-iterations)
+            MAX_ITERATIONS="$2"
+            MAX_ITERATIONS_EXPLICIT=true
+            shift 2
+            ;;
+        *)
+            echo "Unknown argument: $1" >&2
+            echo "Usage: setup-lc-build.sh --validate|--activate|--resume --universe NAME --max-iterations N" >&2
+            exit 1
+            ;;
+    esac
+done
+
+if [[ -z "$MODE" ]]; then
+    echo "Error: must specify --validate or --activate" >&2
+    exit 1
+fi
+
+# Validate universe name — must be safe for sed substitution and file paths
+if [[ ! "$UNIVERSE" =~ ^[a-zA-Z0-9_-]+$ ]]; then
+    echo "Error: Universe name must contain only letters, numbers, underscores, and hyphens." >&2
+    echo "Got: '${UNIVERSE}'" >&2
+    exit 1
+fi
+
+# ─── Validate mode ───────────────────────────────────────────────────
+
+if [[ "$MODE" == "validate" ]]; then
+
+    # Check astra.yaml exists
+    if [[ ! -f "astra.yaml" ]]; then
+        echo "Error: astra.yaml not found in $(pwd)"
+        echo "Run /lc-new to create an analysis specification first."
+        exit 1
+    fi
+
+    # Check astra CLI available
+    if ! command -v astra &>/dev/null; then
+        echo "Error: astra CLI not found. Run: pip install astra"
+        exit 1
+    fi
+
+    # Validate spec
+    echo "Validating astra.yaml..."
+    validation_output=$(astra validate astra.yaml 2>&1) || {
+        echo "Validation failed:"
+        echo "$validation_output"
+        echo ""
+        echo "Fix validation errors before building."
+        exit 1
+    }
+    echo "Validation: passed"
+
+    # Check/create universe
+    if [[ ! -f "universes/${UNIVERSE}.yaml" ]]; then
+        echo "Universe '${UNIVERSE}' does not exist. Creating..."
+        astra universe generate -n "$UNIVERSE" 2>&1
+        echo "Universe created: universes/${UNIVERSE}.yaml"
+    else
+        echo "Universe: ${UNIVERSE} (exists)"
+    fi
+
+    # Check lc CLI
+    if ! command -v lc &>/dev/null; then
+        echo "Warning: lc CLI not found. Materialization commands will fail."
+        echo "Run: pip install lightcone-cli"
+    fi
+
+    # Summary
+    echo ""
+    echo "Ready to plan build for universe: ${UNIVERSE}"
+    echo "Max iterations: ${MAX_ITERATIONS}"
+
+    exit 0
+fi
+
+# ─── Activate mode ───────────────────────────────────────────────────
+
+if [[ "$MODE" == "activate" ]]; then
+
+    SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+    PROMPT_TEMPLATE="${SCRIPT_DIR}/../assets/loop-prompt.md"
+
+    # Check template exists
+    if [[ ! -f "$PROMPT_TEMPLATE" ]]; then
+        echo "Error: loop-prompt.md template not found at ${PROMPT_TEMPLATE}" >&2
+        exit 1
+    fi
+
+    # Check build plan exists
+    if [[ ! -f ".lightcone/plans/build-plan-${UNIVERSE}.md" ]]; then
+        echo "Warning: No build plan found at .lightcone/plans/build-plan-${UNIVERSE}.md"
+        echo "The loop will proceed without a plan."
+    fi
+
+    # Fail hard if loop already active — don't silently overwrite a live loop
+    if [[ -f ".claude/ralph-loop.local.md" ]]; then
+        existing_iter=$(grep '^iteration:' .claude/ralph-loop.local.md 2>/dev/null | awk '{print $2}' || echo "?")
+        echo "Error: An active loop state file already exists (iteration ${existing_iter})." >&2
+        echo "  To resume the interrupted loop: setup-lc-build.sh --resume" >&2
+        echo "  To start fresh: delete .claude/ralph-loop.local.md first, then re-run --activate" >&2
+        exit 1
+    fi
+
+    # Ensure ralph-loop plugin is available
+    # Update MARKETPLACE_URL if the official plugin repository moves.
+    MARKETPLACE_URL="https://github.com/anthropics/claude-plugins-official.git"
+    RALPH_PLUGIN="$HOME/.claude/plugins/marketplaces/claude-plugins-official/plugins/ralph-loop"
+    MARKETPLACE="$HOME/.claude/plugins/marketplaces/claude-plugins-official"
+
+    if [[ ! -d "$RALPH_PLUGIN" ]]; then
+        echo "ralph-loop plugin not found. Attempting to install..."
+
+        if [[ -d "$MARKETPLACE/.git" ]]; then
+            # Marketplace exists but plugin missing — pull latest
+            echo "Updating plugin marketplace..."
+            git -C "$MARKETPLACE" pull --ff-only 2>&1 || true
+        elif [[ ! -d "$MARKETPLACE" ]]; then
+            # No marketplace at all — clone it
+            echo "Cloning plugin marketplace..."
+            mkdir -p "$HOME/.claude/plugins/marketplaces"
+            git clone "$MARKETPLACE_URL" "$MARKETPLACE" 2>&1 || true
+        fi
+
+        # Check again after update/clone
+        if [[ ! -d "$RALPH_PLUGIN" ]]; then
+            echo ""
+            echo "Error: ralph-loop plugin could not be installed." >&2
+            echo "The stop hook is required for /lc-build to loop." >&2
+            echo "" >&2
+            echo "Manual install: /plugin install ralph-loop@claude-plugins-official" >&2
+            # Clean up — don't leave a state file that traps the user
+            rm -f .claude/ralph-loop.local.md
+            exit 1
+        fi
+
+        echo "ralph-loop plugin found after update."
+    fi
+
+    # Verify the stop hook exists within the plugin
+    if [[ ! -f "$RALPH_PLUGIN/hooks/stop-hook.sh" ]]; then
+        echo "Error: ralph-loop plugin is present but hooks/stop-hook.sh is missing." >&2
+        echo "The plugin may be corrupted. Try: /plugin install ralph-loop@claude-plugins-official" >&2
+        exit 1
+    fi
+
+    # Template the prompt
+    prompt_body=$(sed "s/{{UNIVERSE}}/${UNIVERSE}/g" "$PROMPT_TEMPLATE")
+
+    # Create state file
+    mkdir -p .claude
+    cat > .claude/ralph-loop.local.md <<EOF
+---
+active: true
+iteration: 1
+max_iterations: ${MAX_ITERATIONS}
+completion_promise: "BUILD_COMPLETE"
+session_id: ${CLAUDE_CODE_SESSION_ID:-}
+universe: ${UNIVERSE}
+started_at: "$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+---
+
+${prompt_body}
+EOF
+
+    echo "Loop activated for universe: ${UNIVERSE}"
+    echo "  State file: .claude/ralph-loop.local.md"
+    echo "  Max iterations: ${MAX_ITERATIONS}"
+    echo "  Completion promise: BUILD_COMPLETE"
+    echo ""
+    echo "The stop hook will re-inject the build prompt on each exit."
+    echo "To cancel: /cancel-ralph"
+
+    exit 0
+fi
+
+# ─── Resume mode ────────────────────────────────────────────────────
+
+if [[ "$MODE" == "resume" ]]; then
+
+    RALPH_STATE_FILE=".claude/ralph-loop.local.md"
+
+    if [[ ! -f "$RALPH_STATE_FILE" ]]; then
+        echo "No active loop to resume (state file not found)."
+        echo "Run /lc-build to start a new build."
+        exit 1
+    fi
+
+    # Read current state from file
+    CURRENT_ITER=$(grep '^iteration:' "$RALPH_STATE_FILE" | awk '{print $2}')
+    OLD_SESSION=$(grep '^session_id:' "$RALPH_STATE_FILE" | awk '{print $2}')
+    CURRENT_MAX=$(grep '^max_iterations:' "$RALPH_STATE_FILE" | awk '{print $2}')
+
+    # Read universe from dedicated frontmatter field
+    LOOP_UNIVERSE=$(grep '^universe:' "$RALPH_STATE_FILE" | awk '{print $2}')
+
+    # Update session_id to claim this loop for the current session
+    TEMP_FILE="${RALPH_STATE_FILE}.tmp.$$"
+    sed "s/^session_id: .*/session_id: ${CLAUDE_CODE_SESSION_ID:-}/" "$RALPH_STATE_FILE" > "$TEMP_FILE"
+
+    # If --max-iterations was explicitly passed, update it in the state file
+    if [[ "$MAX_ITERATIONS_EXPLICIT" == "true" ]]; then
+        sed -i "s/^max_iterations: .*/max_iterations: ${MAX_ITERATIONS}/" "$TEMP_FILE"
+        CURRENT_MAX="${MAX_ITERATIONS}"
+    fi
+
+    mv "$TEMP_FILE" "$RALPH_STATE_FILE"
+
+    # Compute remaining iterations
+    REMAINING=$(( ${CURRENT_MAX:-0} - ${CURRENT_ITER:-1} + 1 ))
+
+    echo "Resumed loop for universe: ${LOOP_UNIVERSE:-unknown}"
+    echo "  Continuing from iteration: ${CURRENT_ITER:-?} / ${CURRENT_MAX:-?}"
+    echo "  Remaining iterations: ${REMAINING}"
+    echo "  Session updated: ${OLD_SESSION:-<unset>} -> ${CLAUDE_CODE_SESSION_ID:-<unset>}"
+    if [[ "$MAX_ITERATIONS_EXPLICIT" == "true" ]]; then
+        echo "  Max iterations updated to: ${MAX_ITERATIONS}"
+    fi
+
+    exit 0
+fi

lightcone/cli/claude/lightcone/skills/lc-feedback/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: lc-feedback
+description: >
+  File a bug report from the current session. Use when something breaks:
+  /lc-feedback <description of what went wrong>
+allowed-tools: Bash(gh:*), Bash(python:*), Bash(uname:*), AskUserQuestion
+argument-hint: "<what went wrong>"
+---
+
+# /lc-feedback
+
+File a bug report against the right Lightcone repo based on the current session.
+
+Be fast. The user is in the middle of work and wants to get back to it.
+
+## Prerequisites
+
+Run `gh auth status` silently. If it fails:
+
+> GitHub CLI is not authenticated. Run `gh auth login`, then try again.
+
+Stop.
+
+---
+
+## Step 1: Description
+
+The user should have provided a description inline (e.g., `/lc-feedback pipeline dies on second output`). If they didn't, ask briefly:
+
+**What went wrong?**
+
+---
+
+## Step 2: Draft and Confirm
+
+Triage the repo from context:
+- **ASTRA** — `astra` CLI, schema validation, YAML parsing, helpers
+- **lightcone-cli** — `lc` CLI, Dagster execution, recipes, container builds, scaffolding, skills, telemetry hooks
+
+Default to **lightcone-cli** if ambiguous.
+
+Collect versions silently:
+
+```bash
+python3 -c "import astra; print(astra.__version__)" 2>/dev/null || echo "n/a"
+python3 -c "import lightcone.cli; print(lightcone.cli.__version__)" 2>/dev/null || echo "n/a"
+python3 --version 2>&1
+uname -s -r
+```
+
+Show the user a single confirmation message with the target repo, title, and body. Use `AskUserQuestion` with options "File it" / "Let me edit". The issue body format:
+
+```
+## What happened
+
+[1-3 sentences combining user description + session context]
+
+## Error
+
+[Trimmed error/traceback from session, if any]
+
+## Reproduction
+
+[Brief steps from session context]
+
+## Environment
+
+- ASTRA: [version]
+- lightcone-cli: [version]
+- Python: [version]
+- OS: [os]
+```
+
+Omit sections that don't apply (e.g., no Error section if there was no traceback).
+
+---
+
+## Step 3: File
+
+```bash
+gh issue create --repo LightconeResearch/<REPO> --title "<TITLE>" --label "beta-feedback" --body "<BODY>"
+```
+
+If it fails due to the label not existing, retry without `--label`. Print the issue URL.
+
+---
+
+## Rules
+
+- **Be fast** — minimize back-and-forth, one confirmation then file
+- **Read-only** — never modify project files
+- **Trim aggressively** — only the relevant portion of errors, not full files
+- **No sensitive data** — strip absolute paths, credentials, tokens
+- **Don't editorialize** — report what happened, don't speculate on fixes

lightcone/cli/claude/lightcone/skills/lc-migrate/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: lc-migrate
+description: Migrate an existing project into ASTRA / lightcone-cli. Scans code, generates astra.yaml, parameterizes decisions, and runs until outputs materialize. Use after `lc init . --existing-project`. Triggers on "migrate", "convert", "existing project".
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash(astra:*), Bash(lc:*), Bash(python:*), Bash(pip:*), Bash(git:*), Bash(mkdir:*), Bash(ls:*), Agent, AskUserQuestion
+---
+
+# /lc-migrate
+
+End-to-end migration: scan existing code, generate the ASTRA spec, parameterize decisions in the code, and run until everything materializes. The user's existing logic stays intact — changes should be minimal.
+
+## References
+
+- [ASTRA Reference](../../guides/astra-reference.md) -- spec structure, decision identification, recipes, universes
+
+## Phase 1: Scan & Spec
+
+Spawn an Explore subagent to scan the project:
+
+First, read the Decisions section of [ASTRA Reference](../../guides/astra-reference.md), then spawn an Explore subagent. Include the decision criteria in the prompt so the subagent can classify candidates:
+
+```
+Agent(subagent_type="Explore", prompt="""
+Scan this project thoroughly and return a structured inventory.
+
+For every script and notebook, report:
+- File path
+- What it does (read the code, don't guess)
+- What files it reads (data, configs, other scripts' outputs)
+- What files it writes (results, plots, models, etc.)
+- Hardcoded analytical choices: magic numbers, commented alternatives,
+  method-selecting branches, config dicts. Include file, line number,
+  current value, and what it controls.
+- How it's currently invoked (argparse, config file, nothing)
+
+Also report:
+- Dependencies (requirements.txt, pyproject.toml, environment.yml, etc.)
+- Data files present in the project
+- Any existing container setup (Dockerfile, Containerfile)
+
+Return the results as a markdown table:
+| Script | Purpose | Reads | Writes | Hardcoded choices |
+
+And a separate list of ALL candidate decisions with file:line references.
+Err on the side of completeness — include anything that could plausibly
+be an analytical choice. The orchestrator will filter down later.
+
+For reference, here are the decision criteria for classifying candidates:
+<decision-criteria>
+{paste Decisions section from astra-reference.md here}
+</decision-criteria>
+""")
+```
+
+Write the scan results to `CLAUDE.md` under Analysis Context as a script inventory, then draft `astra.yaml` from the scan results following the spec structure documented in `.claude/guides/astra-reference.md`. Use the decision criteria from [ASTRA Reference](../../guides/astra-reference.md) to filter the subagent's candidate decisions down to only true analytical choices — most hardcoded values are implementation details, not decisions. Use current hardcoded values as defaults.
+
+Include `recipe:` blocks on each output pointing to the script that produces it. Also generate `universes/baseline.yaml` with all defaults matching the current hardcoded values (so the first run reproduces existing behavior).
+
+Write to `astra.yaml` and `universes/baseline.yaml`, then validate: `astra validate astra.yaml`. Fix any errors.
+
+Use `AskUserQuestion` to ask the user to review the spec — they can open `astra.yaml` directly or right-click it and open in lightcone-ui. Wait for confirmation before proceeding to implementation.
+
+## Phase 2: Implement
+
+Parameterize the code so decisions can be varied across universes. The goal is minimal changes to user code. Use your best judgement for the approach — the options below are not exhaustive:
+
+**For scripts with hardcoded values:** Add argparse (or extend existing argument parsing) and replace hardcoded values with the parsed args. This is the simplest case.
+
+**For notebooks:** Move the `.ipynb` to `notebooks/` (preserving it as reference), then create a `.py` script that does the parameterized version. The recipe points to the new script.
+
+**For config-file-driven projects:** Create a thin wrapper script that accepts ASTRA decision args, writes/updates the config file, then calls the original entry point. The user's config-driven code stays untouched.
+
+**Dependencies:** Check that `requirements.txt` includes all packages the code imports. If one doesn't exist, create it. If it's incomplete, add missing deps.
+
+Whatever approach you use:
+
+- **Don't refactor, restructure, or improve the code.** Just add the parameter plumbing.
+- **Underscore convention:** Decision IDs use underscores in `astra.yaml` (`outlier_sigma`). lightcone-cli passes `--outlier_sigma`. Argument parsing must match.
+- **Update output paths** to write to `results/{universe}/{output_id}.ext` following the convention in `CLAUDE.md`.
+- **Update recipes** in `astra.yaml` if the entry point or command changed.
+
+## Phase 3: Run & Debug
+
+```bash
+lc run --universe baseline
+```
+
+If it fails, read the error, fix it, and retry. Iterate until `lc status` shows all outputs as `ok`.
+
+If the scan found existing results elsewhere in the project, compare them against the new outputs in `results/baseline/` to verify the migration preserved behavior.
+
+Then validate: `astra validate astra.yaml`. Present summary to user.
+
+## Rules
+
+- **Minimal changes.** Do not refactor, rename, reorganize, or "improve" existing code.
+- **Don't guess.** Read every script before making claims about what it does.
+- **Filter decisions aggressively.** Most hardcoded values are implementation details, not analytical choices.
+- **Preserve behavior.** The baseline universe with default values must reproduce the original behavior exactly.

lightcone/cli/claude/lightcone/skills/lc-new/SKILL.md

@@ -0,0 +1,183 @@
+---
+name: lc-new
+description: Create a new ASTRA analysis project with integrated literature support. Scope the research question through conversation, structure outputs and decisions, search for and extract evidence from scientific papers, and build a complete astra.yaml specification. Use when starting a new analysis, when the user says "new project", "new analysis", or "scope". Triggers on "new", "scope", "research question", "start analysis".
+allowed-tools: Read, Write(astra.yaml), Write(universes/*), Write(CLAUDE.md), Edit(astra.yaml), Edit(universes/*), Edit(CLAUDE.md), Glob, Grep, Bash(astra:*), Bash(lc:*), Bash(mkdir:*), Bash(echo:*), WebSearch, WebFetch, AskUserQuestion, Task
+---
+
+# /lc-new
+
+Create a new ASTRA analysis project through conversation. Build the spec iteratively -- write to `astra.yaml` after each phase so the user sees progress. Literature search and decision identification happen in distinct phases -- talk first, then extract papers, then identify decisions informed by both conversation and literature.
+
+## References
+
+- [ASTRA Reference](../../guides/astra-reference.md) -- spec structure, decision identification, recipes, universes
+- [UI Brand](../../guides/ui-brand.md) -- visual formatting patterns
+
+## Setup
+
+1. Read `astra.yaml` if it exists (to understand context or avoid overwriting)
+2. Note the analysis directory for later
+
+---
+
+## Phase 1: Research Question
+
+Stage banner: RESEARCH QUESTION
+
+> "What are you trying to learn? Describe the question in your own words."
+
+Then sharpen:
+- "What would a clear answer look like?" (sharpens the description)
+- "Why does this matter?" (context for decisions)
+
+**Write to astra.yaml immediately** with `version`, `name`, `description`. This gives the user something visible right away.
+
+---
+
+## Phase 2: Analysis Structure
+
+Stage banner: ANALYSIS STRUCTURE
+
+> "Walk me through your analysis step by step. What goes in, what comes out at the end?"
+
+**Guidance on sub-analyses:** Analyses should only be split into multiple sub-analyses if each sub analysis genuinely has materially different inputs and outputs, and if the scope may be too broad if there is just one analysis; we overall want a sub-analysis to feel like it should genuinely be a self-contained product. For example, training + evaluation would typically be one analysis, because the product would be the trained and validated neural network estimator. When in doubt, opt for a single analysis at this stage. If it does need to be multi-stage, ask the user for confirmation and how to split it. For multi-stage analyses, make sure you confirm stage boundaries. See `.claude/guides/astra-reference.md` for YAML structure and sub-analysis guidance.
+
+**One output per output.** Each output should be a single metric, a single plot, or a single artifact. Do not bundle multiple metrics into one output (e.g., "performance_metrics" containing accuracy, F1, and AUC). Each of those is its own output. Same for plots -- one figure per output.
+
+**Update astra.yaml** with `inputs` and `outputs` (extending the spec from Phase 1).
+
+---
+
+## Phase 3: Deep Dive
+
+Stage banner: DEEP DIVE -- [SECTION NAME]
+
+Ask the user if they want to do a literature deep dive for this section. If not, skip straight to decision identification.
+
+### Paper Collection
+
+Ask if the user has specific papers they want to look into. Also search with WebSearch for highly relevant papers -- keep it limited, only papers that directly bear on the analysis. Use AskUserQuestion to present the list with a one-line description of each paper and why it's relevant. The user can check off which ones to extract and add any others.
+
+### Extraction
+
+For each approved paper: `astra paper add <doi>`, `astra paper path <doi>`, then spawn one `lc-extractor` agent per paper. The agent definition already contains extraction instructions, output format, and verification logic -- you just fill in the paper-specific context.
+
+**Spawning each agent:** Use `Agent(subagent_type="lc-extractor", prompt="...")`. In the prompt, provide:
+- **Analysis context**: the analysis description and decisions this paper might inform
+- **Paper details**: DOI, version (arXiv only), PDF path (from `astra paper path`)
+- **Target decisions**: each decision ID, label, and options with descriptions
+- **Timestamp**: current time in ISO 8601
+
+The agent type is pre-configured with the user's preferred extraction model (set via `lc setup`). Spawn all in a single message (parallel). Show progress as results come in:
+
+```
+  ✓ Ba et al. 2016 -- 3 prior insights
+  ○ Wu & He 2018 (reading...)
+```
+
+Write extracted prior insights to astra.yaml immediately. Synthesize them by topic for the user.
+
+### Decision Identification
+
+Use the conversation and literature to identify decisions. Apply the decision criteria from [astra-reference.md](../../guides/astra-reference.md):
+
+- What could be done differently and still be defensible?
+- Where did papers disagree or compare alternatives?
+- Where did the user express uncertainty?
+
+Write candidate decisions to astra.yaml as a batch for user review. Keep chat output concise (summary + decision IDs), and avoid dumping full decision details in chat.
+
+**Probe for blind spots** -- analysts over-focus on methods and neglect data handling. Probe 1-3 areas: data exclusion, variable operationalization, inference criteria.
+
+### Decision Review
+
+During review, confirm or set each decision's `default`, keep option structure and evidence links, and remove any decisions the user rejects.
+
+---
+
+## Checkpoint
+
+> "Anything else that should inform this analysis?"
+
+Review the spec with the user. Update astra.yaml with any additions.
+
+---
+
+## Finalize
+
+Stage banner: FINALIZING
+
+### Validate
+
+1. `astra validate astra.yaml` -- fix errors, iterate until clean
+2. If prior insights exist: `astra validate astra.yaml --verify-evidence`
+
+### Generate Baseline Universe
+
+```bash
+astra universe generate -n baseline
+```
+
+### Populate CLAUDE.md
+
+Read the existing `CLAUDE.md` (created by `lc init`). Replace the `## Working Notes` section with context that is NOT already visible in `astra.yaml`. The spec is the source of truth for structure, decisions, and evidence -- CLAUDE.md captures only what would be lost after `/clear`:
+
+- **Domain Context**: important things the user explained during scoping -- data characteristics, constraints, why certain approaches were preferred. This is conversational context not captured in the spec.
+- **Implementation Notes**: domain-specific guidance from the conversation (libraries, data formats, gotchas)
+
+### Review with User
+
+> "Anything you'd like to change? Otherwise the specification is ready."
+
+If edits requested, apply, re-validate, and update CLAUDE.md.
+
+---
+
+## Done
+
+Stage banner: SPECIFICATION COMPLETE
+
+Show summary table:
+
+```
+| Section       | Decisions | Outputs | Prior Insights |
+|---------------|-----------|---------|----------|
+| (top-level)   | 3         | 2       | 5        |
+| sub_analysis  | ...       | ...     | ...      |
+```
+
+Then show a Next Up block (see ui-brand.md) with:
+
+- Run `/clear` to free up context, then `/lc-build` to start building
+- Or `/lc-build [description]` to guide what to focus on first (e.g. `/lc-build focus on the fitting script`)
+- Also available: `/lc-verify`
+
+Prompt the user to `/clear` before starting implementation. The scoping conversation consumes significant context. Everything needed to continue is captured in `astra.yaml` and `CLAUDE.md`.
+
+---
+
+## Restrictions
+
+**You are a specification agent, not an implementation agent.**
+
+You MUST NOT write Python, R, or other implementation code.
+
+You MUST ONLY create/modify: `astra.yaml`, `universes/*.yaml`, `CLAUDE.md` (Finalize only).
+
+You MUST NOT fabricate quotes -- all evidence must pass `astra validate --verify-evidence`.
+
+You MUST spawn `lc-extractor` agents for paper processing. One paper per agent. Never read a PDF in the main agent context.
+
+---
+
+## Anti-Patterns
+
+- **Waiting to write** -- Update astra.yaml after each decision crystallizes, not in bulk at the end
+- **Accepting vague goals** -- "Analyze this data" is not a research question; push back
+- **Method-only decisions** -- Actively probe for data handling and exclusion criteria, not just method choices
+- **Literature as afterthought** -- Do not defer all literature to the end. Collect paper candidates during conversation (Phases 1-2) and extract them before identifying decisions (Extraction before Decision Identification in Phase 3)
+- **Too many papers** -- ~2 papers per topic area, max 10 per section; do not try to be exhaustive
+- **Background interruptions** -- Never spawn search or extraction subagents during conversation phases. Collect candidates first, then process them during Phase 3 Extraction
+- **Reading PDFs in main context** -- Always delegate to subagents; PDFs consume too much context
+- **Chat dump of decisions** -- Do not dump full candidate decision content in chat; write decisions to astra.yaml for review
+- **Skipping verification** -- If quotes were extracted, always run `astra validate --verify-evidence`

lightcone/cli/claude/lightcone/skills/lc-verify/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: lc-verify
+description: Verify that astra.yaml, code, and results are consistent. Run after building an analysis.
+allowed-tools: Read, Glob, Grep, Bash(astra:*), Bash(lc:*), Bash(python:*), Bash(ls:*), AskUserQuestion
+---
+
+# /lc-verify
+
+Verify that the spec, code, and results all agree. Default universe is `baseline` unless specified.
+
+## Checks
+
+### 1. Spec validation
+
+```bash
+astra validate astra.yaml
+```
+
+### 2. Materialization status
+
+```bash
+lc status --universe <universe_id>
+```
+
+Every output should show `ok`. Flag anything pending, missing, or without a recipe.
+
+### 3. Decision-code alignment
+
+**The most important check.** For every decision in `astra.yaml`, confirm the code accepts it as a parameter and does not hardcode its value. Compare `astra info --decisions` against `grep -r "add_argument" scripts/`.
+
+### 4. Results match spec
+
+For every output in `astra.yaml`, verify `results/<universe_id>/<output_id>.<ext>` exists and looks well-formed. For `type: metric` outputs, check for valid `{"value": ...}` JSON.
+
+## Report
+
+```
+| Check                    | Status |
+|--------------------------|--------|
+| Spec validation          | ✓/✗    |
+| Materialization (N/N)    | ✓/✗    |
+| Decision-code alignment  | ✓/⚠/✗  |
+| Results match spec (N/N) | ✓/✗    |
+```
+
+List each finding with file paths and line numbers. If there are failures, suggest concrete fixes.
+
+## Rules
+
+- **Read-only** — never modify files
+- **One universe at a time**
+- **Never skip check 3** — decision-code alignment is the core value
+- **Always read actual result files** — don't infer from code