Plotext Financial Chart

Plotext Financial Chart Skill

Create ASCII financial line charts for GitHub Flavored Markdown using plotext with dot marker (•). Pure text output — renders correctly on GitHub, terminals, and all monospace environments.

Analogy: graph-easy is for flowcharts. plotext with dot marker is for financial line charts.

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• Adding price path / line chart diagrams to markdown documentation
• Visualizing trading concepts (barriers, thresholds, entry/exit levels)
• Any GFM markdown file needing financial data visualization
• User mentions "financial chart", "line chart", "price chart", "plotext", or "trading chart"

NOT for: Flowcharts or architecture diagrams — use graph-easy for those.

Preflight Check

All-in-One Preflight Script

/usr/bin/env bash << 'PREFLIGHT_EOF'
python3 --version &>/dev/null || { echo "ERROR: Python 3 not found"; exit 1; }
if command -v uv &>/dev/null; then PM="uv pip"
elif command -v pip3 &>/dev/null; then PM="pip3"
else echo "ERROR: Neither uv nor pip3 found"; exit 1; fi
python3 -c "import plotext" 2>/dev/null || { echo "Installing plotext via $PM..."; $PM install plotext; }
python3 -c "
import plotext as plt, re
plt.clear_figure()
plt.plot([1,2,3], [1,2,3], marker='dot')
plt.plotsize(20, 5)
plt.theme('clear')
output = re.sub(r'\x1b\[[0-9;]*m', '', plt.build())
assert '•' in output
" && echo "✓ plotext ready (dot marker verified)"
PREFLIGHT_EOF

Quick Start

import re
import plotext as plt

x = list(range(20))
y = [97, 98, 100, 101, 100, 98, 100, 101, 102, 101,
     100, 98, 100, 101, 102, 103, 102, 101, 100, 100]

plt.clear_figure()
plt.plot(x, y, marker="dot", label="Price path")
plt.hline(103)    # Upper barrier
plt.hline(97)     # Lower barrier
plt.hline(100)    # Entry price
plt.title("Triple Barrier Method")
plt.xlabel("Time (bars)")
plt.ylabel("Price")
plt.plotsize(65, 22)
plt.theme("clear")
print(re.sub(r'\x1b\[[0-9;]*m', '', plt.build()))

Mandatory Settings

Every chart MUST use these settings:

Marker Reference

Rendering Command

/usr/bin/env bash << 'RENDER_EOF'
python3 << 'CHART_EOF'
import re
import plotext as plt

x = list(range(20))
y = [97, 98, 100, 101, 100, 98, 100, 101, 102, 101,
     100, 98, 100, 101, 102, 103, 102, 101, 100, 100]

plt.clear_figure()
plt.plot(x, y, marker="dot", label="Price path")
plt.hline(103)
plt.hline(97)
plt.hline(100)
plt.title("Triple Barrier Method")
plt.xlabel("Time (bars)")
plt.ylabel("Price")
plt.plotsize(65, 22)
plt.theme("clear")
print(re.sub(r'\x1b\[[0-9;]*m', '', plt.build()))
CHART_EOF
RENDER_EOF

Embedding in Markdown (MANDATORY: Source Adjacent to Chart)

Every chart MUST be immediately followed by a <details> block with Python source. Explanatory text goes after the <details> block, never between chart and source.

✅ CORRECT: Chart → <details> → Explanatory text
❌ WRONG:   Chart → Explanatory text → <details>

See ./references/api-and-patterns.md for full embedding template.

Mandatory Checklist

• [ ] plt.clear_figure() — Reset state
• [ ] marker="dot" — Dot marker for GitHub
• [ ] plt.theme("clear") + re.sub() strip — No ANSI codes
• [ ] plt.title("...") — Every chart needs a title
• [ ] plt.xlabel / plt.ylabel — Axis labels
• [ ] plt.plotsize(65, 22) — Fits 80-col code blocks
• [ ] <details> block immediately after chart (before any explanatory text)

Troubleshooting

Resources

• plotext GitHub
• Full API, patterns, and embedding guide
• Tool selection rationale

Post-Execution Reflection

After this skill completes, check before closing:

1. Did the command succeed? — If not, fix the instruction or error table that caused the failure. 2. Did parameters or output change? — If the underlying tool's interface drifted, update Usage examples and Parameters table to match. 3. Was a workaround needed? — If you had to improvise (different flags, extra steps), update this SKILL.md so the next invocation doesn't need the same workaround.

Only update if the issue is real and reproducible — not speculative.

Plotext Financial Chart — API and Patterns Reference

Core API

import re
import plotext as plt

# Data
x = list(range(20))
y = [100, 101, 102, 101, 100, 99, 98, 99, 100, 101, 102, 103, 102, 101, 100, 99, 100, 101, 102, 101]

# Setup
plt.clear_figure()
plt.plot(x, y, marker="dot", label="Price path")
plt.title("Chart Title")
plt.xlabel("Time (bars)")
plt.ylabel("Price")
plt.plotsize(65, 22)         # Width x Height in characters
plt.theme("clear")

