# Feature Specification: Variable Logger Indicator

## 1. High-Level Goal

To create a "Variable Logger" indicator that acts as a complementary tool to the "Condition Analyzer". Where the analyzer shows *what* conditions fired, the logger will show *why* they fired by displaying the underlying numerical values of the variables that constitute a given signal. This is a deep-dive debugging tool.

## 2. Key Features (User Stories)

*   As a user, I want to select a single "trigger" condition from a dropdown list, identical to the one in the Condition Analyzer.
*   As a user, when the selected trigger condition fires on a bar, I want to see the specific numerical values of the key variables that were used in that condition's calculation.
*   As a user, I want this information displayed in a way that does not clutter the main chart, such as in a dedicated table or within the Data Window.
*   As a user, I want to see not only the variables that make up the trigger condition ("Component Variables") but also a curated list of other key "Contextual Variables" from the strategy to help identify new potential filters.
*   As a user, I want the Component Variables to be visually distinct (e.g., full opacity) from the Contextual Variables (e.g., partial transparency).
*   As a user, I want to control the transparency level for the Contextual Variables via an input setting.


## 3. Implementation Plan

*   **New Script:** All logic will be contained in a new script: `IndicatorVariableLogger.pine`.

*   **Synchronization Requirement:** This indicator must duplicate all necessary inputs and calculation logic from `MainStrategy.pine` to ensure it has access to the true state of all variables.

*   **User Inputs:**
    *   An `input.string()` with a dropdown (`options`) will allow the user to select the primary "trigger" condition.
    *   An `input.int()` will allow the user to set the transparency percentage (e.g., 50) for "Contextual Variables".


*   **Data Exposure from Libraries:**
    *   The core libraries (e.g., `LibraryLongEntry`, `LibraryMACD`) will need to be updated.
    *   Functions that calculate conditions will be modified to return not just the final boolean, but also a `map` or a custom `type` object containing the key intermediate variables.
    *   Example: `f_calculateLongEntry` might return a `map[string, float]` that includes keys like "macd_slope_current", "m2_shortOffsetDiff", etc., for the bar on which the condition fired.

*   **Trigger & Display Logic:**
    *   On each bar, the script will check if the user-selected trigger condition is `true`.
    *   If it is, the script will retrieve the map of variables associated with that condition.
    *   The script will also gather a predefined list of key **Contextual Variables** (e.g., `stoch_value`, `macd_slope_current`, `m2_shortOffsetDiffToNbarsOut`, etc.) that are useful for general analysis.
    *   It will then use `plotchar()` with `display=display.data_window` to log all these key-value pairs. This makes the data visible in the Data Window when hovering over the trigger bar.
    *   The `color` argument of `plotchar()` will be set dynamically. If a variable is a Component Variable, its color will have 0% transparency. If it is a Contextual Variable, its color will use the user-defined transparency input.

## 4. Challenges & Considerations

*   **Library Refactoring:** The most significant effort will be modifying the libraries to expose the necessary internal variables. This requires careful planning to avoid making function signatures overly complex. Using maps is a good way to return a variable number of debug values without changing the function signature every time.
*   **Variable Selection:** The implementation will need a curated list of both Component Variables (per condition) and a globally useful list of Contextual Variables. Keeping this list relevant but not overwhelming will be a key design challenge.
*   **Performance:** Calculating and storing maps of data on every bar could be performance-intensive. The logic should be optimized to only construct and store this data when a trigger event actually occurs.
*   **Display Clutter:** Even within the Data Window, displaying dozens of variables can be overwhelming. The initial implementation may require careful formatting of the `plotchar` text (e.g., using prefixes like `Cmp:` and `Ctx:`) to make the output readable.


## 5. Role in the Development Workflow

This tool is the final step in the deep-dive analysis workflow:
1.  **`MainStrategy`:** Identify a general performance issue with a condition.
2.  **`IndicatorConditionAnalyzer`:** Use the table to find patterns of co-occurring signals on bad trades. Form a hypothesis (e.g., "This condition fails when MACD slope is negative").
3.  **`IndicatorVariableLogger`:** Use this tool to verify the hypothesis by inspecting the exact numerical value of the MACD slope on those specific failing trades. This provides the concrete data needed to add a precise filter (e.g., `and macd_slope_current > -5.0`).