@brainpilot/skills 0.0.6 → 0.0.8

package/skills/01_Meta-Skills/ethoclaw-pdf-research/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: ethoclaw-pdf-research
+description: "Read local PDF files for analysis, summarization, and research-note generation. Use when the user uploads a PDF or provides a local PDF path and wants the model to inspect reports, papers, whitepapers, slides, or scanned documents by extracting text, rendering page images, and producing a structured summary or research log."
+---
+
+# EthoClaw PDF Research Reader
+
+Use scripts first. Prefer a two-path workflow: extract text for speed, inspect rendered page images when formatting is important or the PDF is scan-heavy.
+
+## Interaction rule
+
+Do not parse a newly received PDF immediately by default.
+
+When the user uploads a PDF without a clear output request, first confirm what they want:
+
+- short summary
+- detailed analysis
+- research log returned directly in chat
+- markdown file only if explicitly requested
+- page/section/figure-focused reading
+
+Only start parsing after the user confirms the desired output.
+
+Exception: if the user already asked for a specific output together with the file or path, treat that as confirmation and proceed directly.
+
+## Quick start
+
+Prepare an analysis bundle:
+
+```bash
+python3 scripts/extract_pdf_bundle.py /path/to/file.pdf \
+  --output-dir /tmp/pdf_bundle \
+  --text-last-page 0 \
+  --render-last-page 8
+```
+
+If the user explicitly wants markdown files, generate both deliverables:
+
+```bash
+python3 scripts/build_markdown_deliverables.py \
+  /tmp/pdf_bundle/manifest.json \
+  --output-dir /tmp/pdf_bundle/md
+```
+
+If the user explicitly wants only a research-log file:
+
+```bash
+python3 scripts/build_research_log.py \
+  /tmp/pdf_bundle/manifest.json \
+  --output /tmp/pdf_bundle/research-log.md
+```
+
+## Workflow
+
+1. Resolve the source PDF.
+   - If the user uploaded a file, use the local file path provided by the runtime.
+   - If the user gave a path, validate that it exists before proceeding.
+2. Check whether the user already specified the output.
+   - If yes, proceed directly.
+   - If no, ask a short confirmation question before parsing.
+   - Read `references/confirmation-prompts.md` for the default phrasing.
+3. After confirmation, run `scripts/extract_pdf_bundle.py`.
+   - This produces `manifest.json`, `document.txt`, and rendered PNG page previews.
+4. Read `manifest.json` first.
+   - Check page count, extracted-text size, and rendered image paths.
+5. Read `document.txt` for the main pass.
+   - Use this for normal text PDFs, reports, and most academic papers.
+6. If the extracted text is sparse, garbled, or loses key layout, inspect the PNG pages directly.
+   - Read the first pages for title/abstract/executive summary.
+   - Read result-heavy or conclusion-heavy pages when needed.
+7. Produce the requested output.
+   - Default: return the summary or research log directly in chat.
+   - For a plain summary: give topic, core argument, evidence, conclusions, caveats.
+   - For a research log: write the full research log directly in chat unless the user explicitly asked for a file.
+   - Only generate markdown files when the user explicitly asks for markdown, wants a reusable local artifact, or needs the result saved for later editing.
+   - If markdown files are requested, use `build_markdown_deliverables.py` or `build_research_log.py` as scaffolding helpers, then fill the sections with actual findings.
+
+## Script behavior
+
+### `scripts/extract_pdf_bundle.py`
+
+- Read PDF metadata via `pdfinfo`
+- Extract text with `pdftotext -layout`
+- Render selected pages to PNG via `pdftoppm`
+- Write a reusable bundle for later reading:
+  - `manifest.json`
+  - `document.txt`
+  - `images/page-XXXX.png`
+
+Important flags:
+
+- `--text-last-page 0`: read all pages as text
+- `--render-last-page N`: render the first N pages for visual inspection
+- `--dpi 144`: default PNG quality; raise it if formulas or small print are hard to read
+- `--clean`: replace an existing output directory
+
+### `scripts/build_research_log.py`
+
+- Convert `manifest.json` into a markdown note scaffold
+- Keep source paths and reading instructions in the log
+- Use it when the user explicitly wants a research log, reading note, or reusable markdown artifact
+- Do not stop at the empty scaffold; fill the sections with actual findings after reading the PDF bundle
+
+### `scripts/build_summary_md.py`
+
+- Convert `manifest.json` into a short markdown summary scaffold
+- Use it when the user wants a concise deliverable or when you want a companion file next to the research log
+
+### `scripts/build_markdown_deliverables.py`
+
+- Create both `summary.md` and `research-log.md` in one step
+- Use it as the default markdown-deliverable generator after the user confirms they want markdown output
+
+## Heuristics
+
+- Prefer text first for normal reports and papers.
+- Prefer image inspection when the PDF is scanned, multi-column extraction is messy, or tables/figures matter more than raw prose.
+- For very long PDFs, do not read every rendered page by default. Start with:
+  - title / abstract / executive-summary pages
+  - table-of-contents page if it helps navigation
+  - conclusion / discussion pages
+  - result figures or tables requested by the user
+- If the user asks for deep extraction of a specific section, rerun the script with a tighter page range rather than rendering the whole file at high DPI.
+
+## Notes
+
+- The current version relies on local command-line tools already available on the host: `pdfinfo`, `pdftotext`, and `pdftoppm`.
+- This skill does not perform OCR beyond what the local PDF/text tools can recover. For image-only scans, rely on rendered PNG pages and vision-capable analysis.
+- Keep external writes minimal. Most tasks can be completed locally inside the workspace.
+
+## References
+
+- Read `references/confirmation-prompts.md` when a PDF arrives without a clear requested output.
+- Read `references/output-patterns.md` for compact output shapes and suggested summary formats.

