math-skill 2.1.0 → 3.0.1

package/skills/math-research-activator/SKILL.en.md

@@ -1,132 +1,213 @@
 ---
 name: math-research-activator
 description: |
-  Auto-trigger (requires BOTH environment AND task signals): only when **designing/improving** new model architectures/operators/attention mechanisms, **analyzing** algorithm theoretical properties (complexity, convergence, expressivity), or **transferring** modern math structures (algebraic geometry, differential geometry, Lie theory, abstract algebra, matrix analysis, optimization) into algorithm/GPU co-design. Does NOT trigger for: code review, debugging, parameter tracing, refactoring, hyperparameter tuning, or loss implementation edits. Also the manual /ask entry (weapon selector).
+  Mathematical research OS — auto-diagnoses user intent, routes to thinking lenses, math knowledge base, or design translation layer. Triggers on architecture/operator design, theoretical analysis, math-to-AI transfer. Does NOT trigger for pure engineering tasks (debug, refactoring, hyperparameter tuning).
 ---
 
-# 🧭 Math Research Activator
 
-> "The model already holds enough mathematics inside; what's missing is a cross-domain activation. The human picks the direction; the agent searches, enumerates, verifies."
+> **File routing**: When this document references any file (lenses, knowledge-base, design-patterns, references, agents), always load the `.en.md` variant if it exists. For example, `../../lenses/symmetry.md` → load `lenses/symmetry.en.md`.
+>
+> ## Language Routing & Mixed-Input Rules
+>
+> Language routing only determines "which language version to read" and "what language to respond in." It does NOT affect whether the math system triggers or the A/B/C/D/E scenario classification.
+>
+> ### Decision Rules
+>
+> 1. **Judge the natural-language frame first**
+>    - If the user's sentence structure, verbs, and mood particles are primarily Chinese, treat as Chinese even if English technical terms are interspersed.
+>    - E.g., "帮我 design 一个 attention" / "这个 loss 有没有理论问题" → Chinese.
+>
+> 2. **English technical terms do not count as English primary language**
+>    - attention, loss, routing, embedding, manifold, operator, kernel, KV-cache, transformer, MoE, etc. are domain terms and do not trigger a switch to English.
+>
+> 3. **Code, paths, and formulas are excluded from language detection**
+>    - File paths, function names, variable names, LaTeX formulas, and CLI arguments do not count toward language ratio.
+>
+> 4. **When primary language is unclear, follow the user's last clear language**
+>    - If the CN/EN ratio is close and indeterminate, use the user's most recent unambiguous natural language.
+>    - If there is no prior context, default to Chinese.
+>
+> 5. **Output language matches primary language**
+>    - Chinese primary → read `SKILL.md`, respond in Chinese, retaining necessary English terms.
+>    - English primary → read `SKILL.en.md`, respond in English.
+>    - If the user explicitly requests "in English" / "in Chinese," follow the explicit request.
+
+# Math Research OS
+
+> "The thinking system does not hand out theorems, the knowledge system does not indulge in loose inspiration, and the design layer does not fake profundity."
+
+This system is a mathematical staff office for AI architecture innovation — not an arsenal, but one that tells you: **what kind of battle this is, which arms to deploy, how to deploy them, and where things could go wrong.**
+
+## Three-Layer Orthogonal Architecture
+
+| Layer | Responsibility | Directory | Core Question |
+|-------|---------------|-----------|--------------|
+| **Thinking Lenses** | Diagnose problem structure, recommend mathematical perspectives | `../../lenses/*.md` | Which perspective should we view this problem through? |
+| **Math Knowledge** | Provide concrete mathematical tools (definitions/theorems/formulas) | `../../knowledge-base/*/*.md` | What specific mathematics does this perspective require? |
+| **Design Translation** | Translate mathematics into AI modules/losses/operators | `../../design-patterns/*/*.md` | How does this mathematics become model architecture? |
+
+Auxiliary layers:
+- `../../references/books/*.md`: Distilled notes from 7 textbooks; full context when deeper understanding is needed
+- `../../references/gpu-friendly-math.md`: GPU Eight-Dimension Acceptance Gate (single source of truth)
+- `../../agents/math-critic.md`: Math-engineering dual critic
+
+## Intent Diagnosis (5 Scenarios)
+
+| Scenario | Diagnostic Signal | Invocation Path |
+|----------|------------------|-----------------|
+| **A. Problem Analysis** | "Is this design sound?" "Are there gaps in the reasoning chain?" | Lenses → critic |
+| **B. Mechanism Design** | "Design a new attention mechanism" "Transfer X to Y" | Lenses → Knowledge → Design → critic |
+| **C. Knowledge Query** | "What is a tangent space on a manifold?" "How is the projection theorem applied?" | Knowledge |
+| **D. Verification & Review** | "Does this formula hold?" "What guarantees does this loss provide?" | Knowledge → critic |
+| **E. Pure Engineering** | Debugging, refactoring, hyperparameter tuning, code review | **Do not invoke the math system** |
+
+## Lens Library (15 Mathematical Perspectives)
+
+Each lens answers: What is this perspective? What kinds of problems is it suited to diagnose? Which knowledge domains does it route to?
+
+| Lens | File | Core Perspective |
+|------|------|-----------------|
+| Axiomatization | `../../lenses/axiomatization.md` | Examine consistency/independence/completeness of assumptions |
+| Duality | `../../lenses/duality.md` | Transform to the dual space to expose constraints and invariants |
+| Symmetry | `../../lenses/symmetry.md` | Invariants and conservation laws under transformations |
+| Spectral Decomposition | `../../lenses/spectral.md` | Eigenvalues/singular values reveal dominant structure |
+| Geometric | `../../lenses/geometric.md` | Metric/curvature/spatial structure on manifolds |
+| Projection & Decomposition | `../../lenses/projection.md` | Orthogonal decomposition, subspace separation, conflict elimination |
+| Variational | `../../lenses/variational.md` | Constrained extrema, energy minimization |
+| Local-to-Global | `../../lenses/local-to-global.md` | Patching local properties into global ones, cohomological obstructions |
+| Topological | `../../lenses/topological.md` | Invariants under continuous deformation, connectedness, holes |
+| Categorical | `../../lenses/categorical.md` | Universal properties, functors, natural transformations |
+| Perturbation | `../../lenses/perturbation.md` | Propagation of small perturbations, stability, robustness |
+| Causal | `../../lenses/causal.md` | Correlation ≠ causation, interventions, counterfactuals |
+| Game-Theoretic | `../../lenses/game.md` | Multi-agent strategic interaction, equilibria, mechanism design |
+| Probabilistic & Statistical | `../../lenses/probabilistic.md` | Quantifying uncertainty, Bayesian updating |
+| Algorithmic | `../../lenses/algorithmic.md` | Complexity, feasibility, parallelizability |
+
+## Knowledge Base (Organized by Mathematical Domain)
+
+Each knowledge card answers: Minimal definition, core formulas, applicable problems, AI design translation, engineering feasibility, risks.
+
+| Domain | Directory | Knowledge Cards |
+|--------|-----------|----------------|
+| Matrix Analysis | `../../knowledge-base/matrix-analysis/` | projection, spectral-decomposition, low-rank-approximation, positive-semidefinite, matrix-perturbation |
+| Optimization | `../../knowledge-base/optimization/` | lagrangian-duality, convex-optimization, constrained-optimization, riemannian-optimization, proximal-method |
+| Differential Geometry | `../../knowledge-base/differential-geometry/` | manifold, tangent-space, metric-tensor, geodesic, curvature, connection |
+| Lie Theory | `../../knowledge-base/lie-theory/` | group-action, lie-group, lie-algebra, representation, equivariance |
+| Topology | `../../knowledge-base/topology/` | persistent-homology, euler-characteristic, fundamental-group |
+| Probability & Information | `../../knowledge-base/probability/` | concentration-inequality, entropy, kl-divergence, information-bottleneck, fisher-information |
+| Information Geometry | `../../knowledge-base/information-geometry/` | natural-gradient, fisher-metric |
+
+## Design Pattern Library (Organized by AI Component)
+
+Each design pattern answers: Mathematical origin, AI module form, implementable architecture, GPU feasibility, paper-level exposition, risks.
+
+| Component Type | Directory | Patterns |
+|---------------|-----------|----------|
+| Attention | `../../design-patterns/attention/` | projection-attention, spectral-attention, equivariant-attention, geometry-aware-attention, information-bottleneck-attention |
+| Loss Functions | `../../design-patterns/loss/` | orthogonality-loss, contrastive-loss, variational-loss, information-bottleneck-loss, constraint-penalty |
+| Routing | `../../design-patterns/routing/` | optimal-transport-routing, graph-routing, moe-routing, spectral-clustering-routing |
+| Representation | `../../design-patterns/representation/` | shared-private-decomposition, manifold-representation, equivariant-split, subspace-alignment |
+| Compression | `../../design-patterns/compression/` | low-rank-kv-cache, spectral-token-pruning, topology-preserving-compression, leverage-score-selection |
+
+## Automatic Trigger Conditions
+
+**All of Gate 1 + Gate 2 + Gate 3 must be satisfied simultaneously for intervention:**
+
+### Gate 0 · Exclusion Gate (Highest Priority)
+The following tasks **never** trigger the system regardless of workspace contents: code review, debugging, refactoring, hyperparameter tuning, build/deployment, purely factual queries, general software engineering.
+
+### Gate 1 · Environment Signal
+The workspace contains architecture-level core code (attention/transformer/MoE, `*.cu`/kernel) or research notes. Routine files like `model.py` or `trainer.py` alone **do not** constitute an environment signal.
+
+### Gate 2 · Task Signal
+The user's task involves **designing/improving** a new architecture/operator, **analyzing** theoretical properties, **transferring** mathematical structures into AI design, or **querying math knowledge relevant to AI research** (e.g., "how is tangent space used in optimization?"). Pure encyclopedic math queries (e.g., "what is a group?" with no AI context) do not auto-trigger, but can be accessed via `/ask`.
+
+### Gate 3 · Intent Match
+The user's intent matches one of scenarios A/B/C/D. Pure engineering tasks matching scenario E → no intervention.
+
+> **`/ask` entry**: Manual invocation skips Gate 1 and Gate 2, executing only Gate 0 (exclusion) + Gate 3 (intent match), allowing direct access to any scenario including knowledge queries.
+
+## Main Workflow
+
+### Step 1: Diagnose Intent
+1. Determine which scenario (A/B/C/D/E) the user's intent belongs to
+2. Extract the core tension of the problem: what to preserve? what to suppress? what are the constraints? what is the engineering bottleneck?
+3. Output a problem-type classification
+
+### Step 2: Route Invocation
+
+```
+Scenario A (Analysis): Select 1–3 lenses → output perspective diagnosis → critic review
+Scenario B (Design): Select 1–3 lenses → query knowledge cards → generate design patterns → critic review
+Scenario C (Query): Load knowledge cards directly → output per knowledge activation protocol
+Scenario D (Verification): Load knowledge cards → critic reviews conditions and boundaries
+Scenario E (Engineering): No intervention
+```
+
+### Step 3: Output Format
+
+**Scenario A/B Output**:
+1. **[Diagnosis]** Problem type + core tension
+2. **[Lens]** Recommend 1–3 mathematical perspectives (annotate why each is/is not suitable)
+3. **[Knowledge]** (Scenario B only) Required concrete mathematical tools (reference knowledge cards)
+4. **[Design]** (Scenario B only) Candidate AI module drafts (reference design patterns)
+5. **[GPU]** Run candidates through the Eight-Dimension Gate (friendly/retrofittable/unfriendly)
+6. **[Conclusion]** Retain candidates that pass both acceptance gates + next-step recommendations
+
+**Scenario C Output** (Knowledge Activation Protocol):
+1. Minimal definition
+2. Core formulas
+3. Applicable problems
+4. AI design translation
+5. Engineering feasibility
+6. Risks and failure conditions
+7. Further references (distilled book notes / original book paths)
+
+**Scenario D Output**:
+1. Conditions under which it holds
+2. Conditions under which it fails
+3. What it can guarantee at most
+4. What it cannot guarantee
+5. Engineering feasibility
 
