# Trader Explain

> Atribución de características de nivel regulatorio para cualquier señal LSTM/Transformer: PageRank de entrada única rankea las top-K características que impulsaron la predicción.

Fuente: https://skillsagentes.com/skills/ruvnet/ruflo/trader-explain
Markdown: https://skillsagentes.com/skills/ruvnet/ruflo/trader-explain.md

Repositorio: https://github.com/ruvnet/ruflo
Autor: ruvnet
Licencia: MIT
Actualizado: el mes pasado
Coste de contexto: 47 tok instalada, 2k tok al activarse, 2k tok con todos los archivos del bundle
Bundle: 1 archivo, 8 KB
Permisos que pide: bash read mcp__plugin_ruflo-core_ruflo__memory_retrieve mcp__plugin_ruflo-core_ruflo__memory_store mcp__ruflo-sublinear__page-rank-entry

## Instalación

Un skill son archivos markdown: los mismos archivos valen para cualquier agente y lo único que cambia es el directorio de destino, es decir la bandera `--agent`. Añade `-g` para instalarlo en todos los proyectos de la máquina.

```bash
# Claude Code
npx -y skills add ruvnet/ruflo --skill trader-explain --agent claude-code
# Cursor
npx -y skills add ruvnet/ruflo --skill trader-explain --agent cursor
# Codex
npx -y skills add ruvnet/ruflo --skill trader-explain --agent codex
# Gemini CLI
npx -y skills add ruvnet/ruflo --skill trader-explain --agent gemini
# Windsurf
npx -y skills add ruvnet/ruflo --skill trader-explain --agent windsurf
# Cline
npx -y skills add ruvnet/ruflo --skill trader-explain --agent cline
```

## Qué hace

- Construye un grafo de contribución de características desde una señal y ejecuta PageRank de entrada única para rankear las top-K.
- Si --explain no está disponible en neural-trader, usa un heurístico de z-score y etiqueta el artefacto como fallback.
- Firma el artefacto de atribución con Ed25519 y lo guarda en el namespace trading-analysis.
- Devuelve una tabla markdown con el ranking, iteraciones de PageRank y la firma.

## Cuándo usarla

- Necesitas explicar qué características impulsaron una predicción de un modelo LSTM/Transformer, con fines regulatorios (EU AI Act, SEC Reg-AI).

## Qué la activa

- "Explica qué características impulsaron la señal SIG-123"
- "Genera la atribución regulatoria de esta predicción"

## Antes de instalar

- Necesita que la señal exista en el namespace trading-signals; para firmar requiere una clave witness Ed25519.
- Variables de entorno: SIGNAL_ID
- reads environment config

## Archivos

- SKILL.md — 8 KB

## SKILL.md

Reproducido tal cual desde ruvnet/ruflo bajo MIT. Esta sección es el documento original y está en inglés.

Explain a trading signal by building a feature-contribution graph and running single-entry forward-push PageRank from the signal output node. Top-K ranked features are returned as a markdown table AND persisted to `trading-analysis` as a `SignedAttributionArtifact` (ADR-126 Phase 6).

**Why this skill matters:**
- EU AI Act + SEC Reg-AI guidance require interpretable model output for any algorithmic trading system that touches retail capital. This is the regulator-grade attribution path the rest of the substrate has been waiting for.
- The same call site picks up the full native-WASM PageRank from `mcp__ruflo-sublinear__page-rank-entry` once that tool is registered in the runtime — until then, the local power-iteration kernel ships in `signed-attribution.mjs` and produces the same ordering (seeded mulberry32).

Steps:

1. **Retrieve the signal** from the canonical `trading-signals` namespace (ADR-126 Phase 1 + Phase 2 lifecycle):
   ```text
   mcp__plugin_ruflo-core_ruflo__memory_retrieve({
     key: "SIGNAL_ID",
     namespace: "trading-signals"
   })
   ```
   The signal entry includes `modelId`, `prediction`, and the feature vector at the time of inference.