# Horizontal reference lines (barriers, thresholds)
plt.hline(103)               # Upper barrier
plt.hline(97)                # Lower barrier
plt.hline(100)               # Entry price

# Build and strip ANSI
output = re.sub(r'\x1b\[[0-9;]*m', '', plt.build())
print(output)

Key Functions

Chart Patterns

Triple Barrier Method

import re
import plotext as plt

x = list(range(20))
y = [97, 98, 100, 101, 100, 98, 100, 101, 102, 101, 100, 98, 100, 101, 102, 103, 102, 101, 100, 100]

plt.clear_figure()
plt.plot(x, y, marker="dot", label="Price path")
plt.hline(103)    # Upper barrier (+pt x sigma)
plt.hline(97)     # Lower barrier (-sl x sigma)
plt.hline(100)    # Entry price
plt.title("Triple Barrier Method")
plt.xlabel("Time (bars)")
plt.ylabel("Price")
plt.plotsize(65, 22)
plt.theme("clear")
output = re.sub(r'\x1b\[[0-9;]*m', '', plt.build())

Price Path with Moving Average

import re
import plotext as plt

x = list(range(30))
price = [100, 101, 103, 102, 104, 103, 105, 104, 106, 105,
         107, 106, 105, 104, 103, 102, 101, 100, 99, 98,
         97, 98, 99, 100, 101, 102, 103, 104, 105, 106]
# Simple moving average (window=5)
ma = [None]*4 + [sum(price[i-4:i+1])/5 for i in range(4, 30)]

plt.clear_figure()
plt.plot(x, price, marker="dot", label="Price")
plt.plot(x[4:], ma[4:], marker="dot", label="SMA(5)")
plt.title("Price with Moving Average")
plt.xlabel("Time")
plt.ylabel("Price")
plt.plotsize(65, 18)
plt.theme("clear")
output = re.sub(r'\x1b\[[0-9;]*m', '', plt.build())

Range Bar Threshold Visualization

import re
import plotext as plt

x = list(range(15))
price = [100, 100.5, 101, 101.5, 102, 102.5, 102, 101.5, 101, 100.5, 100, 99.5, 99, 99.5, 100]

plt.clear_figure()
plt.plot(x, price, marker="dot", label="Price")
plt.hline(102.5)
plt.hline(97.5)
plt.title("Range Bar Threshold (250 dbps)")
plt.xlabel("Ticks")
plt.ylabel("Price")
plt.plotsize(50, 15)
plt.theme("clear")
output = re.sub(r'\x1b\[[0-9;]*m', '', plt.build())

Size Guidelines

Embedding in Markdown

Template (MANDATORY: Source Immediately After Chart)

Every rendered chart MUST be followed immediately by a collapsible <details> block containing the Python source code. This is non-negotiable for:

• Reproducibility: Future maintainers can regenerate the chart
• Editability: Data or styling can be modified and re-rendered
• Auditability: Changes to charts are trackable in git diffs

Ordering Convention (CRITICAL)

The <details> block MUST be immediately adjacent to the chart — no explanatory text between them:

✅ CORRECT ORDER:
   1. Chart (code block)
   2. <details> with source (immediately after)
   3. Explanatory text (after <details>)

❌ WRONG ORDER:
   1. Chart (code block)
   2. Explanatory text
   3. <details> with source

Why: The source code is part of the chart artifact. When explanatory text is inserted between chart and source, future edits risk separating or losing the reproducibility information. Keeping them adjacent ensures the chart + source travel together through document edits.

Complete Example

````markdown

Triple Barrier Method

                        Triple Barrier Method
   ┌────────────────────────────────────────────────────────────┐
103├ •• Price path ────────────────────────────────•────────────┤
   │                                              • •           │
   ...
 97├•───────────────────────────────────────────────────────────┤
   └┬──────────────┬──────────────┬─────────────┬──────────────┬┘
   0.0            4.8            9.5          14.2          19.0
Price                        Time (bars)

<details> <summary>plotext source</summary>

import re
import plotext as plt

x = list(range(20))
y = [97, 98, 100, 101, 100, 98, 100, 101, 102, 101,
     100, 98, 100, 101, 102, 103, 102, 101, 100, 100]

plt.clear_figure()
plt.plot(x, y, marker="dot", label="Price path")
plt.hline(103)
plt.hline(97)
plt.hline(100)
plt.title("Triple Barrier Method")
plt.xlabel("Time (bars)")
plt.ylabel("Price")
plt.plotsize(65, 22)
plt.theme("clear")
print(re.sub(r'\x1b\[[0-9;]*m', '', plt.build()))

</details>

The triple barrier method (de Prado, AFML Ch. 3) uses three barriers:

• Upper barrier: Take-profit level at +pt × σ
• Lower barrier: Stop-loss level at -sl × σ
• Vertical barrier: Maximum holding period of h bars

This chart shows a price path that experiences drawdown (MAE) before recovering to hit the upper barrier (MFE). ````

The `<details>` block is MANDATORY and must be immediately after the chart — never insert explanatory text between them.

GFM Collapsible Section Rules