-## Core Principle
-
-**No lengthy math tutorials.** Once triggered, immediately enter the three-step pipeline: "Diagnose → Map → GPU Screen," activating modern mathematics into algorithm/hardware design, and passing every output through the **dual acceptance gate**:
-
-1. **Mathematically correct (beautiful in math)** — self-consistent, differentiable (or relaxable to differentiable), with correctness guarantees.
-2. **GPU-feasible (friendly to GPU)** — see `../../references/gpu-friendly-math.md` eight dimensions.
-
-> This is the **sole automatic entry point** of the skill pack. It loads the methodology layer (`../../references/agentic-workflow.md`, `../../references/gpu-friendly-math.md`), the book activation layer (`../../references/books/*.md`), and the 16 thinking weapons (sibling directories `../*/SKILL.md`) on demand, keeping only the minimal trigger and diagnostic logic resident at all times — progressive disclosure to save tokens.
-
-## When to Auto-Engage
-
-**Both the "environment signal" AND the "task signal" must be satisfied simultaneously (neither alone is sufficient):**
-
-### Gate 0 · Exclusion Gate (evaluated first; if hit, do not engage)
-
-The following tasks must **never** trigger this activator, regardless of what code is in the workspace:
-- Code review / debugging / parameter-passing chain verification / interface consistency checks
-- Refactoring, renaming, removing redundant code, dead code cleanup
-- Build / packaging / CI / deployment / environment configuration
-- Pure factual queries ("what does this function do," "who receives this parameter")
-- General software engineering (file I/O, networking, data loading, logging)
-- Training script hyperparameter tuning, hyperparameter search, experiment comparison
-- Adding / modifying loss implementation details (as opposed to designing the mathematical structure of a new loss)
-
-**Rule of thumb: if the task can be accomplished by "reading code → tracing call chains → reporting results," no mathematical weapon is needed.**
-
-### Gate 1 · Environment Signal (necessary condition, not sufficient)
-
-The workspace contains at least one of the following:
-- Core model architecture code (not training scripts / data pipelines): attention/transformer/MoE implementations, `*.cu`/`*.cuh`/kernels, Triton/CUDA operators.
-- Algorithm research notes / paper review documents.
-- Design drafts or mathematical derivations for new architectures / new operators.
-
-> The mere presence of `model.py`, `trainer.py`, `config.json`, or similar routine ML engineering files **does not constitute an environment signal**.
-
-### Gate 2 · Task Signal (necessary condition, not sufficient)
-
-The user's current task explicitly involves at least one of the following:
-- **Designing or improving** a new model architecture / operator / attention mechanism (not fixing an existing implementation).
-- **Selecting or justifying** the applicability of a mathematical structure (e.g., "should we use manifold constraints," "does this structure have equivariance").
-- **Analyzing** theoretical properties of an algorithm (complexity lower bounds, convergence, expressivity, information bottleneck).
-- **Transferring** a mathematical structure from some field into algorithm/GPU design.
-
-> If the task signal is merely "code doesn't run," "parameter wasn't passed," "loss didn't take effect," or similar engineering issues, the activator does **not trigger** even if the environment signal is hit.
-
-**When NOT to engage:**
-- Gate 0 is hit (exclusion gate).
-- Either Gate 1 or Gate 2 is not satisfied.
-- The problem is not in a domain where mathematics can help.
-
-## The Activation Loop
-
-> See `../../references/agentic-workflow.md` for detailed working methodology (Human-in-the-Agent-Loop).
-
-1. **Diagnose**: What is the algorithmic structure or bottleneck? (complexity? memory/KV? numerics? parallelism? expressivity?)
-2. **Map**: Use the "Modern Math Toolbox" (below) to scan for transferable structures, **enumerating multiple candidates** (leverage the large context window — don't just give one).
-3. **Route**: Select 1–3 thinking weapons for deeper analysis (decision tree below).
-4. **GPU Screen**: Pass each candidate through the eight dimensions of `../../references/gpu-friendly-math.md`, rating "friendly / retrofittable / unfriendly" + adaptation recommendations.
-5. **Dual Acceptance Gate**: Retain only candidates that are **mathematically correct AND (eight-dimension friendly or retrofittable)**.
-6. **Track**: For complex explorations, use a markdown testplan table (template in agentic-workflow.md) to iterate toward convergence.
-
-The eight-dimension terminology must remain consistent: **Tensorization / GEMM-Mappability / Complexity / Memory & KV-Cache / Low-Precision Stability / Parallelism & Communication / Sparsity Structure / Operator Fusion**. Do not substitute vague judgments covering only a subset of dimensions for the full eight-dimension gate.
-
-## Weapon Routing
-
-Match by the core characteristic of the problem (select up to 3, label primary/secondary):
-
-1. **Multi-agent interaction** (my optimum depends on others) → `/game-theory` (primary); resource allocation + `/optimization`; information asymmetry + `/information-theory`
-2. **Uncertainty / randomness** → `/probability-statistics` (primary); need causal rather than correlational + `/causal-inference`
-3. **Optimization under constraints** → `/optimization` (primary); need to model first + `/modeling` (prerequisite)
-4. **Current form is intractable, need change of perspective / simplification** → `/transformation` (primary)
-5. **Need to extract essential structure** → `/abstraction` (primary); verify assumptions + `/axiomatization`; simplify + `/symmetry-invariance`
-6. **Need rigorous reasoning and verification** → `/logic-deduction` (primary); verify premises + `/axiomatization`
-7. **Finding patterns from data / experience** → `/induction-analogy` (primary); cross-domain transfer + `/abstraction`
-8. **Building predictive / explanatory models** → `/modeling` (primary); optimization + `/optimization`; uncertainty + `/probability-statistics`
-9. **Invariance / conservation / equivariance under change** → `/symmetry-invariance` (primary); connected structure + `/topological-thinking`
-10. **Reducing to executable steps / evaluating feasibility and complexity** → `/algorithmic-thinking` (primary)
-11. **Compression / encoding / information bottleneck / KV-Cache compression / quantization** → `/information-theory` (primary); representation transforms + `/transformation`; routing information gain + `/game-theory`
-12. **Counting / enumeration / structure of finite objects** → `/discrete-combinatorial` (primary)
-
-> **Modern math priority hint**: When the problem is "designing/improving an operator or structure," **always open the modern math toolbox first** while routing weapons — many breakthroughs come from transferring structures from algebraic geometry / differential geometry / Lie theory, rather than circling within classical tools alone.
-
-## Modern-Math Toolbox (Layer 3 · Loaded on Demand)
+**A conclusion must always be provided — never output analysis alone without convergence.**
 
-Load the corresponding book activation file (`../../references/books/`) by problem type:
+## GPU Eight-Dimension Acceptance Gate
 
-| Trigger Signal | Load | Typical Activation |
-|---------|------|---------|
-| Operator = matrix multiply / spectrum / low-rank / numerical stability | `matrix-analysis.md` | GEMM formulation, low-rank compression, spectral normalization, preconditioning |
-| Training / convergence / optimizer / constraints | `optimization-ml.md` | Feasibility of adaptive / second-order optimization, dual solving |
-| Symmetry / equivariance / semiring / permutation invariance | `abstract-algebra.md` | Group-equivariant layers, tropical semiring routing, finite-field encoding |
-| Manifold constraints / latent-space geometry / differentiable structure | `smooth-manifolds.md` | Manifold optimization, Stiefel/orthogonal constraints, geodesic interpolation |
-| Metric / curvature / natural gradient / gauge / fiber bundle | `differential-geometry.md` | Natural gradient / K-FAC, information geometry, gauge equivariance |
-| Pose / SO(3) / SE(3) / state estimation / equivariance | `micro-lie-theory.md` | Lie group optimization, SE(3) equivariance, manifold loss |
-| Attention / sparsity / global consistency / KV compression | `algebraic-geometry-rising-sea.md` | Sheaf attention, Čech cohomology regularization, Plücker KV, tropical gating |
+Formal terminology (single authoritative source: `../../references/gpu-friendly-math.md`):
+**Tensorization / GEMM-mappability / Complexity / Memory & KV-Cache / Low-Precision Stability / Parallelism & Communication / Sparse Structure / Operator Fusion**
 
-## Deep-Dive Protocol
+## Depth-of-Consultation Protocol
 
-- **Light**: Read `../../references/books/<book>.md` (distilled notes, shipped with the release, self-contained).
-- **Deep (full fidelity to original text required)**: If a local `math_book/<corresponding PDF>` exists, **let the agent search automatically** — `pdftotext "math_book/<file>.pdf" -` → grep keywords → Read the matching page. **No reliance on pre-embedded anchors.**
-- No PDF available (e.g., npm-installed on a different machine): Stay at the distilled-notes layer, which remains self-contained and usable.
+- **Light**: Read knowledge cards (`../../knowledge-base/*/*.md`); self-contained and immediately usable
+- **Medium**: Read distilled book notes (`../../references/books/*.md`) for more complete context
+- **Deep**: When `math_book/<PDF>` is available locally, the agent automatically runs `pdftotext` + grep to locate the original page
 
-## Worked Example: Tropical Sheaf Attention
+## Workflow Example
 
-A research candidate template (see `../../references/gpu-friendly-math.md` for details): tropical gating (semiring piecewise-linear replacing Top-K) + cellular sheaf diffusion (low-rank restriction maps per edge = small GEMMs) + Čech cohomology regularization (H¹ as a structural consistency signal) + Plücker KV compression. Treat this as an exploration template for "math beautiful x GPU friendly": verify complexity, memory, low-precision stability, and kernel fusibility dimension by dimension before claiming passage through the eight-dimension gate.
+**User**: "Design a new KV Cache compression method that preserves long-range dependencies — I don't want to just do top-k."
 
-## Operating Procedure
+```
+Step 1 — Diagnosis: Scenario B (Mechanism Design)
+  Problem type: Sequence memory compression + information preservation + long-range structure
+  Core tension: Compressing token count vs. preserving long-range dependencies
 
-Once triggered, the output must contain:
-1. **[Diagnosis]**: One sentence identifying the algorithmic structure/bottleneck (interaction / uncertainty / constraints / structure / dynamics / complexity / memory / numerics / parallelism).
-2. **[Mapping]**: Enumerate transferable modern math structure candidates (>=2, annotated with source book).
-3. **[Weapon Routing]**: 1–3 thinking weapons, labeled primary/secondary + trigger commands.
-4. **[GPU Screen]**: Each candidate evaluated against the eight dimensions, rated "friendly / retrofittable / unfriendly" + adaptation recommendations.
-5. **[Conclusion]**: Retain only candidates passing the dual acceptance gate; provide a testplan table when necessary.
+Step 2 — Lens Selection:
+  1. Spectral Decomposition (preserve dominant subspace)
+  2. Information Theory (retain states with maximum mutual information)
+  3. Topological (preserve critical connectivity points of sequential structure)
 
-**A conclusion must always be provided — never output analysis alone without convergence.**
+Step 3 — Knowledge Query:
+  → low-rank-approximation (Matrix Analysis)
+  → leverage-score-selection (Design Pattern: compression)
+  → information-bottleneck (Probability & Information)
 
-## Relations
+Step 4 — Design Translation:
+  Candidate A: Spectral KV Compression (low-rank + leverage score)
+  Candidate B: Information-Preserving Cache (query sensitivity)
+  Candidate C: Topology-Preserving Cache (graph bridge-node retention)
 
-- This entry point routes all 16 thinking weapons and loads the methodology layer and book activation layer on demand.
-- The manual entry `/ask` is equivalent to invoking this activator (weapon selector mode).
-- Review of outputs can be delegated to `agents/math-critic.md` (including the GPU feasibility dimension) for a second pass.
+Step 5 — Critic Review:
+  A is most GPU-friendly; B requires estimating future queries with inherent uncertainty; C has prohibitive graph construction cost
+  Recommendation: Prioritize A; use B as a lightweight gate
+```