# Read Reference Source First

> Use whenever the task is to port behavior from an existing known-good implementation (Pine Script indicator, TradingView feature, library function, "match the Bloomberg chart"). FIRST tool call is to read the source via the available MCP — pinescript for Pine, WebFetch for URLs, file read for locals. Substituting intuition for the one-tool-call-away source costs iterations.

- Skill: `traderspost/read-reference-source-first` (Agent Skill)
- Install (CLI): `npx skillmds@latest add traderspost/read-reference-source-first`
- Raw SKILL.md: https://api.skillmd.com/api/skills/traderspost/read-reference-source-first/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: traderspost (https://skillmd.com/u/traderspost)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/traderspost/read-reference-source-first

---


# Read the reference source FIRST before porting

When a task says "match the behavior of X" — Pine indicator, TradingView's "Anchored VWAP", competitor's chart feature, a paper's algorithm — the temptation is to start coding based on what the term sounds like. Resist. The first tool call should always be to read the actual source.

This lesson was learned at a cost of 3 wrong-implementation iterations on a single feature. The agent implemented a "trend fill" effect based on what the words sounded like (recolor the line) instead of what the Pine source actually did (per-bar color BOTH lines + transparent area fill BETWEEN them, with fill direction matching the bull/bear state). The Pine source was one MCP call away the whole time. The operator finally had to say "you should examine the original pine script because you're missing ideas" before the agent went and read it.

## When to use

Reach for this skill if the task description contains:

- "Match the TradingView X" / "port the Pine indicator Y"
- "Like in [name of well-known product]"
- A reference screenshot from another tool
- "The way [library / paper / spec] does it"
- ANY mention of an existing implementation the operator considers canonical

## The pattern

```
1. Identify the reference source.
   - Pine Script → mcp__pinescript__* (pine_search, pine_reference, pine_examples)
   - TradingView indicator → mcp__pinescript or web search for the script ID
   - Library function → file read or WebFetch the docs
   - Competitor screenshot → ask the operator for the closest available source / docs / videos
   - Local file → just read it

2. Read the source. ALL OF IT, not just the part that "sounds relevant."

3. Note the surprising behaviors. There WILL be surprises. They are
   why the operator asked you to match an existing implementation
   instead of just describing what they want.

4. ONLY THEN propose an implementation.
```

The propose-after-read flow inverts the usual instinct (propose, then iterate when wrong). Inverting it once costs ~30 seconds for the read. NOT inverting it costs 1-3 wrong-implementation iterations of 5-30 minutes each.

## Available reference-reading tools

The set is session-dependent. Common ones worth checking before starting a port:

| Tool | What it reads | When |
|---|---|---|
| `mcp__pinescript__pine_search` | Pine language docs, built-ins, syntax | Any Pine Script port |
| `mcp__pinescript__pine_reference` | Specific function/keyword reference | Detail-level lookups |
| `mcp__pinescript__pine_examples` | Worked examples of patterns | "How is the typical X done in Pine?" |
| `WebFetch` | Any URL | TradingView script pages, paper PDFs, library docs |
| `Read` | Local files | Vendor SDKs, local reference impls, git submodules |
| Chrome / browser MCP | A live web page | When you need to see the reference rendered |

Know which of these are available BEFORE starting a port. If the task mentions a Pine source but the Pine MCP isn't available in this session, that's a blocker to flag — not a permission to guess.

## Gotchas

- **The reference name doesn't tell you the behavior.** "Trend fill" sounds obvious. It is not. Indicator names are marketing; the source is what ships.
- **A code reference is not a screenshot reference.** Reading the source tells you the math. Looking at the screenshot tells you the styling. You need both — see `browser-verify-ui-changes`.
- **The MCP being "available" isn't the same as "checked."** If the session's tool list includes the MCP but you haven't actually used it, you don't have the source loaded. The check is the call.
- **Don't paraphrase the source to the operator.** Quote it or link to it. The operator may know the source better than you and spot a missing nuance.
- **For long sources, scan for the specific behavior the task names.** Don't read 800 lines of an indicator to find the 12 lines that implement "trend fill."

## Reference implementation

In the project where this was learned, the discipline was eventually codified as a feedback-memory note titled "Read reference source before porting" referenced from a top-level memory index, and revisited at the start of every porting task.

## Related skills

- `browser-verify-ui-changes` — its companion discipline ("don't claim done; screenshot and diff")
- `lightweight-charts-integration` — the chart layer the ported indicator gets drawn into
- `pine-to-typescript-port` — when the source is Pine specifically, the concept-mapping table there is the next step after reading the source