package/skills/01_Meta-Skills/ethoclaw-pdf-research/references/confirmation-prompts.md

@@ -0,0 +1,31 @@
+# Confirmation Prompts
+
+When a PDF arrives, do not start parsing immediately unless the user explicitly asked for immediate analysis.
+
+Use a short confirmation message like this:
+
+## Default confirmation
+
+I have received this PDF. How would you like me to handle it?
+- Brief summary
+- Detailed analysis
+- Research log (direct reply to you)
+- Focus on certain pages / sections / figures
+- If you want, I can also organize it into a markdown file
+
+I will start parsing after you confirm.
+
+## If the file looks like a manual / SOP / guide
+
+I have received this PDF, it looks like an operation manual/documentation. How would you like me to output it?
+- Quick summary
+- Organize by "usage-process-output-precautions"
+- Direct reply as research log
+- Organize as operation guide for newcomers
+- If you want, I can also generate a markdown file
+
+I will parse after you confirm.
+
+## If the user already gave a goal
+
+If the user says things like "help me summarize", "make a research log", "focus on methods section", that counts as confirmation. Start parsing directly and produce the requested output without asking again.

package/skills/01_Meta-Skills/ethoclaw-pdf-research/references/output-patterns.md

@@ -0,0 +1,45 @@
+# Output Patterns
+
+Use one of these compact shapes after reading a PDF bundle.
+
+## 1. Short summary
+
+Use when the user only wants the gist.
+
+- Topic:
+- Core claim:
+- Main evidence:
+- Key takeaway:
+- Caveat:
+
+## 2. Research log
+
+Use when the user wants a reusable note.
+
+- Basic metadata: title, source path, page count
+- One-paragraph overview
+- Key points
+- Methods / data / evidence
+- Results / claims
+- Caveats
+- Useful quotes or numbers
+- Follow-up questions
+
+## 3. Figure/table-oriented reading
+
+Use when layout matters more than prose extraction.
+
+- What the figure/table shows
+- Why it matters
+- Any exact numbers visible
+- Any ambiguity caused by resolution or cropping
+
+## 4. Comparison note
+
+Use when multiple PDFs are involved.
+
+- Shared topic
+- Agreement points
+- Disagreement points
+- Evidence quality by document
+- Final synthesis

package/skills/01_Meta-Skills/ethoclaw-pdf-research/scripts/build_markdown_deliverables.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+
+SCRIPT_DIR = Path(__file__).resolve().parent
+
+
+def run(cmd):
+    subprocess.run(cmd, check=True)
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Create markdown deliverable scaffolds from a PDF bundle manifest.")
+    parser.add_argument("manifest", help="Path to manifest.json produced by extract_pdf_bundle.py")
+    parser.add_argument("--output-dir", required=True, help="Directory for markdown deliverables")
+    parser.add_argument("--title", default="", help="Optional title override")
+    args = parser.parse_args()
+
+    manifest = Path(args.manifest).expanduser().resolve()
+    outdir = Path(args.output_dir).expanduser().resolve()
+    outdir.mkdir(parents=True, exist_ok=True)
+
+    summary_path = outdir / "summary.md"
+    research_log_path = outdir / "research-log.md"
+
+    common = [str(manifest)]
+    if args.title:
+        common += ["--title", args.title]
+
+    run([sys.executable, str(SCRIPT_DIR / "build_summary_md.py"), *common, "--output", str(summary_path)])
+    run([sys.executable, str(SCRIPT_DIR / "build_research_log.py"), *common, "--output", str(research_log_path)])
+
+    print(summary_path)
+    print(research_log_path)
+
+
+if __name__ == "__main__":
+    main()

