executor-strategy-overview

description	Create and maintain executor strategy overview presentations. Use when scaffolding a new executor, updating strategy documentation, or when the QA check requires a strategy-overview.marp.md file. Generates Marp slide decks with codePaths tracking for CI enforcement.
metadata	{"github-path":"skills/executor-strategy-overview","github-ref":"refs/tags/v1.1.0","github-repo":"https://github.com/recallnet/recall-skills","github-tree-sha":"2349f9d1ec0dec34d851612ef645e9a9e68fac4c"}
name	executor-strategy-overview
triggers	["create strategy overview","executor presentation","strategy overview docs","marp slides","missing-marp-source","missing strategy overview"]

Executor Strategy Overview

Create and maintain Marp-based strategy overview presentations for executors. These slide decks provide a visual walkthrough of arbitrage strategies and are CI-required — they must stay in sync with the source code they document.

When to Use

• Scaffolding a new executor (create alongside README and AGENTS.md)
• Code changes require updating the strategy explanation
• QA check failed with missing-marp-source or missing-pdf
• Porting an executor from replay-lab to another repo

When NOT to Use

• General presentations (use show-and-tell instead)
• Non-executor documentation

Output Location

docs/executors/{executor-name}/
├── strategy-overview.marp.md    # Source slides (required)
└── strategy-overview.pdf        # Generated PDF (required)

Also requires an entry in docs/executors/README.md linking to the .marp.md file.

The 10-Slide Structure

Every executor strategy overview must cover:

1. Title — Strategy name, venue pair, one-line description
2. What is an Executor? — Concept: strategy-scoped service owning the full loop
3. Opportunity Discovery — How trade inputs are sourced and scored
4. Ranking & Selection — Scoring criteria, filters, validation rules
5. Order Placement — Entry strategy (maker, taker, hybrid)
6. Resting & Cancel Conditions — What triggers re-evaluation or cancellation
7. Fill Detection — How fills are detected (WS, REST, polling)
8. Hedge / Completion — How the second leg executes
9. Position & Resolution — Lifecycle from open to settlement
10. Failure Modes & Recovery — Error handling, orphan recovery, retry logic

Frontmatter Template

---
id: executors.{name}.strategy-overview
title: "{VenueA}-{VenueB} {Strategy} Strategy Overview"
docType: explanation
summary: "Visual walkthrough of the {strategy}: ranking, placement, fills, hedging, and failure recovery."
owner: team-execution
lastReviewed: "{YYYY-MM-DD}"
codePaths:
  - executors/{name}/src/execution/runner.ts
  - executors/{name}/src/strategy/ranking/*.ts
  - packages/arb-execution/src/execution-cycle.ts
  # Add all source files this deck explains
marp: true
theme: default
paginate: true
---

codePaths Field

The codePaths array pins this documentation to source files. When pinned files change and the deck is not updated, the pre-commit hook warns.

Rules:

• List every significant source file the deck explains
• Use relative paths from repo root
• Include: ranking logic, execution cycle, fill tracking, state machine
• Update lastReviewed date when content changes

Procedure

Step 1: Create Directory Structure

mkdir -p docs/executors/{executor-name}

Step 2: Write the Marp Source

Create docs/executors/{executor-name}/strategy-overview.marp.md:

1. Copy the frontmatter template above
2. Fill in the 10 slides following the structure
3. Use Marp syntax (--- for slide breaks, # for titles)
4. Include diagrams (ASCII or Mermaid if supported)
5. Reference actual source files in code blocks

Key content per slide:

Slide	Must Include
1	Executor name, venues, strategy type, file path
2	Definition of executor, responsibilities table
3	Opportunity source, scoring method, directionality
4	Kernel validation, selection criteria, result destination
5	Price derivation, order parameters, state transitions
6	Cancel triggers table, timeout handling
7	Fill detection diagram (WS + REST fallback)
8	Hedge sequence, retry logic, forced-taker guarantee
9	Position lifecycle diagram, PnL tracking, settlement
10	Failure modes table with recovery actions

Step 3: Generate PDF

Install Marp CLI if not present:

npm install -g @marp-team/marp-cli

Generate the PDF:

marp docs/executors/{executor-name}/strategy-overview.marp.md --pdf -o docs/executors/{executor-name}/strategy-overview.pdf

Or with npx:

npx @marp-team/marp-cli docs/executors/{executor-name}/strategy-overview.marp.md --pdf -o docs/executors/{executor-name}/strategy-overview.pdf

Step 4: Link from Index

Add to docs/executors/README.md:

- [{VenueA}-{VenueB} {Strategy} Overview (slides)](./{executor-name}/strategy-overview.marp.md)

Step 5: Commit Both Files

git add docs/executors/{executor-name}/strategy-overview.marp.md
git add docs/executors/{executor-name}/strategy-overview.pdf
git add docs/executors/README.md

QA Enforcement

The check-executor-strategy-overview-docs.ts script enforces:

Check	Violation	Fix
missing-marp-source	No .marp.md file	Create the slide deck
missing-pdf	No .pdf file	Generate with Marp CLI
missing-docs-index-link	Not linked in README	Add link to index

Auto-fix: The pre-commit hook auto-regenerates PDFs when .marp.md files change:

for marp_file in $STAGED_MARP; do
  pdf_file="${marp_file%.marp.md}.pdf"
  ./node_modules/.bin/marp "$marp_file" --pdf -o "$pdf_file"
  git add "$pdf_file"
done

Example Slide Content

Slide 1: Title

# {VenueA}-{VenueB} {Strategy} Strategy

**{One-line description}**

Executor: `executors/{name}`
Venues: {VenueA}, {VenueB}, {VenueC} (any pair)

{strategy loop diagram}

Slide 7: Fill Detection (Diagram)

# Fill Detection

**Dual-source for redundancy:**

Venue WebSocket (user feed) → Primary: ~100ms latency ↓ REST Polling (order status) → Fallback: every 30s ↓ Fill Recorded (database) → Leg state: placed → filled

References

• references/template.marp.md — Complete template with all 10 slides
• references/example-2leg.md — Real example from kalshi-polymarket-2leg
• Marp documentation: https://marpit.marp.app/

Rules

• Always use the 10-slide structure — don't skip slides
• Include codePaths frontmatter — required for freshness tracking
• Generate PDF with Marp CLI — don't commit hand-created PDFs
• Link from docs/executors/README.md — required for discovery
• Update lastReviewed date when content changes
• Use actual source file paths in code blocks — not pseudocode
• Keep diagrams as ASCII or use Marp's Mermaid support
• Never include sensitive data (API keys, credentials) in slides

Integration

Triggered by:

• QA check failures (missing-marp-source, missing-pdf)
• New executor scaffolding
• Code changes affecting strategy logic

Related skills:

• show-and-tell — For demo presentations, not strategy docs
• recall-commit — Use conventional commits when updating slides