2. **Extract per-feature contribution scores** from the model:
   ```bash
   npx neural-trader --predict --signal "$SIGNAL_ID" --explain --json
   ```
   The expected output shape:
   ```ts
   {
     features: Array<{ name: string; contribution: number }>;
     // for Transformers, also includes per-head attention co-occurrence:
     attention?: Array<{ head: string; cooccur: Array<[number, number, number]> }>;
   }
   ```

   **Fallback path** — if `--explain` is not shipped on the installed `neural-trader` build (older versions; the flag was scoped for a follow-up upstream PR), the skill degrades to a deterministic feature-importance heuristic over the signal's input vector: `contribution_i = |input_i - μ_i| / σ_i` (z-score magnitude). This is a known proxy — not as faithful as attention/SHAP — and the resulting artifact is tagged `attribution_method: "input-zscore-fallback"` so downstream consumers can filter it out for regulator filings. Document the fallback path in the resulting markdown summary so the agent surfaces it to the user.

3. **Build the feature-contribution graph**:
   - **Nodes**: one node per feature + one source node `__signal_output__` for the prediction.
   - **Edges**: outgoing edges from `__signal_output__` to each feature node, weighted by `contribution_i`. When attention co-occurrence data is available, also add edges between feature nodes weighted by `cooccur` — this is what makes the PageRank single-entry rather than degenerating to plain top-K.
   - **Source**: `__signal_output__` (index 0 by convention so the smoke can assert reproducibility).

4. **Run single-entry PageRank** — preferred path when `mcp__ruflo-sublinear__page-rank-entry` is registered:
   ```text
   mcp__ruflo-sublinear__page-rank-entry({
     nodes: GRAPH_NODES,
     edges: GRAPH_EDGES,
     sourceIndex: 0,
     damping: 0.85,
     maxIterations: 100,
     tolerance: 1e-8,
     seed: 42
   })
   ```
   The local fallback (`localSingleEntryPageRank` in `plugins/ruflo-neural-trader/src/signed-attribution.mjs`) runs ~30 LOC of seeded power-iteration when the MCP tool is not available — same math, same result up to floating-point tolerance, same ordering for the same seed (the Phase 6 smoke asserts this).

5. **Build the top-K `AttributionFeature[]`** via `topKFeatures(graph, scores, k=10, excludeIndex=0)` — excludes the source node from the ranked output. Ties broken by node index (lower index wins) so the ranking is deterministic.

6. **Sign the artifact** (reuses the Phase 4 signing primitives — same Ed25519 + canonicalization):
   - Build the `SignedAttributionArtifact` body:
     ```ts
     {
       signalId: SIGNAL_ID,
       modelId: SIGNAL.modelId,
       features: TOP_K_FEATURES,             // from step 5
       graphMetadata: {
         nodeCount: GRAPH.nodes.length,
         edgeCount: COUNT_EDGES,
         pageRankIterations: PR_RESULT.iterations,
         seed: SEED                          // load-bearing for reproducibility
       },
       generatedAt: NEW_DATE_ISO
     }
     ```
   - Resolve the witness signing key — same lookup order as Phase 4:
     1. `RUFLO_WITNESS_KEY_PATH` env var — JSON file with `{ "privateKey": "<hex>" }`.
     2. `verification/witness-key.json` (the ADR-103 default path).
   - If a key resolves: `signAttributionArtifact(body, privateKeyHex)` from `plugins/ruflo-neural-trader/src/signed-attribution.mjs`.
   - If NEITHER path resolves: log `"[WARN] ruflo-neural-trader: no witness signing key found — storing attribution artifact in UNSIGNED degraded mode. Regulator filings will reject UNSIGNED artifacts."` and store the body unsigned. NEVER silently fall back.

7. **Store the (possibly signed) artifact** to the canonical `trading-analysis` namespace (ADR-126 Phase 1):
   ```text
   mcp__plugin_ruflo-core_ruflo__memory_store({
     key: "attribution-SIGNAL_ID-TIMESTAMP",
     namespace: "trading-analysis",
     value: JSON.stringify(signedArtifact)
   })
   ```
   The `trading-analysis` namespace is the canonical home for model-analysis output (regime classifications, technical-indicator summaries, model-training results — and now attribution rankings). Long-lived — no TTL — because the audit trail is the deliverable.