package/skills/01_Meta-Skills/ethoclaw-pdf-research/scripts/build_research_log.py

@@ -0,0 +1,84 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Build a markdown research-log template from an extracted PDF bundle manifest.")
+    parser.add_argument("manifest", help="Path to manifest.json produced by extract_pdf_bundle.py")
+    parser.add_argument("--title", default="", help="Override document title")
+    parser.add_argument("--output", default="", help="Write markdown to this path; otherwise print to stdout")
+    args = parser.parse_args()
+
+    manifest_path = Path(args.manifest).expanduser().resolve()
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    pdfinfo = manifest.get("pdfinfo", {})
+    title = args.title or pdfinfo.get("Title") or Path(manifest["source_pdf"]).stem
+
+    image_files = manifest.get("images", {}).get("files", [])
+    image_list = "\n".join(f"- {p}" for p in image_files[:12]) or "- (none)"
+
+    md = f"""# Research Log: {title}
+
+## Source
+- PDF: {manifest['source_pdf']}
+- Total pages: {manifest.get('page_count', 'unknown')}
+- Extracted text: {manifest['text']['path']}
+- Rendered preview pages: {manifest['images']['first_page']}-{manifest['images']['last_page']} @ {manifest['images']['dpi']} DPI
+
+## Suggested reading plan for the model
+1. Read `manifest.json` first for metadata.
+2. Read `document.txt` for the raw extracted text.
+3. If the text looks broken, inspect the rendered PNG pages directly.
+4. Summarize the paper/report in the structure below.
+
+## Rendered page files
+{image_list}
+
+## Summary
+- One-paragraph overview:
+- Document type / topic:
+- Main question or purpose:
+
+## Key points
+- 
+- 
+- 
+
+## Methods / data / evidence
+- 
+- 
+- 
+
+## Results / claims
+- 
+- 
+- 
+
+## Caveats
+- 
+- 
+- 
+
+## Useful quotes or numbers
+- 
+- 
+- 
+
+## My follow-up notes
+- 
+- 
+- 
+"""
+
+    if args.output:
+        out = Path(args.output).expanduser().resolve()
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(md, encoding="utf-8")
+    else:
+        print(md)
+
+
+if __name__ == "__main__":
+    main()

package/skills/01_Meta-Skills/ethoclaw-pdf-research/scripts/build_summary_md.py

@@ -0,0 +1,63 @@
+#!/usr/bin/env python3
+import argparse
+import json
+from pathlib import Path
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Build a markdown summary template from an extracted PDF bundle manifest.")
+    parser.add_argument("manifest", help="Path to manifest.json produced by extract_pdf_bundle.py")
+    parser.add_argument("--title", default="", help="Override document title")
+    parser.add_argument("--output", default="", help="Write markdown to this path; otherwise print to stdout")
+    args = parser.parse_args()
+
+    manifest_path = Path(args.manifest).expanduser().resolve()
+    manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    pdfinfo = manifest.get("pdfinfo", {})
+    title = args.title or pdfinfo.get("Title") or Path(manifest["source_pdf"]).stem
+
+    md = f"""# Summary: {title}
+
+## Source
+- PDF: {manifest['source_pdf']}
+- Total pages: {manifest.get('page_count', 'unknown')}
+- Extracted text: {manifest['text']['path']}
+- Preview images: {manifest['images']['dir']}
+
+## Executive summary
+- Topic:
+- Purpose:
+- Core message:
+
+## Key findings
+- 
+- 
+- 
+
+## Evidence / basis
+- 
+- 
+- 
+
+## Practical takeaway
+- 
+- 
+
+## Caveats
+- 
+- 
+
+## Suggested next step
+- 
+"""
+
+    if args.output:
+        out = Path(args.output).expanduser().resolve()
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(md, encoding="utf-8")
+    else:
+        print(md)
+
+
+if __name__ == "__main__":
+    main()

