dsh-aris-panel 0.1.0

package/skills/deepxiv/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: deepxiv
+description: Search and progressively read open-access academic papers through DeepXiv. Use when the user wants layered paper access, section-level reading, trending papers, or DeepXiv-backed literature retrieval.
+argument-hint: "[query-or-paper-id]"
+allowed-tools: Bash(*), Read, Write
+---
+
+# DeepXiv Paper Search & Progressive Reading
+
+Search topic or paper ID: $ARGUMENTS
+
+## Role & Positioning
+
+DeepXiv is the **progressive-reading** literature source:
+
+| Skill | Source | Best for |
+|-------|--------|----------|
+| `/arxiv` | arXiv API | Batch search, PDF download, metadata |
+| **`/deepxiv`** | **DeepXiv SDK** | **Progressive section-level reading** |
+| `/semantic-scholar` | S2 API | Published venue metadata, citation counts |
+| `/alphaxiv` | alphaxiv.org | Instant LLM-optimized summary of one paper, with LaTeX source fallback |
+
+Use DeepXiv when you want to avoid loading full papers too early.
+
+## Constants
+
+- **DEEPXIV_FETCHER** — canonical name `deepxiv_fetch.py`, resolved per
+  [`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2
+  (Policy D1 — primary + fallback cascade). If unresolved (canonical
+  chain exhausted), fall back to the raw `deepxiv` CLI (documented per
+  command below).
+- **MAX_RESULTS = 10** — Default number of results to return.
+
+> Overrides (append to arguments):
+> - `/deepxiv "agent memory" - max: 5` — top 5 results
+> - `/deepxiv "2409.05591" - brief` — quick paper summary
+> - `/deepxiv "2409.05591" - head` — metadata + section overview
+> - `/deepxiv "2409.05591" - section: Introduction` — read one section only
+> - `/deepxiv "trending" - days: 14 - max: 10` — trending papers
+> - `/deepxiv "karpathy" - web` — DeepXiv web search
+> - `/deepxiv "258001" - sc` — Semantic Scholar metadata by ID
+
+## Setup
+
+DeepXiv is optional. If the CLI is not installed, tell the user:
+
+```bash
+pip install deepxiv-sdk
+```
+
+On first use, `deepxiv` auto-registers a free token and stores it in `~/.env`.
+
+## Workflow
+
+### Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for:
+
+- **Query or ID**: a paper topic, arXiv ID, or Semantic Scholar ID
+- **`- max: N`**: override `MAX_RESULTS`
+- **`- brief`**: fetch paper brief
+- **`- head`**: fetch metadata and section map
+- **`- section: NAME`**: fetch one named section
+- **`- trending`** or query `trending`: fetch trending papers
+- **`- days: 7|14|30`**: trending time window
+- **`- web`**: run DeepXiv web search
+- **`- sc`**: fetch Semantic Scholar metadata by ID
+
+If the main argument looks like an arXiv ID and no explicit mode is given, default to `- brief`.
+
+### Step 2: Locate the Adapter
+
+Resolve `$DEEPXIV_FETCHER` via the canonical strict-safe chain (see
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2).
+Policy D1 cascade: the resolved adapter is preferred; if unresolved
+(canonical chain exhausted), fall back to raw `deepxiv` CLI commands
+documented in Step 3.
+
+```bash
+cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+if [ -z "${ARIS_REPO:-}" ] && [ -f .aris/installed-skills.txt ]; then
+    ARIS_REPO=$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null) || true
+fi
+if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
+    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
+fi
+DEEPXIV_FETCHER=".aris/tools/deepxiv_fetch.py"
+[ -f "$DEEPXIV_FETCHER" ] || DEEPXIV_FETCHER="tools/deepxiv_fetch.py"
+[ -f "$DEEPXIV_FETCHER" ] || { [ -n "${ARIS_REPO:-}" ] && DEEPXIV_FETCHER="$ARIS_REPO/tools/deepxiv_fetch.py"; }
+[ -f "$DEEPXIV_FETCHER" ] || DEEPXIV_FETCHER=""
+
+# Smoke test (optional — adapter resolution shown to user). The cascade
+# in Step 3 below branches purely on `[ -n "$DEEPXIV_FETCHER" ]`; a
+# resolved-but-non-functional adapter is not currently auto-demoted.
+if [ -n "$DEEPXIV_FETCHER" ]; then
+  echo "DeepXiv adapter resolved at: $DEEPXIV_FETCHER" >&2
+else
+  echo "DeepXiv adapter unresolved (canonical chain exhausted); raw deepxiv CLI fallback will be used." >&2
+fi
+```
+
+### Step 3: Execute the Minimal Command
+
+**Search papers**
+
+```bash
+python3 "$DEEPXIV_FETCHER" search "QUERY" --max MAX_RESULTS
+```
+
+Fallback:
+
+```bash
+deepxiv search "QUERY" --limit MAX_RESULTS --format json
+```
+
+**Brief summary**
+
+```bash
+python3 "$DEEPXIV_FETCHER" paper-brief ARXIV_ID
+```
+
+Fallback:
+
+```bash
+deepxiv paper ARXIV_ID --brief --format json
+```
+
+**Section map**
+
+```bash
+python3 "$DEEPXIV_FETCHER" paper-head ARXIV_ID
+```
+
+Fallback:
+
+```bash
+deepxiv paper ARXIV_ID --head --format json
+```
+
+**Specific section**
+
+```bash
+python3 "$DEEPXIV_FETCHER" paper-section ARXIV_ID "SECTION_NAME"
+```
+
+Fallback:
+
+```bash
+deepxiv paper ARXIV_ID --section "SECTION_NAME" --format json
+```
+
+**Trending**
+
+```bash
+python3 "$DEEPXIV_FETCHER" trending --days 7 --max MAX_RESULTS
+```
+
+Fallback:
+
+```bash
+deepxiv trending --days 7 --limit MAX_RESULTS --output json
+```
+
+**Web search**
+
+```bash
+python3 "$DEEPXIV_FETCHER" wsearch "QUERY"
+```
+
+Fallback:
+
+```bash
+deepxiv wsearch "QUERY" --output json
+```
+
+**Semantic Scholar metadata**
+
+```bash
+python3 "$DEEPXIV_FETCHER" sc "SEMANTIC_SCHOLAR_ID"
+```
+
+Fallback:
+
+```bash
+deepxiv sc "SEMANTIC_SCHOLAR_ID" --output json
+```
+
+### Step 4: Present Results
+
+When searching, present a compact table:
+
+```text
+| # | ID | Title | Year | Citations | Notes |
+|---|----|-------|------|-----------|-------|
+```
+
+When reading a paper, show:
+
+- title
+- arXiv ID
+- authors
+- venue/date if available
+- TLDR or abstract summary
+- suggested next step: `brief` → `head` → `section`
+
+### Step 5: Escalate Depth Only When Needed
+
+Use this progression:
+
+1. `search`
+2. `paper-brief`
+3. `paper-head`
+4. `paper-section`
+5. full paper only if necessary
+
+Do not jump to full-paper reads when a brief or one section answers the question.
+
+### Step 6: Update Research Wiki (if active)
+
+**Required when `research-wiki/` exists in the project**; skip silently
+otherwise. When the wiki dir exists, resolve `$WIKI_SCRIPT` per the
+canonical chain at
+[`shared-references/wiki-helper-resolution.md`](../shared-references/wiki-helper-resolution.md)
+(Variant B — warn-and-skip). Ingest papers that were meaningfully
+read (brief / head / section / full) during this invocation — mere
+`search` hits without a depth read do not need ingestion:
+
+```bash
+if [ -d research-wiki/ ]; then
+  cd "$(git rev-parse --show-toplevel 2>/dev/null || pwd)" || exit 1
+  ARIS_REPO="${ARIS_REPO:-$(awk -F'\t' '$1=="repo_root"{print $2; exit}' .aris/installed-skills.txt 2>/dev/null)}"
+  if [ -z "${ARIS_REPO:-}" ] && [ -f "$HOME/.aris/repo" ]; then
+    ARIS_REPO=$(cat "$HOME/.aris/repo" 2>/dev/null) || true
+  fi
+  WIKI_SCRIPT=".aris/tools/research_wiki.py"
+  [ -f "$WIKI_SCRIPT" ] || WIKI_SCRIPT="tools/research_wiki.py"
+  [ -f "$WIKI_SCRIPT" ] || { [ -n "${ARIS_REPO:-}" ] && WIKI_SCRIPT="$ARIS_REPO/tools/research_wiki.py"; }
+  [ -f "$WIKI_SCRIPT" ] || {
+    echo "WARN: research_wiki.py not found; depth-read summary delivered, wiki ingest skipped. Fix: bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), export ARIS_REPO, or cp <ARIS-repo>/tools/research_wiki.py tools/." >&2
+    WIKI_SCRIPT=""
+  }
+  if [ -n "$WIKI_SCRIPT" ]; then
+    for each arxiv_id the user asked this skill to read in depth:
+        python3 "$WIKI_SCRIPT" ingest_paper research-wiki/ \
+            --arxiv-id "<arxiv_id>"
+  fi
+fi
+```
+
+The helper handles metadata / slug / dedup / page / index / log in one
+call — **do not handwrite `papers/<slug>.md`**. See
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md).
+Backfill missed ingests with
+`python3 "$WIKI_SCRIPT" sync research-wiki/ --arxiv-ids <id1>,<id2>,...`
+after resolving `$WIKI_SCRIPT` as above.
+
+## Key Rules
+
+- Prefer the adapter script over raw `deepxiv` commands when available.
+- DeepXiv is optional. If unavailable, give the install command and suggest `/arxiv` or `/research-lit "topic" - sources: web`.
+- Use section-level reads to save tokens.
+- Treat DeepXiv as complementary to `/arxiv` and `/semantic-scholar`, not a replacement.
+- If the result overlaps with a published venue paper from Semantic Scholar, keep the richer venue metadata in the final summary.

package/skills/dse-loop/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: dse-loop
+description: "Autonomous design space exploration loop for computer architecture and EDA. Runs a program, analyzes results, tunes parameters, and iterates until objective is met or timeout. Use when user says \"DSE\", \"design space exploration\", \"sweep parameters\", \"optimize\", \"find best config\", or wants iterative parameter tuning."
+argument-hint: "[task-description — include program, parameters, objective, and timeout]"
+allowed-tools: Bash(*), Read, Grep, Glob, Write, Edit
+---
+
+# DSE Loop: Autonomous Design Space Exploration
+
+> 🔁 **Do not wrap this skill in `/loop` / `CronCreate`.** It already loops
+> internally until its objective is met or it times out. Unlike the
+> verdict-bearing review/audit skills, its stop gate is an **objective
+> machine-checkable metric** (Type-A), so its self-termination is safe
+> same-model — the reason not to wrap it is **scheduler duplication**, not the
+> verdict fence. See
+> [`shared-references/external-cadence.md`](../shared-references/external-cadence.md).
+
+Autonomously explore a design space: run → analyze → pick next parameters → repeat, until the objective is met or timeout is reached. Designed for computer architecture and EDA problems.
+
+## Context: $ARGUMENTS
+
+## Safety Rules — READ FIRST
+
+**NEVER do any of the following:**
+- `sudo` anything
+- `rm -rf`, `rm -r`, or any recursive deletion
+- `rm` any file you did not create in this session
+- Overwrite existing source files without reading them first
+- `git push`, `git reset --hard`, or any destructive git operation
+- Kill processes you did not start
+
+**If a step requires any of the above, STOP and report to the user.**
+
+## Constants (override via $ARGUMENTS)
+
+| Constant | Default | Description |
+|----------|---------|-------------|
+| `TIMEOUT` | 2h | Total wall-clock budget. Stop exploring after this. |
+| `MAX_ITERATIONS` | 50 | Hard cap on number of design points evaluated. |
+| `PATIENCE` | 10 | Stop early if no improvement for this many consecutive iterations. |
+| `OBJECTIVE` | minimize | `minimize` or `maximize` the target metric. |
+
+Override inline: `/dse-loop "task desc — timeout: 4h, max_iterations: 100, patience: 15"`
+
+## Typical Use Cases
+
+| Problem | Program | Parameters | Objective |
+|---------|---------|-----------|-----------|
+| Microarch DSE | gem5 simulation | cache size, assoc, pipeline width, ROB size, branch predictor | maximize IPC or minimize area×delay |
+| Synthesis tuning | yosys/DC script | optimization passes, target freq, effort level | minimize area at timing closure |
+| RTL parameterization | verilator sim | data width, FIFO depth, pipeline stages, buffer sizes | meet throughput target at min area |
+| Compiler flags | gcc/llvm build + benchmark | -O levels, unroll factor, vectorization, scheduling | minimize runtime or code size |
+| Placement/routing | openroad/innovus | utilization, aspect ratio, layer config | minimize wirelength / timing |
+| Formal verification | abc/sby | bound depth, engine, timeout per property | maximize coverage in time budget |
+| Memory subsystem | cacti / ramulator | bank count, row buffer policy, scheduling | optimize bandwidth/energy |
+
+## Workflow
+
+### Phase 0: Parse Task & Setup
+
+1. **Parse $ARGUMENTS** to extract:
+   - **Program**: what to run (command, script, or Makefile target)
+   - **Parameter space**: which knobs to tune and their ranges/options (may be incomplete — see step 2)
+   - **Objective metric**: what to optimize (and how to extract it from output)
+   - **Constraints**: hard limits that must not be violated (e.g., timing must close)
+   - **Timeout**: wall-clock budget
+   - **Success criteria**: when is the result "good enough" to stop early?
+
+2. **Infer missing parameter ranges** — If the user provides parameter names but NOT ranges/options, you MUST infer them before exploring:
+
+   a. **Read the source code** — search for the parameter names in the codebase:
+      - Look for argparse/click definitions, config files, Makefile variables, module parameters, `#define`, `parameter` (SystemVerilog), `localparam`, etc.
+      - Extract defaults, types, and any comments hinting at valid values
+
+   b. **Apply domain knowledge** to set reasonable ranges:
+      | Parameter type | Inference strategy |
+      |---------------|-------------------|
+      | Cache/memory sizes | Powers of 2, typically 1KB–16MB |
+      | Associativity | Powers of 2: 1, 2, 4, 8, 16 |
+      | Pipeline width / issue width | Small integers: 1, 2, 4, 8 |
+      | Buffer/queue/FIFO depth | Powers of 2: 4, 8, 16, 32, 64 |
+      | Clock period / frequency | Based on technology node; try ±50% from default |
+      | Bound depth (BMC/formal) | Geometric: 5, 10, 20, 50, 100 |
+      | Timeout values | Geometric: 10s, 30s, 60s, 120s, 300s |
+      | Boolean/enum flags | Enumerate all options found in source |
+      | Continuous (learning rate, threshold) | Log-scale sweep: 5 points spanning 2 orders of magnitude around default |
+      | Integer counts (threads, cores) | Linear: from 1 to hardware max |
+
+   c. **Start conservative** — begin with 3-5 values per parameter. Expand range later if the best result is at a boundary.
+
+   d. **Log inferred ranges** — write the inferred parameter space to `dse_results/inferred_params.md` so the user can review:
+      ```markdown
+      # Inferred Parameter Space
+
+      | Parameter | Source | Default | Inferred Range | Reasoning |
+      |-----------|--------|---------|---------------|-----------|
+      | CACHE_SIZE | config.py:42 | 32768 | [8192, 16384, 32768, 65536, 131072] | powers of 2, ±2x from default |
+      | ASSOC | config.py:43 | 4 | [1, 2, 4, 8] | standard associativities |
+      | BMC_DEPTH | run_bmc.py:15 | 10 | [5, 10, 20, 50] | geometric, common BMC depths |
+      ```
+
+   e. **Boundary expansion** — during the search, if the best result is at the min or max of a range, automatically extend that range by one step in that direction (but log the extension).
+
+3. **Read the project** to understand:
+   - How to run the program
+   - Where results are produced (stdout, log files, reports)
+   - How to parse the objective metric from output
+   - Current/baseline configuration (if any)
+
+4. **Create working directory**: `dse_results/` in project root
+   - `dse_results/dse_log.csv` — one row per design point
+   - `dse_results/DSE_REPORT.md` — final report
+   - `dse_results/DSE_STATE.json` — state for recovery
+   - `dse_results/inferred_params.md` — inferred parameter space (if ranges were not provided)
+   - `dse_results/configs/` — config files for each run
+   - `dse_results/outputs/` — raw output for each run
+
+5. **Write a parameter extraction script** (`dse_results/parse_result.py` or similar) that takes a run's output and returns the objective metric as a number. Test it on a baseline run first.
+
+6. **Run baseline** (iteration 0): run the program with default/current parameters. Record the baseline metric. This is the point to beat.
+
+### Phase 1: Initial Exploration
+
+**Goal**: Quickly survey the space to understand which parameters matter most.
+
+**Strategy**: Latin Hypercube Sampling or structured sweep of key parameters.
+
+1. Pick 5-10 diverse design points that span the parameter ranges
+2. Run them (in parallel if independent, via background processes or sequential)
+3. Record all results in `dse_log.csv`:
+   ```
+   iteration,param1,param2,...,metric,constraint_met,timestamp,notes
+   0,default,default,...,baseline_val,yes,2026-03-13T10:00:00,baseline
+   1,val1a,val2a,...,result1,yes,2026-03-13T10:05:00,initial sweep
+   ...
+   ```
+4. Analyze: which parameters have the most impact on the objective?
+5. Narrow the search to the most sensitive parameters
+
+### Phase 2: Directed Search
+
+**Goal**: Converge toward the optimum by making informed choices.
+
+**Strategy**: Adaptive — pick the approach that fits the problem:
+
+- **Few parameters (≤3)**: Fine-grained grid search around the best region from Phase 1
+- **Many parameters (>3)**: Coordinate descent — optimize one parameter at a time, holding others at current best
+- **Binary/categorical params**: Enumerate promising combinations
+- **Continuous params**: Binary search or golden section between best neighbors
+- **Multi-objective**: Track Pareto frontier, explore along the front
+
+For each iteration:
+
+1. **Select next design point** based on results so far:
+   - Look at the trend: which direction improves the metric?
+   - Avoid re-running configurations already evaluated
+   - Balance exploration (untested regions) vs exploitation (near current best)
+
+2. **Modify parameters**: edit config file, command-line args, or source constants
+
+3. **Run the program**: execute and capture output
+
+4. **Parse results**: extract the objective metric and check constraints
+
+5. **Log to `dse_log.csv`**: append the new row
+
+6. **Check stopping conditions**:
+   - Timeout reached? → stop
+   - Max iterations reached? → stop
+   - Patience exhausted (no improvement in N iterations)? → stop
+   - Success criteria met (metric is "good enough")? → stop
+   - Constraint violation pattern detected? → adjust search bounds
+
+7. **Update `DSE_STATE.json`**:
+   ```json
+   {
+     "iteration": 15,
+     "status": "in_progress",
+     "best_metric": 1.23,
+     "best_params": {"cache_size": 32768, "assoc": 4, "pipeline_width": 2},
+     "total_iterations": 15,
+     "start_time": "2026-03-13T10:00:00",
+     "timeout": "2h",
+     "patience_counter": 3
+   }
+   ```
+
+8. **Decide next step** → back to step 1
+
+### Phase 3: Refinement (if time allows)
+
+If the search converged and there's still time budget:
+
+1. **Local perturbation**: try ±1 step on each parameter from the best point
+2. **Sensitivity analysis**: which parameters can be relaxed without hurting the metric?
+3. **Constraint boundary**: if a constraint is nearly binding, explore near-feasible points
+
+### Phase 4: Report
+
+Write `dse_results/DSE_REPORT.md`:
+
+```markdown
+# Design Space Exploration Report
+
+**Task**: [description]
+**Date**: [start] → [end]
+**Total iterations**: N
+**Wall-clock time**: X hours Y minutes
+
+## Objective
+- **Metric**: [what was optimized]
+- **Direction**: minimize / maximize
+- **Baseline**: [value]
+- **Best found**: [value] ([improvement]% better than baseline)
+
+## Best Configuration
+| Parameter | Baseline | Best |
+|-----------|----------|------|
+| param1    | default  | best_val |
+| param2    | default  | best_val |
+| ...       | ...      | ... |
+
+## Search Trajectory
+| Iteration | param1 | param2 | ... | Metric | Notes |
+|-----------|--------|--------|-----|--------|-------|
+| 0 (baseline) | ... | ... | ... | ... | baseline |
+| 1 | ... | ... | ... | ... | initial sweep |
+| ... | ... | ... | ... | ... | ... |
+| N (best) | ... | ... | ... | ... | ★ best |
+
+## Parameter Sensitivity
+- **param1**: [high/medium/low impact] — [brief explanation]
+- **param2**: [high/medium/low impact] — [brief explanation]
+
+## Pareto Frontier (if multi-objective)
+[Table or description of non-dominated points]
+
+## Stopping Reason
+[timeout / max_iterations / patience / success_criteria_met]
+
+## Recommendations
+- [actionable insights from the exploration]
+- [which parameters matter most]
+- [suggested follow-up explorations]
+```
+
+Also generate a summary plot if matplotlib is available:
+- Convergence curve (metric vs iteration)
+- Parameter sensitivity bar chart
+- Pareto frontier scatter (if multi-objective)
+
+## State Recovery
+
+If the context window compacts mid-run, the loop recovers from `DSE_STATE.json` + `dse_log.csv`:
+
+1. Read `DSE_STATE.json` for current iteration, best params, patience counter
+2. Read `dse_log.csv` for full history
+3. Resume from next iteration
+
+## Key Rules
+
+- Work AUTONOMOUSLY — do not ask the user for permission at each iteration
+- **Every run must be logged** — even failed runs, constraint violations, errors. The log is the ground truth.
+- **Never re-run an identical configuration** — check `dse_log.csv` before each run
+- **Respect the timeout** — check elapsed time before starting a new iteration. If the next run is likely to exceed the timeout, stop and report.
+- **Parse metrics programmatically** — write a parsing script, don't eyeball logs
+- **Keep raw outputs** — save each run's full output in `dse_results/outputs/iter_N/`
+- **Constraint violations are not improvements** — a design point that violates constraints is never "best", regardless of the metric
+- If a run crashes, log the error, skip that point, and continue with the next
+- If the same crash repeats 3 times with different configs, the harness code itself is
+  the suspect — **discard and reimplement the run/parse script cleanly from the spec**
+  (a peer move to another patch; delete only the script, never `dse_log.csv` /
+  `dse_results/`; see `shared-references/external-cadence.md` § *Let a broken attempt
+  restart, not just patch*). **Before resuming the sweep, re-validate metric
+  comparability**: re-parse one COMPLETED iteration's raw output from
+  `dse_results/outputs/iter_N/` with the new parser and confirm it reproduces that row of
+  `dse_log.csv`; on mismatch, either fix the parser or re-parse and flag all affected
+  rows — never mix two parsing semantics in one log. If a clean reimplement crashes the
+  same way, stop and report — the spec or the environment is then in question, which is
+  what needs the human
+
+## Example Invocations
+
+```
+# Minimal — just name the parameters, let the agent figure out ranges
+/dse-loop "Run gem5 mcf benchmark. Tune: L1D_SIZE, L2_SIZE, ROB_ENTRIES. Objective: maximize IPC. Timeout: 3h"
+
+# Partial — some ranges given, some not
+/dse-loop "Run make synth. Tune: CLOCK_PERIOD [5ns, 4ns, 3ns, 2ns], FLATTEN, ABC_SCRIPT. Objective: minimize area at timing closure. Timeout: 1h"
+
+# Fully specified — explicit ranges for everything
+/dse-loop "Simulate processor with FIFO_DEPTH [4,8,16,32], ISSUE_WIDTH [1,2,4], PREFETCH [on,off]. Run: make sim. Objective: max throughput/area. Timeout: 2h"
+
+# Real-world: PDAG-SFA formal verification tuning
+/dse-loop "Run python run_bmc.py. Tune: BMC_DEPTH, ENGINE, TIMEOUT_PER_PROP. Objective: maximize properties proved. Timeout: 2h"
+```