1. Blank lines required — Must have empty line after <summary> and before </details> for Markdown to render 2. No indentation — <details> and <summary> must be at column 0 3. Summary text — Always use plotext source for consistency

Success Criteria

Correctness

1. Renders without error — Python script runs cleanly 2. Data accurate — All data points and reference lines visible 3. No ANSI codes — Output is pure text (no color escapes) 4. Source preserved (MANDATORY) — <details> block with runnable Python source

Aesthetics

1. Dot marker only — • characters render at correct width on GitHub 2. Readable labels — Title, axis labels, legend visible 3. Appropriate size — Chart fits code block without horizontal scroll 4. Clean diagonals — Dot marker produces recognizable slope patterns

Portability

1. GitHub rendering — Correct alignment in GitHub markdown preview 2. Terminal rendering — Correct in iTerm2, Kitty, VS Code terminal 3. Editor rendering — Correct in VS Code, vim, any monospace editor 4. No font dependencies — Dot marker works in any monospace font

Evolution Log

Convention: Reverse chronological order (newest on top, oldest at bottom). Prepend new entries.

---

2026-02-26: Initial Evolution Log

Status: Skill is in use and maintained. Track improvements here.

Purpose

This evolution log tracks updates to the skill. Each entry should note:

• What changed (content, structure, tooling)
• Why it changed (bug fix, feature request, best practice)
• Files affected

How to Use

1. When updating SKILL.md or references, add an entry here with the date 2. Keep entries reverse-chronological (newest first) 3. Link to ADRs or GitHub issues when relevant 4. Reference specific line changes when helpful

---

Tool Selection Rationale

Evaluation Summary

Evaluated 6 ASCII/text chart tools for rendering financial line charts in GitHub Flavored Markdown. The primary use case is triple barrier diagrams, price paths with barriers/thresholds, and range bar visualizations.

Tools Evaluated

Detailed Comparison

asciichartpy

• Output: Plain ASCII box-drawing characters (╭╮│╯╰)
• Diagonals: Staircase only — slopes rendered as vertical steps
• GitHub: Renders correctly (pure ASCII)
• Verdict: No true diagonals, no x-axis labels, no title support
• Rating: 2/5

plotille

• Output: Braille Unicode dots (U+2800-U+28FF)
• Diagonals: True smooth slopes via 2x4 Braille sub-pixels
• GitHub: Misaligned — Braille characters render at wrong width in GitHub's font
• Verdict: Font-dependent, Y-axis labels have too many decimals
• Rating: 4/5 (terminal), 2/5 (GitHub)

plotext (SELECTED)

• Output: Configurable — dot, HD blocks, Braille, FHD
• Diagonals: Depends on marker mode
• GitHub: Dot and HD markers align correctly; Braille and FHD do not
• Verdict: Best overall — matplotlib-like API, all features needed
• Rating: 5/5

Marker mode evaluation within plotext:

Selected: dot marker — universal alignment, zero font dependencies.

svgbob (Rust CLI)

• Output: SVG vector graphics from ASCII input
• Diagonals: True smooth SVG lines
• GitHub: SVG not embeddable in markdown code blocks
• Verdict: Excellent for SVG documents, not for inline markdown
• Parentheses issue: Renders () as SVG arcs
• Rating: 5/5 (SVG), 0/5 (markdown code blocks)

GoAT (Go CLI)

• Output: SVG vector graphics from ASCII input
• Diagonals: True smooth SVG polylines
• GitHub: SVG not embeddable in markdown code blocks
• Verdict: Better than svgbob (handles parentheses correctly, dark mode)
• Rating: 5/5 (SVG), 0/5 (markdown code blocks)

Ascidia (Python CLI)

• Output: PNG/SVG from ASCII input
• Dependencies: Requires system cairo library (brew install cairo)
• Diagonals: True image lines with dashed diagonal support
• GitHub: Image output, not text
• Verdict: Heavy dependencies, less maintained
• Rating: 3/5

Font Compatibility Research

The Braille Problem

Braille Unicode characters (U+2800-U+28FF) require fonts with native monospace Braille glyphs. When a font lacks these, the OS falls back to a different font with different glyph metrics, causing horizontal misalignment.

Fonts with native Braille support:

• DejaVu Sans Mono
• Iosevka Term
• Hack
• Menlo (macOS, based on DejaVu)

Fonts lacking Braille:

• JetBrains Mono (open issue #630)
• Fira Code (partial, relies on fallback)

GitHub's font stack: ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas, Liberation Mono, monospace

GitHub uses SF Mono / Menlo on macOS, which has Braille support, but alignment still varies across platforms and browsers. The dot marker (•) avoids this problem entirely.

Why Dot Marker Wins

The bullet character • (U+2022) is:

1. Present in every monospace font 2. Rendered at correct character cell width universally 3. Not affected by font fallback mechanisms 4. Visually distinct as a data point

Trade-off: Lower resolution (1x1 per cell vs 4x2 for Braille), but universal alignment is more important for documentation.

Decision

Tool: plotext Marker: dot (•) Rationale: Best API (matplotlib-like), all chart features needed (title, axes, hlines, legend), universal GitHub alignment with dot marker, no font dependencies.