8. **Return the markdown summary** to the agent. Suggested format:
   ```
   ## Feature attribution for signal `SIGNAL_ID` (model: MODEL_ID)

   | Rank | Feature | Score |
   |------|---------|-------|
   | 1    | NAME    | 0.42  |
   | 2    | NAME    | 0.18  |
   | …    | …       | …     |

   - PageRank iterations: N
   - Graph: nodeCount nodes, edgeCount edges
   - Seed: 42 (reproducible — same seed → same ordering)
   - Path: mcp | local
   - Signature: ed25519:abcd… (or UNSIGNED — degraded warning above)
   ```

### Verification

Downstream consumers verify the artifact before any regulator-facing report or paper→live promotion:

```ts
import { verifyAttributionArtifact } from 'plugins/ruflo-neural-trader/src/signed-attribution.mjs';

const ok = await verifyAttributionArtifact(artifact, trustedPublicKey);
if (!ok) {
  // [ERROR] attribution verification failed — refuse to publish.
  // Pin to trustedPublicKey from project config; do NOT trust the
  // artifact.witnessPublicKey field (CWE-347 / #1922 — attacker-controllable).
  return;
}
```

**Acceptance criteria (ADR-126 Phase 6):**
- `trader-explain <signalId>` returns a ranked feature list whose top-3 features overlap the model's attention argmax (when `--explain` available; documented tolerance).
- Reproducibility: two runs with the same `signalId` + same `--seed` produce byte-identical rank ordering (asserted by `scripts/smoke-neural-trader-feature-attribution.mjs`).
- Signed artifact verifies under the trusted pubkey; tampering any feature score or `graphMetadata.seed` invalidates the signature.
- Fallback paths engage cleanly: when MCP unavailable, local kernel runs; when `--explain` flag missing, z-score heuristic runs and the artifact is tagged.

**Refs:**
- ADR-126 Phase 6 (this skill's authoring ADR)
- ADR-126 Phase 4 (the signing scheme this reuses)
- ADR-123 (single-entry PageRank substrate; the same family that Phase 3 leverages for portfolio CG)
- `plugins/ruflo-neural-trader/src/signed-attribution.ts` (the typed contract)
- `plugins/ruflo-neural-trader/src/signed-attribution.mjs` (the runtime mirror)
- `scripts/smoke-neural-trader-feature-attribution.mjs` (the regression smoke)

## Dónde encaja

- Categoría: [Finanzas](https://skillsagentes.com/categorias/finanzas.md) — Contabilidad, modelado financiero y flujos de reportes.
- Creador: [ruvnet](https://skillsagentes.com/creators/ruvnet.md) — 275 skills en el directorio
- [Todas las skills](https://skillsagentes.com/skills.md)
- [Ranking de instalaciones](https://skillsagentes.com/ranking.md)

## Otras skills del mismo repositorio

- [Harness Gepa](https://skillsagentes.com/skills/ruvnet/ruflo/harness-gepa.md): Inspecciona y audita genomas GEPA: carga y valida un genoma, renderiza el system prompt que compila, o clasifica los modos de fallo de una transcripción de ejecución.
- [Deepseek Reason](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-reason.md): Completion en modo razonamiento contra deepseek-reasoner (R1) de DeepSeek. Devuelve el chain-of-thought por separado de la respuesta final. Lee DEEPSEEK_API_KEY y degrada si falta o la API no responde.
- [Deepseek Chat](https://skillsagentes.com/skills/ruvnet/ruflo/deepseek-chat.md): Completion de un solo turno contra el modelo deepseek-chat de DeepSeek vía /v1/chat/completions. Lee DEEPSEEK_API_KEY y degrada con status:degraded si falta o la API no responde. Para tareas sin razonamiento.
- [Adr Index](https://skillsagentes.com/skills/ruvnet/ruflo/adr-index.md): Construye o reconstruye el índice de ADRs y su grafo de dependencias ejecutando scripts/import.mjs, en vez de cientos de llamadas MCP.
- [Agntcy Status](https://skillsagentes.com/skills/ruvnet/ruflo/agntcy-status.md): Muestra el estado de la integración AGNTCY/SLIM/CASA: si los paquetes están instalados, qué transporte está activo y si el enforcement de CASA está habilitado.

---

Skills Agentes · [Índice de páginas en markdown](https://skillsagentes.com/sitemap.md) · [Inicio](https://skillsagentes.com/index.md)