/ia-pinescript

name: ia-pinescript
class: language
description: >-
  Pine Script v6: syntax, performance, error diagnosis, backtesting,
  visualization. Use when writing or debugging `.pine` files or TradingView
  Pine indicators/strategies.
paths: "**/*.pine"

Pine Script Development

**Verify before implementing**: For Pine Script version-specific syntax or new built-in functions, look up current official docs before writing code. Prefer Context7 (`query-docs`) when available. Otherwise use available web tools to read the [TradingView Pine Script docs](https://www.tradingview.com/pine-script-docs/) for the script's version. TradingView updates Pine Script frequently and training data may be stale.

Critical Syntax Rules

• Keep simple ternaries readable; multiline expressions require valid continuation indentation. For complex ternaries, use intermediate variables:

  isBull = close > open
  barColor = isBull ? color.green : color.red

• **Continuation lines outside parentheses MUST be indented by a non-multiple of 4**: same indentation as the start errors, and 4/8/12 spaces parse as a local block and error too (2 spaces is the conventional choice). Inside parentheses (function calls, parenthesized expressions) any indentation works, including multiples of 4
• **NEVER use plot() inside local scopes** (if/for/functions); use conditional value instead: `plot(condition ? value : na)`
• Use `barstate.isconfirmed` when signals require the chart bar's closing values. It does not establish that requested higher-timeframe values are confirmed; inspect `request.security()` offsets and lookahead separately.

Platform Limits

Check the current [platform limits](https://www.tradingview.com/pine-script-docs/writing/limitations/) before sizing a script: 64 plot counts (one call can consume several); up to 500 line, box, or label IDs each and 100 polyline IDs; 40 unique `request.*()` calls, or 64 on Ultimate; 100,000 compiled tokens. History buffers, requested intrabars, and chart history have distinct limits; there is no general 500-bar `request.security()` history limit.

• Drawings positioned with `xloc.bar_index` reach at most 9,999 bars into the past and 500 into the future; for anything older, switch the drawing to `xloc.bar_time` and pass a timestamp (a time value without `xloc.bar_time` is treated as a future bar index and errors)
• Set the relevant `max_*_count` declaration parameter and cap growth with a rolling buffer: push each object, then `line.delete(arr.shift())` after the intended line count is exceeded. The default display count is approximately 50 per drawing type.

Performance

• **Tuple security calls**: one `request.security()` returning `[close, high, low]` instead of 3 separate calls
• Pre-allocate arrays with `array.new<type>(size)` instead of push-and-resize
• Evaluate history-dependent functions such as `ta.rsi()` in global scope on every bar. Short-circuit signal predicates using those stored results; see [Pine v6 lazy evaluation](https://www.tradingview.com/pine-script-docs/migration-guides/to-pine-version-6/#lazy-evaluation-of-conditions).
• Cache repeated calculations in variables; Pine recalculates every bar
• Iterate collections with `for item in myArray` (or `for [i, item] in myArray`) instead of `for i = 0 to array.size(...) - 1`; both forms use updated collection sizes on later iterations.
• For `for...in`, resize arrays or matrices only with the changing iteration bounds in mind. To add or remove map entries, iterate a `map.keys()` snapshot or a `map.copy()` while modifying the original. Avoid directly initializing `var`/`varip` with a loop result: the loop stops after its first iteration. Declare first and assign with `:=`, or return the loop result from a function. See the [Pine v6 loop rules](https://www.tradingview.com/pine-script-docs/language/loops/).
• Model related values as a user-defined type, not parallel arrays: `type Trade` with `float entry`, `int startBar`, plus `method` functions, stored in one `array<Trade>`. Parallel arrays (`entries`, `startBars`, ...) desync on any missed push/remove and every operation must be repeated per array; one typed array keeps each object's fields together

Debugging

Use [Pine Logs](https://www.tradingview.com/pine-script-docs/writing/debugging/) through `log.info()`, `log.warning()`, and `log.error()`, plus these visual checks:

• **Label debugging**: `label.new(bar_index, high, str.tostring(myVar))` to inspect values; cap retained labels explicitly.
• **Table monitor**: `table.new()` with `barstate.islast` for real-time variable dashboard
• **Debug mode toggle**: use `if input.bool(false, "Debug")` for local debug code; keep plot calls global.
• **Repainting checks**: record live signals with timestamps, then compare the same bars after reload. `value[1]` refers to the preceding bar and does not detect revisions to an earlier calculation.

Strategy & Backtesting

• Use `strategy.*` functions: `strategy.wintrades`, `strategy.losstrades`, `strategy.grossprofit`
• Declare persistent drawdown state before updating it:

  var float maxEquity = strategy.equity
  maxEquity := math.max(maxEquity, strategy.equity)
  dd = maxEquity > 0 ? (maxEquity - strategy.equity) / maxEquity * 100 : na

• Estimate annualized Sharpe from mean excess returns divided by their standard deviation, scaled by the square root of periods per year; state the sampling interval and annualization assumptions and handle zero variance.
• **Walk-forward validation**: optimize on period 1, test on period 2, re-optimize on period 2, test on period 3. Compare degradation against sampling uncertainty, costs, and regime changes; no universal percentage establishes overfitting.
• **Indicator accuracy testing**: at bar `t`, score `prediction[horizon]` against the now-realized outcome, such as `close > close[horizon]`, excluding warmup bars. Positive offsets reference the past, never future bars; see [history referencing](https: