dsh-aris-panel 0.1.0

package/skills/figure-description/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: figure-description
+description: "Process user-provided patent figures and generate formal drawing descriptions. Use when user says \"附图处理\", \"figure description\", \"附图说明\", \"drawings description\", or wants to describe patent figures with reference numerals."
+argument-hint: "[figure-directory-or-figure-list]"
+allowed-tools: Bash(*), Read, Write, Edit, Grep, Glob, WebSearch, WebFetch
+---
+
+# Figure Description for Patents
+
+Process patent figures and generate drawing descriptions based on: **$ARGUMENTS**
+
+Unlike `/paper-figure` which generates data plots, this skill processes user-provided technical diagrams and assigns reference numerals.
+
+## Constants
+
+- `FIGURE_DIR = "patent/figures/"` — Output directory for figure descriptions
+- `REFERENCE_NUMERAL_PREFIX = 100` — Starting numeral for first figure's components
+- `NUMERAL_SERIES = 100` — Each figure uses a separate 100-series (Fig 1: 100-199, Fig 2: 200-299, etc.)
+
+## Inputs
+
+1. User-provided figures (PNG, JPG, SVG, PDF) — search for them in the project directory
+2. `patent/INVENTION_DISCLOSURE.md` — for understanding what components to identify
+3. `patent/CLAIMS.md` — for mapping numerals to claim elements
+
+## Workflow
+
+### Step 1: Discover Figures
+
+1. Search the project directory for figure files:
+   - Check `patent/figures/`, `figures/`, root directory
+   - Look for PNG, JPG, SVG, PDF files
+   - Check INVENTION_BRIEF.md or INVENTION_DISCLOSURE.md for figure references
+2. List all discovered figures with their paths
+3. If figures are missing that claims require, note them as `[MISSING: description needed]`
+
+### Step 2: Analyze Each Figure
+
+For each figure found:
+
+1. **Read the image** using the Read tool (supports image files)
+2. **Identify components**: What labeled or visually distinct components are shown?
+3. **Identify connections**: How do components relate to each other?
+4. **Identify flow**: If it's a flowchart or sequence, what is the step order?
+
+### Step 3: Assign Reference Numerals
+
+For each figure, assign numerals using the series convention:
+
+| Figure | Numeral Range |
+|--------|-------------|
+| FIG. 1 | 100-199 |
+| FIG. 2 | 200-299 |
+| FIG. 3 | 300-399 |
+
+For each identified component:
+- Assign the next available numeral in the series
+- Cross-reference to the claim elements it supports
+- Note if a component appears in multiple figures (use same numeral across figures)
+
+### Step 4: Generate Drawing Descriptions
+
+Write formal drawing descriptions (附图说明):
+
+**For CN jurisdiction (Chinese)**:
+```
+图1是[发明名称]的系统结构示意图；
+图2是[发明名称]的方法流程图；
+图3是[具体组件]的详细结构示意图；
+```
+
+**For US/EP jurisdiction (English)**:
+```
+FIG. 1 is a block diagram illustrating the system architecture according to one embodiment;
+FIG. 2 is a flowchart illustrating the method steps according to one embodiment;
+FIG. 3 is a detailed view of the processing module of FIG. 1;
+```
+
+### Step 5: Generate Reference Numeral Index
+
+Create a complete mapping:
+
+```markdown
+## Reference Numeral Index
+
+| Numeral | Component Name | Figure(s) | Claim Element |
+|---------|---------------|-----------|---------------|
+| 100 | System | FIG. 1 | Claim X preamble |
+| 102 | Processor | FIG. 1 | Claim X, element 1 |
+| 104 | Memory | FIG. 1 | Claim X, element 2 |
+| 106 | Communication bus | FIG. 1 | Claim X, element 3 |
+| 200 | Method | FIG. 2 | Claim 1 preamble |
+| 202 | Receiving step | FIG. 2 | Claim 1, step 1 |
+| 204 | Processing step | FIG. 2 | Claim 1, step 2 |
+```
+
+### Step 6: Cross-Reference to Claims
+
+Verify that every claim element has at least one reference numeral:
+
+| Claim Element | Figure | Numeral | Status |
+|---------------|--------|---------|--------|
+| [element] | [which fig] | [numeral] | Covered / [MISSING] |
+
+If any claim element has no corresponding figure or numeral, flag it:
+- `[MISSING FIGURE: Need a diagram showing {element description}]`
+- `[MISSING NUMERAL: Component {name} in figure {X} needs a numeral]`
+
+### Step 7: Output
+
+Write `patent/figures/figure_descriptions.md`:
+```markdown
+## Figure Descriptions
+
+### FIG. 1 — [Description]
+[Formal one-paragraph description with all reference numerals]
+
+### FIG. 2 — [Description]
+[Formal one-paragraph description with all reference numerals]
+...
+```
+
+Write `patent/figures/numeral_index.md`:
+```markdown
+## Reference Numeral Index
+
+[Complete table of all numerals, components, figures, and claim mappings]
+```
+
+## Key Rules
+
+- Every component in every figure must have a reference numeral.
+- Every reference numeral must be explained in the specification.
+- Numeral series must be consistent: 100-series for FIG. 1, 200-series for FIG. 2.
+- If the same component appears in multiple figures, use the SAME numeral.
+- Do NOT modify user-provided figures -- only describe them.
+- Flag missing figures that the claims require but the user has not provided.
+- Drawing descriptions are one sentence each, in a consistent format.

package/skills/figure-spec/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: figure-spec
+description: "Generate deterministic publication-quality architecture, workflow, and pipeline diagrams from structured JSON (FigureSpec) into editable SVG. Use when user says \"架构图\", \"workflow 图\", \"pipeline 图\", \"确定性矢量图\", \"figure spec\", \"draw architecture\", or needs precise, editable, publication-ready vector diagrams. Preferred over AI illustration for formal architecture/workflow figures."
+argument-hint: "[description-of-diagram]"
+allowed-tools: Bash(*), Read, Write, Edit, mcp__codex__codex
+---
+
+# FigureSpec: Deterministic JSON → SVG Figure Generation
+
+Generate publication-quality **architecture diagrams**, **workflow pipelines**, **audit cascades**, and **system topology** figures as editable SVG vector graphics using a deterministic JSON → SVG renderer.
+
+## When to Use This Skill
+
+**Use `figure-spec`** for:
+- System architecture diagrams (layered, hub-and-spoke, multi-plane)
+- Workflow / pipeline figures
+- Audit cascade / flow-control diagrams
+- Any structured diagram where node positions, connections, and groupings are semantically important
+- Figures that need to be edited/tweaked later (SVG is plain text)
+- Figures where determinism matters (same spec → same SVG)
+
+**Do NOT use for:**
+- Data plots (bar/line/scatter) — use `/paper-figure`
+- Natural/qualitative illustrations — use `/paper-illustration`
+- Quick state-machine / flowchart — use `/mermaid-diagram` (lighter syntax)
+
+## Core Properties
+
+- **Deterministic**: identical FigureSpec JSON always produces identical SVG output (for a fixed renderer version + fonts)
+- **Editable**: SVG output is plain-text, can be post-edited by hand or programmatically
+- **Validated**: renderer enforces schema, rejects malformed specs with clear error messages
+- **Shape-aware**: edge clipping works correctly for rect/rounded/circle/ellipse/diamond
+- **CJK support**: multi-line labels with proper Chinese character width estimation
+- **No external API**: runs fully local, no network, no API keys
+
+## Tool Location
+
+Phase 3.1 (Arch C) move: the canonical implementation now lives at
+`skills/figure-spec/scripts/figure_renderer.py` (this SKILL's own
+`scripts/` subdirectory). A backwards-compatible shim at
+`tools/figure_renderer.py` forwards to the canonical file via
+`os.execv`, so existing users with `.aris/tools/figure_renderer.py`
+or a manually copied `tools/figure_renderer.py` keep working
+unchanged.
+
+Resolve `$FIGURE_RENDERER` with the hybrid chain (layer 0 prefers the
+self-contained location for the owning SKILL; layers 1-4 are the
+shared-runtime chain documented in
+[`shared-references/integration-contract.md`](../shared-references/integration-contract.md) §2,
+Policy A — skill-local gate):
+
+```bash
+# Layer 0: self-contained (CC 1.0+ exposes $CLAUDE_SKILL_DIR).
+FIGURE_RENDERER=""
+if [ -n "${CLAUDE_SKILL_DIR:-}" ] && [ -f "$CLAUDE_SKILL_DIR/scripts/figure_renderer.py" ]; then
+  FIGURE_RENDERER="$CLAUDE_SKILL_DIR/scripts/figure_renderer.py"
+fi
+# Layers 1-4: shared-runtime chain (legacy compatibility + non-CC hosts).
+if [ -z "$FIGURE_RENDERER" ]; then
+  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
+  FIGURE_RENDERER=".aris/tools/figure_renderer.py"
+  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER="tools/figure_renderer.py"
+  [ -f "$FIGURE_RENDERER" ] || { [ -n "${ARIS_REPO:-}" ] && FIGURE_RENDERER="$ARIS_REPO/tools/figure_renderer.py"; }
+  [ -f "$FIGURE_RENDERER" ] || FIGURE_RENDERER=""
+fi
+[ -z "$FIGURE_RENDERER" ] && {
+  echo "ERROR: figure_renderer.py not resolved (layer 0: \$CLAUDE_SKILL_DIR/scripts/; layers 1-4: .aris/tools/, tools/, \$ARIS_REPO/tools/, \$ARIS_REPO/tools/ via ~/.aris/repo)." >&2
+  echo "       /figure-spec cannot produce SVG output. Fix: rerun bash tools/install_aris.sh or smart_update.sh (refreshes ~/.aris/repo), or copy the helper from \$ARIS_REPO/skills/figure-spec/scripts/." >&2
+  exit 1
+}
+```
+
+Invoke:
+
+```bash
+python3 "$FIGURE_RENDERER" render <spec.json> --output <out.svg>
+python3 "$FIGURE_RENDERER" validate <spec.json>
+python3 "$FIGURE_RENDERER" schema
+```
+
+## Workflow
+
+### Step 1: Understand the Diagram Goal
+
+From `$ARGUMENTS` (description or path to `PAPER_PLAN.md` / `NARRATIVE_REPORT.md`), identify:
+- **Purpose**: architecture, workflow, pipeline, audit cascade, topology?
+- **Main entities**: what are the boxes?
+- **Relationships**: how do they connect? (uses, produces, calls, verifies, chains)
+- **Grouping**: do entities cluster into named regions?
+- **Hierarchy vs network**: stacked layers, left-to-right flow, or central hub?
+
+### Step 2: Draft the FigureSpec JSON
+
+Canvas sizing guide:
+- Single-column figure: ~500×350 px
+- Two-column (full-width): ~900×500 px
+- Tall topology: ~700×700 px
+
+Start from a template based on the diagram type:
+
+**Architecture (stacked rows)**:
+```json
+{
+  "canvas": {"width": 900, "height": 520},
+  "nodes": [
+    {"id": "layer1_label", "label": "Layer 1", "x": 450, "y": 60, ...},
+    {"id": "node_a", "label": "A", "x": 180, "y": 120, ...},
+    {"id": "node_b", "label": "B", "x": 350, "y": 120, ...}
+  ],
+  "edges": [...],
+  "groups": [
+    {"label": "Layer 1", "node_ids": ["node_a", "node_b"], "fill": "#F0F9FF", "stroke": "#BAE6FD"}
+  ]
+}
+```
+
+**Workflow (left-to-right chain)**:
+```json
+{
+  "canvas": {"width": 900, "height": 300},
+  "nodes": [
+    {"id": "step1", "label": "Step 1", "x": 100, "y": 150, "shape": "rounded"},
+    {"id": "step2", "label": "Step 2", "x": 280, "y": 150, "shape": "rounded"}
+  ],
+  "edges": [
+    {"from": "step1", "to": "step2", "label": "produces"}
+  ]
+}
+```
+
+**Decision diamond**:
+```json
+{"id": "check", "label": "Passes?", "shape": "diamond", "x": 450, "y": 200}
+```
+
+### Step 3: Render and Validate
+
+```bash
+# Validate first ($FIGURE_RENDERER was resolved in "Tool Location" above)
+python3 "$FIGURE_RENDERER" validate /tmp/spec.json
+
+# Render to SVG
+python3 "$FIGURE_RENDERER" render /tmp/spec.json --output figures/fig_arch.svg
+
+# Convert to PDF for LaTeX inclusion
+rsvg-convert -f pdf figures/fig_arch.svg -o figures/fig_arch.pdf
+```
+
+If validation fails, inspect the error (missing field, duplicate ID, overlap warning, invalid hex color) and fix the JSON.
+
+### Step 4: Visual Review
+
+Open the SVG/PDF and check:
+- **No overlaps**: nodes don't collide with each other or group boundaries
+- **Readability**: font sizes are consistent, labels aren't clipped
+- **Edge clarity**: arrows hit nodes at clean angles, labels near edges are legible
+- **Group alignment**: background rectangles frame their members cleanly
+- **Color distinction**: categories are visually distinct in both color and grayscale
+
+If issues found, edit the JSON spec (never the generated SVG) and re-render.
+
+### Step 5: Iterate with Codex Review (Optional, for High-Stakes Figures)
+
+For paper architecture figures, invoke cross-model review:
+
+```
+mcp__codex__codex:
+  model: gpt-5.6-sol
+  config: {"model_reasoning_effort": "xhigh"}
+  prompt: |
+    Review this SVG figure for a technical paper (architecture / workflow diagram).
+
+    Spec file: /path/to/spec.json
+    Rendered: /path/to/fig.svg
+
+    Evaluate:
+    1. Clarity (C): can a reader understand the system from this figure alone?
+    2. Readability (R): font sizes, label placement, visual hierarchy
+    3. Semantic accuracy (S): do relationships match the described system?
+
+    Score each axis 1-10 and list specific issues to fix.
+```
+
+Iterate until all three axes ≥ 7/10. The ARIS tech report figures went through 5 rounds of this loop to reach C:7/R:7/S:8.
+
+## Schema Quick Reference
+
+Run `python3 "$FIGURE_RENDERER" schema` (resolve $FIGURE_RENDERER per "Tool Location" above) for the authoritative schema.
+
+### Nodes
+
+| Field | Required | Default | Notes |
+|-------|----------|---------|-------|
+| `id` | ✓ | — | Unique |
+| `label` | ✓ | — | `\n` for multi-line |
+| `x`, `y` | ✓ | — | Center coordinates |
+| `width`, `height` | | 120, 50 | |
+| `shape` | | `rounded` | `rect` / `rounded` / `circle` / `ellipse` / `diamond` |
+| `fill`, `stroke` | | auto from palette | `#RRGGBB` |
+| `text_color` | | `#333333` | |
+| `font_size` | | 14 | Override style default |
+
+### Edges
+
+| Field | Default | Notes |
+|-------|---------|-------|
+| `from`, `to` | required | Same = self-loop |
+| `label` | — | Short edge label |
+| `style` | `solid` | `solid` / `dashed` / `dotted` |
+| `color` | `#555555` | |
+| `curve` | `false` | Curved path |
+
+### Groups
+
+Rectangular background regions framing a set of nodes:
+```json
+{"label": "Layer Name", "node_ids": ["a", "b", "c"], "fill": "#EFF6FF", "stroke": "#BFDBFE"}
+```
+
+## Design Patterns
+
+### Pattern 1: Layered Architecture
+Stack rows of related nodes, each row is a group, add inter-layer arrows with semantic labels (`uses↓`, `produces↑`, `checks↓`).
+
+### Pattern 2: Hub-and-Spoke
+Central node (e.g., Executor), peripheral nodes (skills, tools), solid arrows for primary relations, dashed for feedback.
+
+### Pattern 3: Pipeline with Feedback
+Left-to-right main flow, feedback arrows curve below with `curve: true`.
+
+### Pattern 4: Audit Cascade
+Three-stage horizontal cascade with inputs feeding in from top, outputs exiting right, each stage in its own group.
+
+## Anti-Patterns
+
+- **Don't use groups as hierarchy**: groups frame peer nodes, not containment
+- **Don't nest groups**: renderer draws them as background rectangles; nested groups look like Russian dolls
+- **Don't cross-draw long diagonals**: if an arrow crosses 3+ rows, rethink the layout
+- **Don't mix font sizes for same role**: keep one size per node category
+
+## Output Contract
+
+- SVG file in `figures/` (vector, editable, hand-tweakable)
+- Source FigureSpec JSON saved in `figures/specs/` for reproducibility
+- PDF version via `rsvg-convert` for LaTeX inclusion
+
+## Integration with Other Skills
+
+- **`/paper-writing`** (Workflow 3): when `illustration: figurespec` (default for architecture figures), this skill handles Phase 2b
+- **`/paper-figure`**: handles data plots; they complement each other (data + architecture = complete figure set)
+- **`/paper-illustration`**: fallback for figures that need natural/qualitative style (method illustrations with photos, qualitative result grids)
+- **`/mermaid-diagram`**: lighter alternative for simple flowcharts
+
+## Review Tracing
+
+After each `mcp__codex__codex` or `mcp__codex__codex-reply` reviewer call, save the trace following `shared-references/review-tracing.md` (Policy C — forensic; never silently skip). Use `save_trace.sh` (resolved per the chain in `shared-references/integration-contract.md` §2) or write files directly to `.aris/traces/<skill>/<date>_run<NN>/`. Respect the `--- trace:` parameter (default: `full`).