package/skills/embodiment-description/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: embodiment-description
+description: "Write detailed embodiment descriptions for patent specifications. Use when user says \"撰写实施例\", \"write embodiment\", \"实施例描述\", \"detailed description\", or wants to describe how to practice an invention."
+argument-hint: "[claims-path-or-embodiment-details]"
+allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob
+---
+
+# Embodiment Description
+
+Write detailed embodiments for: **$ARGUMENTS**
+
+Embodiments describe HOW to make and use the invention -- they are the patent equivalent of experiment sections, but describe the invention rather than evaluating it empirically.
+
+## Constants
+
+- `MIN_EMBODIMENTS = 1` — At least one complete embodiment required
+- `MAX_EMBODIMENTS = 3` — Practical limit; more embodiments strengthen enablement
+- `EMBODIMENT_STYLE = detailed` — `detailed` (full working example) or `outline` (sketch)
+- `REFERENCE_NUMERAL_PREFIX = 100` — Starting reference numeral for first figure's components
+
+## Inputs
+
+1. `patent/INVENTION_DISCLOSURE.md` — invention decomposition (core/supporting/optional features)
+2. `patent/CLAIMS.md` — drafted claims that the embodiments must support
+3. User-provided figures (if any) in any directory
+4. `patent/figures/numeral_index.md` if it exists (from `/figure-description`)
+
+## Workflow
+
+### Step 1: Plan Embodiments
+
+For each claim category (method, system, etc.), plan at least one embodiment:
+
+| Embodiment | Covers Claims | Type | Key Variations |
+|-----------|--------------|------|----------------|
+| 1 | Claims 1, X | Best mode / preferred | [primary implementation] |
+| 2 | Claims 2, 3 | Alternative | [different parameters/materials] |
+| 3 | Claims 4, 5 | Additional alternative | [different configuration] |
+
+### Step 2: Write Each Embodiment
+
+For each embodiment, write a detailed description following this structure:
+
+**Opening paragraph**:
+"In one embodiment, [invention summary with reference to what is being described]."
+
+**Component/step-by-step description**:
+
+For method embodiments:
+- Describe each step in order
+- Reference figure numerals: "As shown in FIG. 1, at step 202, the processor 102 receives the input data 104..."
+- Include specific parameters, ranges, and conditions
+- Describe what happens at each decision point
+
+For system/apparatus embodiments:
+- Describe each component
+- Reference figure numerals: "Referring to FIG. 1, the system 100 comprises a processor 102, a memory 104, and a communication interface 106..."
+- Describe interconnections between components
+- Describe operation of the system step-by-step
+
+**Variations and alternatives**:
+- "In some embodiments, the processor 102 may be a GPU, an FPGA, or an ASIC."
+- "In another embodiment, the memory 104 may be replaced with a distributed storage system."
+- "The parameters described above are exemplary; other values within the range [X, Y] are also contemplated."
+
+These variations are critical -- they support broader claim interpretation.
+
+### Step 3: Reference Numeral Integration
+
+Ensure consistent reference numeral usage:
+
+1. Every component mentioned must have a numeral
+2. Numeral must appear first in parentheses after the component name: "the processor (102)"
+3. Subsequent references: "the processor 102" (no parentheses)
+4. Numbering follows figure series: 100-series for FIG. 1, 200-series for FIG. 2
+
+**Format**:
+- First mention: "the processor (102)"
+- Later in same embodiment: "the processor 102"
+- Cross-figure: "the processor 102 (shown in both FIG. 1 and FIG. 2)"
+
+### Step 4: Claim Support Verification
+
+For each claim element, verify it appears in at least one embodiment:
+
+| Claim Element | Embodiment | Reference Numeral | Description Paragraph |
+|---------------|-----------|-------------------|----------------------|
+| [element] | [which] | [numeral] | [paragraph reference] |
+
+If any claim element lacks embodiment support, add the necessary description.
+
+### Step 5: Software/Algorithm Embodiments (if applicable)
+
+For method/software inventions, include:
+- Pseudocode or algorithmic description (NOT actual code)
+- Flowchart description tied to figures
+- Data structure descriptions
+- Interface specifications
+
+Example:
+```
+In one embodiment, the method comprises the following steps:
+At step 202, the processor 102 receives input data from the input device 108.
+At step 204, the processor 102 extracts feature vectors from the input data using a convolutional neural network.
+At step 206, the processor 102 applies the attention mechanism 110 to the feature vectors...
+```
+
+### Step 6: Output
+
+Embodiment sections are written to `patent/specification/detailed_description.md` (or appended to the specification structure).
+
+Each embodiment section should be self-contained but cross-reference other embodiments when describing alternatives.
+
+## Key Rules
+
+- Embodiments must teach a POSITA to make and use the invention without undue experimentation.
+- Include at least one "best mode" embodiment (US requirement).
+- Multiple embodiments strengthen the specification against enablement challenges.
+- Describe the invention, do NOT evaluate it empirically ("The embodiment achieves 95% accuracy" is wrong; "The processor classifies the input data" is correct).
+- **CRITICAL — NO experimental data, test results, accuracy percentages, detection rates, precision values, or comparative performance data.** These belong in papers, not patents. The embodiment teaches HOW to make and use, not HOW WELL it performs.
+- WRONG: "传感器对直径超过150μm的金属颗粒实现了100%的检测精度，即使在检测限处仍保持94%的高精度。"
+- RIGHT: "当不锈钢颗粒通过间隙传感区域时，谐振频率下降。颗粒直径越大，频率偏移幅度越大。"
+- Do NOT include tables of experimental results, graphs of measurement data, or comparisons with prior art performance.
+- **CRITICAL — An embodiment is NOT an experiment.** Do NOT describe "repeated experiments", "accuracy evaluation", "precision testing", "calibration experiments", or "comparison with reference methods". An embodiment describes ONE way to make and use the invention — it is a recipe, not a test report.
+- Do NOT copy experimental sections from source papers verbatim. Transform the experimental setup into a manufacturing/operation description.
+- If the source material is a paper, extract ONLY: (1) what was built, (2) what materials/parameters were used, (3) how it operates. Ignore all test methodology, results, and performance metrics.
+- Include specific parameters where possible, but frame them as exemplary, not limiting.
+- Reference numerals must be consistent with the figures.
+- Do NOT use subjective language ("excellent", "surprising", "superior").