package/skills/01_Meta-Skills/ethoclaw-pdf-research/scripts/extract_pdf_bundle.py

@@ -0,0 +1,140 @@
+#!/usr/bin/env python3
+import argparse
+import json
+import os
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+
+def run(cmd):
+    return subprocess.run(cmd, check=True, text=True, capture_output=True)
+
+
+def parse_pdfinfo(pdf_path: Path):
+    result = run(["pdfinfo", str(pdf_path)])
+    info = {}
+    for line in result.stdout.splitlines():
+        if ":" not in line:
+            continue
+        key, value = line.split(":", 1)
+        info[key.strip()] = value.strip()
+    pages = int(info.get("Pages", "0") or 0)
+    return {"raw": info, "pages": pages}
+
+
+def sanitize_text(text: str) -> str:
+    text = text.replace("\x0c", "\n")
+    text = text.replace("\r", "")
+    text = re.sub(r"\n{3,}", "\n\n", text)
+    return text.strip() + "\n"
+
+
+def extract_text(pdf_path: Path, output_path: Path, first_page=None, last_page=None):
+    cmd = ["pdftotext", "-enc", "UTF-8", "-layout"]
+    if first_page is not None:
+        cmd += ["-f", str(first_page)]
+    if last_page is not None:
+        cmd += ["-l", str(last_page)]
+    cmd += [str(pdf_path), "-"]
+    result = run(cmd)
+    text = sanitize_text(result.stdout)
+    output_path.write_text(text, encoding="utf-8")
+    return text
+
+
+def render_pages(pdf_path: Path, output_dir: Path, start_page: int, end_page: int, dpi: int):
+    prefix = output_dir / "page"
+    cmd = [
+        "pdftoppm",
+        "-png",
+        "-r",
+        str(dpi),
+        "-f",
+        str(start_page),
+        "-l",
+        str(end_page),
+        str(pdf_path),
+        str(prefix),
+    ]
+    run(cmd)
+    images = sorted(output_dir.glob("page-*.png"))
+    renamed = []
+    for image in images:
+        m = re.search(r"page-(\d+)\.png$", image.name)
+        if not m:
+            continue
+        page_num = int(m.group(1))
+        new_path = output_dir / f"page-{page_num:04d}.png"
+        image.rename(new_path)
+        renamed.append(new_path)
+    return renamed
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Extract text and rendered pages from a PDF into a reusable analysis bundle.")
+    parser.add_argument("pdf", help="Path to the input PDF")
+    parser.add_argument("--output-dir", required=True, help="Directory for extracted artifacts")
+    parser.add_argument("--text-first-page", type=int, default=1, help="First page for text extraction")
+    parser.add_argument("--text-last-page", type=int, default=0, help="Last page for text extraction; 0 means all pages")
+    parser.add_argument("--render-first-page", type=int, default=1, help="First page to render as images")
+    parser.add_argument("--render-last-page", type=int, default=8, help="Last page to render as images")
+    parser.add_argument("--dpi", type=int, default=144, help="PNG render DPI")
+    parser.add_argument("--clean", action="store_true", help="Delete output directory before writing")
+    args = parser.parse_args()
+
+    pdf_path = Path(args.pdf).expanduser().resolve()
+    output_dir = Path(args.output_dir).expanduser().resolve()
+
+    if not pdf_path.exists():
+        raise SystemExit(f"PDF not found: {pdf_path}")
+
+    if shutil.which("pdfinfo") is None or shutil.which("pdftotext") is None or shutil.which("pdftoppm") is None:
+        raise SystemExit("Missing required commands. Need pdfinfo, pdftotext, and pdftoppm in PATH.")
+
+    if args.clean and output_dir.exists():
+        shutil.rmtree(output_dir)
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    info = parse_pdfinfo(pdf_path)
+    total_pages = info["pages"]
+    text_last_page = total_pages if args.text_last_page in (0, None) else min(args.text_last_page, total_pages)
+    render_last_page = min(args.render_last_page, total_pages)
+
+    text_path = output_dir / "document.txt"
+    text = extract_text(pdf_path, text_path, args.text_first_page, text_last_page)
+    char_count = len(text.strip())
+
+    images_dir = output_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    image_paths = render_pages(pdf_path, images_dir, args.render_first_page, render_last_page, args.dpi)
+
+    manifest = {
+        "source_pdf": str(pdf_path),
+        "output_dir": str(output_dir),
+        "page_count": total_pages,
+        "text": {
+            "path": str(text_path),
+            "first_page": args.text_first_page,
+            "last_page": text_last_page,
+            "char_count": char_count,
+        },
+        "images": {
+            "dir": str(images_dir),
+            "first_page": args.render_first_page,
+            "last_page": render_last_page,
+            "dpi": args.dpi,
+            "files": [str(p) for p in image_paths],
+        },
+        "pdfinfo": info["raw"],
+    }
+    manifest_path = output_dir / "manifest.json"
+    manifest_path.write_text(json.dumps(manifest, ensure_ascii=False, indent=2), encoding="utf-8")
+
+    print(json.dumps(manifest, ensure_ascii=False, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/01_Meta-Skills/experiment-controller/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: experiment-controller
+description: "Use this skill whenever the user wants to execute experiments based on a finalized method and record results. Triggers include: 'run experiment', 'experiment controller', 'implement experiment', 'run model', 'execute training', 'experiment-controller', 'record results', 'ablation study', or any request to turn METHOD.md into concrete runs and output to EXPERIMENT.md. This skill is the **mandatory interface-layer experiment executor** in NeuroClaw: it searches literature/GitHub for matching experimental setups and codebases, proposes one scheme + repo after user discussion, uses git skills to download and setup, runs the experiment(s), and iteratively appends every result + observation to EXPERIMENT.md."
+license: MIT License (NeuroClaw custom skill – freely modifiable within the project)
+layer: interface
+skill_type: workflow
+dependencies:
+  - claw-shell
+  - dependency-planner
+  - git-essentials
+---
+# Experiment Controller
+## Overview
+This skill implements the **Literature/GitHub Search → Scheme Confirmation → Git Execution → Iterative Logging** process for the NeuroClaw experiment-controller phase.
+
+It acts as the Experiment Manager within the multi-agent framework:
+- Reads the latest **IDEA.md** and **METHOD.md** from the workspace.
+- Searches recent literature (multi-search-engine, arxiv-search, pubmed-search) and GitHub for reproducible experimental setups and open-source repositories that match the proposed architecture.
+- Summarizes candidate schemes (hyperparameters, datasets, baselines, training protocols) and proposes the most suitable GitHub repo.
+- Iteratively discusses with the user to confirm the exact scheme/repo.
+- After confirmation: uses git-essentials/git-workflows to clone, dependency-planner to install environment, claw-shell to run the experiment (training/inference/ablation).
+- After every run (or ablation), automatically records: setup details, metrics, logs, observations, and any issues.
+- Saves everything in **EXPERIMENT.md** (with dated sections for each run).
+
+**Research use only** — the output is a complete, reproducible EXPERIMENT.md ready for paper-writing and future replication.
+
+## Quick Reference (Experiment Flow)
+| Step | Description                              | Output File               |
+|------|------------------------------------------|---------------------------|
+| 1. Read & Parse | Load IDEA.md + METHOD.md                | 01_idea_method_summary.md |
+| 2. Literature & GitHub Search | Find matching setups & repos            | 02_search_results.md      |
+| 3. Proposal | Recommend best scheme + repo            | 03_proposal.md            |
+| 4. User Discussion | Confirm scheme/repo                     | 04_discussion.md          |
+| 5. Git Clone & Setup | Clone + install dependencies            | 05_setup_log.md           |
+| 6. Run Experiment | Execute training/inference/ablation     | 06_run_log_*.md (per run) |
+| 7. Record Results | Append metrics + observations           | EXPERIMENT.md             |
+
+## Harness Engineering Protocol (Mandatory for Reproducibility)
+
+All experiments executed via experiment-controller **must** follow the **Task Decomposition → Agent Initialization → Execution → Verification** protocol to ensure self-validation, auditability, and resumability.
+
+### Phase 1: Task Decomposition
+- Parse experimental goal from METHOD.md into discrete tasks (data preprocessing, feature extraction, model training, inference, evaluation)
+- Define success criteria for each task (BIDS format compliance, feature vector shape/range, metric thresholds)
+- Identify cross-task dependencies and data flow
+- Output: `experiment_task_manifest.json` with task graph
+
+### Phase 2: Agent Initialization
+- **Pre-flight checks**: verify all dependencies installed, data paths accessible, Docker/GPU resources available (if required)
+- **Environment snapshot**: capture Python version, library versions, hardware specs, random seeds → `environment_manifest.json`
+- **Checkpoint management**: determine checkpoint frequency, rollback strategy, memory constraints
+- **Logging setup**: initialize structured logging with unique experiment session ID (timestamp + hash)
+
+### Phase 3: Execution with Incremental Logging
+- Execute each task with **real-time progress tracking**
+- Save checkpoint after each completed task (enables resumption on failure)
+- Log detailed metrics, intermediate outputs, and timing information
+- Generate cryptographic hash (SHA256) for each output artifact
+- Stream results to EXPERIMENT.md in real-time sections with timestamps
+
+### Phase 4: Verification and Post-Execution Validation
+- **Self-verification checks** (module-specific):
+  - Preprocessing: verify BIDS compliance, check for NaN/Inf values, validate normalization ranges
+  - Feature extraction: check output shape consistency, verify statistical properties (mean/std within expected bounds)
+  - Model training: validate loss curve smoothness, check for NaN gradients, verify train/val split integrity
+  - Inference: cross-check predictions for domain-specific constraints (probability bounds, anatomical plausibility)
+- **Result integrity validation**:
+  - Recompute hash of all output files and compare with stored values
+  - Flag any mismatches as potential corruption/tampering
+- **Generate final audit report**: `experiment_audit_report.md` with task execution times, success/failure status, verification results, and reproducibility metadata
+
+### Self-Verification Implementation Details
+
+Each skill integrated into experiment-controller must include **automatic validation steps**:
+
+**Preprocessing validation**:
+```
+- BIDS compliance: confirm file naming, JSON sidecars, required fields
+- Data integrity: NaN/Inf count, range of pixel values, histogram sanity check
+- Statistical bounds: mean/std within neuroimaging norms (e.g., T1w intensity ~0-4000 HU)
+```
+
+**Feature extraction validation**:
+```
+- Output shape check: row/column count match expected dataset size
+- Distribution check: ensure features are not constant or degenerate
+- Correlations: detect and warn on features with >0.95 mutual correlation
+```
+
+**Training validation**:
+```
+- Loss curve smoothness: flag sudden spikes or plateau too early
+- Gradient health: ensure no NaN/Inf gradients during backprop
+- Validation metric monotonicity (for early stopping): warn if validation improves inconsistently
+- Train/val split: cross-verify split ratio and no subject leakage
+```
+
+**Inference validation**:
+```
+- Output shape consistency: predictions match expected target cardinality
+- Domain constraints: probability predictions in [0,1], regression outputs within physiologically plausible ranges
+- Batch effect check: compare results across batch sizes (should be near-identical with same seed)
+```
+
+## Installation
+```bash
+# Place files in: skills/experiment-controller/
+```
+
+## Important Notes & Limitations
+- Always starts from latest IDEA.md + METHOD.md; stops and prompts if missing.
+- Every step and every run is saved as numbered Markdown files for full transparency and resumption.
+- Git clone uses git-essentials/git-workflows (never manual commands outside skills).
+- Dependencies are handled exclusively by dependency-planner.
+- Multiple runs (e.g., ablations) are supported; results are appended with timestamps.
+- Final output always saved/updated as `EXPERIMENT.md` in workspace root.
+- Logs include: command executed, hyperparameters, metrics (accuracy, loss, Dice, etc.), runtime, observations, and any errors.
+
+## When to Call This Skill
+- Immediately after method-design completes METHOD.md
+- When the user wants to run, reproduce, or compare experiments
+- Before paper-writing (to populate quantitative results)
+
+## Complementary / Related Skills
+- `research-idea` → provides IDEA.md
+- `method-design` → provides METHOD.md (input)
+- `multi-search-engine` → literature & GitHub search
+- `git-essentials` / `git-workflows` → clone and manage repositories
+- `dependency-planner` → environment & dependency installation
+- `claw-shell` → internal execution of training scripts
+- `paper-writing` → consumes EXPERIMENT.md for results/tables
+
+## Reference
+NeuroClaw architecture (section 1.7 experiment-controller skill).  
+Flow: literature/GitHub search → user-confirmed scheme → git clone → dependency setup → iterative execution → EXPERIMENT.md logging.  
+
+---
+Created At: 2026-03-24 00:00 HKT
+Last Updated At: 2026-04-05 02:01 HKT
+Author: chengwang96