/x2strategy

name: x2strategy
description: >
  ALAGENT X2Strategy: any research input (PDF paper, Markdown draft,
  DOCX report, text notes, or keyword search) → structured strategy
  specification → executable Backtrader code → backtest → diagnosis report.
  Two core capabilities: (1) paper2spec extracts multi-strategy specs from
  any document via 5-layer LLM extraction, and (2) spec2code generates
  validated Backtrader code, runs backtests, and compares against paper
  metrics. Use this skill whenever the user wants to analyze a quant paper,
  extract trading strategies, generate strategy code, run a backtest, search
  for papers, or go end-to-end from any input to executable results. Also
  triggers on: "look at this paper", "what strategies does this use",
  "implement this strategy", "search for momentum papers", "turn this into
  code", or any request about quantitative finance research → implementation.
  Even if the user doesn't mention "strategy" explicitly — if they provide a
  finance paper or research document, use this skill.
argument-hint: "[paper.pdf | strategy.md | report.docx | search query]"
metadata:
  version: 0.6.1
  author: ALAGENT AI (alagent-ai)
  tags: [quantitative-finance, paper-parsing, strategy-extraction, code-generation, backtesting]

X2Strategy

Any finance-related input → Strategy spec → Executable code → Backtest → Diagnosis.

Capabilities

| Capability | What it does | Deep dive | |-----------|-------------|-----------| | **paper2spec** | Any document (PDF/MD/DOCX/TXT) → structured strategy specification | [references/paper2spec.md](references/paper2spec.md) | | **spec2code** | Strategy spec → Backtrader code → validate → backtest → diagnosis | [references/spec2code.md](references/spec2code.md) |

Input format auto-detected from extension:

| Format | Extension | Notes | |--------|-----------|-------| | PDF (papers) | `.pdf` | PyMuPDF → Mode A (direct) or Mode B (FAISS) | | Markdown (drafts) | `.md`, `.markdown` | Direct text read | | DOCX (reports) | `.docx` | python-docx (requires `uv sync --extra docx`) | | Plain text | `.txt` | Direct read |

---

Interaction Principles

**You are the executor. The user is the requester.**

• Run tools silently, present results and insights in natural language.
• Never show CLI commands (`uv run python scripts/...`) unless user asks.
• Offer next actions conversationally: "Would you like me to implement the second strategy as well?"

When reporting results, focus on **what you found**, not how:

❌ Bad:  "I ran `uv run python scripts/analyze.py paper.pdf` and got 3 strategies."
✅ Good: "This paper contains 3 independent strategies: [1] minimum distance method, [2] ADF stationarity, and [3] Johansen cointegration. Which one should I implement?"

**Use interactive tools aggressively.** When your platform provides interactive question tools — `vscode_askQuestions` (VS Code Copilot), `AskUserQuestion` (Claude Code), or equivalent — use them for ALL user-facing choices. Interactive tools present clickable options, which is faster and less error-prone than asking the user to type.

Apply interactive tools to:

• First-Run Setup choices (workspace path, API provider, key input)
• Input confirmation (proceed / add clarification / adjust settings)
• Review checkpoints and implementation approval
• `needs_human_review` resolution after extraction or repair
• Search result selection (pick papers from a numbered list)
• Any scenario where the user picks from options

If no interactive tool is available, fall back to numbered text menus.

Progress Marker Protocol

Run tools silently, but make long pipelines **traceable**. While working through the eight-step workflow, prefix status lines with one of three structured markers so the user (and any outer parser) can follow phase progress without reading raw command output. The markers carry the discipline; the surrounding prose stays natural-language.

| Marker | When to emit | Format | |--------|-------------|--------| | `[PROGRESS]` | Entering or finishing a workflow step | `[PROGRESS] <step> — <one-line status>` | | `[ARTIFACT]` | A concrete file was written | `[ARTIFACT] <workspace-relative-path> — <what it is>` | | `[ERROR]` | A step failed or a check did not pass | `[ERROR] <step> — <what failed> — <next action>` |

Rules:

• One marker per line, at the start of the line, then plain language.
• Every `[ARTIFACT]` must name a concrete workspace-relative path that was

actually written (this satisfies the Output Paths contract below).

• `[ERROR]` must always be followed by what you will do next (retry once,

stop and report, ask the user) — never a bare failure.

• Markers supplement natural-language reporting; they do not replace it. Still

explain *what you found*, not *how you ran it*. Never show the CLI command.

Example:

[PROGRESS] paper2spec/extract — extracting strategy specs from content.json
[ARTIFACT] library/upsa/spec.json — 1 strategy, 4 indicators, 3 logic steps
[PROGRESS] HITL review — 1 open needs_human_review item, asking for resolution

Iteration & Retry Discipline

Generation and repair must be bounded. Translate the backend's hard turn gate (`--max-turns`) into agent discipline:

• **Generate once, then at most one smoke-test repair round.** Write the code,

validate, run. If it fails, apply one targeted fix round (see the triage flow in [references/spec2code.md](references/spec2code.md)) and re-run.

• **If it still fails after that one repair round, stop and report.** Emit an

`[ERROR]` line, summarize what failed and the most likely root cause, and ask the user how to proceed. Do not keep patching incrementally.

• **A single runtime-error category gets at most 3 fix attempts.** If the same

error class persists, the strategy logic likely needs a fundamentally different approach — say so rather than tweaking further.

• Never silently loop. Each retry must be visible via a `[PROGRESS]` or

`[ERROR]` marker so the user can