OPEN-SOURCE SCRIPT
Updated

Trap Failure Planner [AGPro Series]

753
Trap Failure Planner [AGPro Series]

🧠 Core Idea

Is the trap thesis itself failing and handing control back through the edge?


📌 Overview / What it does

Trap Failure Planner is a chart-first control-return planner for traders who study trap behavior, failed participation, false break recovery, and post-trap execution readiness.

Instead of only marking the first trap or false break, the script watches the second step: after a trap thesis appears, does that thesis keep control, or does price return through the trap edge with enough quality to matter? It produces a 0-100 Failure Score, trap thesis zones, control-return labels, risk-edge guides, target-guide references, alerts, and a compact AG Pro planning panel.

It does not predict future price, automate entries, or claim that a control return must continue. Its role is to organize one specific decision question with clean visual structure.


🎯 Purpose & Design Philosophy

This script was built to fill the gap between first-touch trap markers and practical trade review.

Many tools stop when price runs a level and closes back inside. That can be useful, but traders still need to know whether the trap thesis survives after the first reaction. Trap Failure Planner focuses on that later decision point: is the trap still in control, or did the other side reclaim the edge?

The design supports a planner mindset. It helps traders evaluate state, score, risk edge, target context, and next action without turning the chart into a crowded signal board.


⚡ Why This Script Is Different

Most tools focus on the first false break, sweep, trap label, or reclaim back inside a range.

This script does NOT try to become another false-break trap detector, inducement scanner, liquidity grab detector, stop-hunt map, order block map, or generic support / resistance zone tool.

Instead, it focuses on the failure of the trap thesis itself. The workflow begins only after a trap thesis exists, then waits for control to return through the edge with persistence, follow-through, volume response, and acceptance quality.

That makes it a second-stage trap failure planner, not a first-stage trap detector.


⚙️ Methodology

1. Context Detection
The script builds recent upper and lower trap-thesis rails from prior price action and normalizes behavior with ATR.

2. Reference Mapping
When price probes beyond a rail and closes back inside, the script maps a trap thesis zone between the rail and the probe extreme.

3. Reaction Evaluation
The planner tracks whether price returns through the trap edge within the failure window. The 0-100 model evaluates false break behavior, close recovery, follow-through, volume spike, control-return persistence, and level acceptance.

4. Visual Output
Qualified events print Trap Failed labels, retain the centered trap zone, and project risk-edge and target-guide references.


🗺️ How to Read the Chart

Zones = the active trap thesis area between the control edge and the probe extreme.

Labels = trap thesis states, sparse testing states, and confirmed Trap Failed events.

Colors = teal for bullish control-return context, pink for bearish control-return context, yellow for testing states, indigo for target guides, and red for risk edges.

Panel = the AG Pro summary showing Trap State, Failure Score, Control Shift, Risk Edge, and Action.


🚦 Signals & States

• Upper Trap Thesis → price probed above the upper rail and closed back inside; the planner watches whether that trap thesis survives.

• Lower Trap Thesis → price probed below the lower rail and closed back inside; the planner watches whether that trap thesis survives.

• Return Test → price is challenging the trap edge, but the score or close-count requirement is not complete yet.

• Bull Control Return → an upper trap thesis failed and control returned back above the edge.

• Bear Control Return → a lower trap thesis failed and control returned back below the edge.


🔔 Alerts Logic

Alerts trigger when upper or lower trap thesis states appear and when qualified bull or bear control-return events are confirmed.

High-score alerts require the event score to meet the selected alert threshold.

Alerts are attention markers only. They are not trade instructions, entry commands, or outcome guarantees.


🧩 Confluence Logic

The score becomes stronger when the trap thesis probe is clean, price returns through the trap edge, the return holds for the required close count, follow-through expands, volume rises relative to baseline, and the close location supports the control-return side.

When these components align, the trap failure context becomes cleaner. When they do not align, the script stays in watch, return-test, or reset mode.


📊 When to Use

• Markets with visible trap and failed-participation behavior

• False break structures where the first trap thesis may fail

• Breakout or breakdown attempts that get rejected, then reclaim control again

• Range-edge reviews where traders need a second-stage decision layer


⚠️ When NOT to Use

• Extremely low-liquidity symbols

• Very noisy micro timeframes with erratic wicks

• News spikes where structure changes too quickly

• Charts where recent rails are not meaningful planning references


🎛️ Key Inputs

• Planner Side → choose Auto, Bull Return Only, or Bear Return Only.

• Trap Thesis Lookback → controls the rolling reference rails used for trap thesis detection.

• Failure Window Bars → defines how long a trap thesis remains active before reset.

• Control Return Closes → defines how many closes beyond the edge are required for confirmation.

• Minimum Failure Score → controls how selective confirmed Trap Failed labels are.

• Control Return Buffer ATR → controls how much acceptance beyond the edge is required.

• Risk / Target Settings → control planning guide placement.

• Visual Settings → control zones, guides, labels, panel location, theme, and font sizes.


🖥️ Interface & Visual Design

The panel is built for fast review: state first, score second, control shift third, then risk and action.

The trap thesis zone includes centered text so the chart remains readable without extra floating explanations.

Labels are compact, offset away from candles, and controlled by cooldown and maximum-visible settings.


🧪 Practical Usage Workflow

1. Read the panel to identify whether a trap thesis is active or already failed.
2. Check the trap thesis zone and the edge being tested.
3. Review the Failure Score and Control Shift rows.
4. Use the Risk Edge and target guide as planning references.
5. Confirm the event inside broader market context.


🔍 Interpretation Guidelines

Think in terms of control, not prediction.

A trap thesis label means price created a possible trap context. A Trap Failed label means that thesis lost control according to the script rules. A higher score means the failure was cleaner across the model components, not that the next move is guaranteed.


🚫 What This Script Is NOT

• Not a prediction engine

• Not financial advice

• Not auto trading

• Not guaranteed signals

• Not a false-break trap detector clone

• Not an inducement scanner

• Not a liquidity grab detector

• Not a support / resistance zone scanner

• Not an order block or fair value gap map


⚠️ Limitations & Transparency

Trap behavior depends on timeframe, liquidity, spread, volatility, and market context.

The script uses a deterministic ruleset. It cannot know news context, hidden order flow, participant intent, or whether a control return will continue.

More aggressive settings may show more events but also more noise. More conservative settings may improve selectivity while reducing frequency.


🧠 Market Context Notes

Trap thesis failure often becomes more meaningful when it aligns with broader structure, volatility expansion, session context, or liquidity behavior.

The script is designed to organize that review, not replace it.


🧾 Use Case Examples

When price probes above a recent upper rail, closes back inside, and later returns above that edge with persistence and follow-through, the planner can mark Bull Control Return if the score is strong enough.

When price probes below a recent lower rail, closes back inside, and later returns below that edge with acceptance, the planner can mark Bear Control Return.


🧱 System Philosophy

AGPro decision tools are built to reduce chart ambiguity by turning raw price events into structured review states.

Trap Failure Planner follows that philosophy by separating the first trap thesis from the later question of whether that thesis actually survives.


🔐 Non-Promise Statement

No indicator can remove uncertainty.

No script can guarantee direction, continuation, reversal, or profit.


📉 Risk Disclosure

Trading involves risk.

Users are responsible for their own decisions, risk management, position sizing, and interpretation.

This script is for educational and analytical use only and does not provide financial advice.


📚 Educational Note

Use this script to study what happens after a trap thesis forms. The key question is not only whether price created a trap, but whether that trap can continue to defend control.
Release Notes
UPDATE NOTES - V1.3

This update focuses on premium chart readability, cleaner trap-thesis presentation, and calmer publication-ready defaults.

The core purpose of the script remains unchanged.
This release improves how trap thesis, control return, risk guide, target guide, labels, and panel states are presented on the chart.

This script continues to function as an analytical and visualization tool.
It does not attempt to predict price direction or provide guaranteed outcomes.


------------------------
What Changed
------------------------

* Cleaned the script header
The version header was standardized and the opening block was converted to a clean ASCII publication format.

* Refined label density
Sparse context labels are now disabled by default, event label cooldown is calmer, and the visible label cap is reduced for a cleaner public chart.

* Improved trap-zone visual hierarchy
Trap thesis zones now use concise centered box text and remain the primary visual layer for the active thesis.

* Optimized completed trap memory
The number of retained completed trap zones is lower by default, keeping the chart active without turning it into a cluttered history map.

* Improved panel behavior
The panel now rebuilds cleanly when location or theme changes and preserves the single merged blue AG Pro header row.


------------------------
Visual Improvements
------------------------

* Reduced context-label clutter from the prior version

* Kept event labels visible for a chart that does not feel empty

* Preserved centered trap-zone text for first-glance readability

* Refined the visual balance between trap thesis, failed trap label, and risk / target guides


------------------------
Interface & Usability
------------------------

* Panel location, theme, and font-size controls remain available

* Label font-size control remains available with Normal as the default

* Event labels remain enabled by default

* Context labels remain optional for users who want a more annotated chart


------------------------
Behavior Notes
------------------------

This update does not change the core analytical purpose of the script.

The goal is to improve clarity, visual balance, and usability, not to introduce predictive behavior.

Users should interpret outputs the same way as before, but with a cleaner and more publication-ready visual structure.


------------------------
Limitations Reminder
------------------------

The script remains a rule-based analytical tool.

Market conditions such as volatility, liquidity, false-break depth, and timeframe differences may affect how trap failure states appear.

Outputs should always be interpreted within broader market context.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice or guaranteed trading outcomes.

Users remain responsible for their own decisions.
Release Notes
UPDATE NOTES - V1.4

This update focuses on visual readability, trap-thesis interpretation, panel structure, and publication-ready chart context.

The core purpose of the script remains unchanged.
This release improves how the existing trap-failure logic is presented, organized, and interpreted on the chart.

This script continues to function as an analytical and visualization tool.
It does not attempt to predict price direction or provide guaranteed outcomes.


------------------------
What Changed
------------------------

* Rebuilt the trap-zone label architecture.
Active and completed trap zones now use separate centered solid badges instead of relying on native box text.

* Improved completed trap-failure badges.
Qualified trap failures now keep a clear FAIL score badge inside the completed zone for stronger light and dark chart readability.

* Refined workflow language.
Panel and label wording now presents liquidity, sweep, trap, and reaction behavior as review context rather than trade instructions.

* Updated state language.
The panel now uses cleaner context states such as Review Bull Return, Review Bear Return, Return Test, Watch Edge, Wait Close, and Scan Setup.

* Reworked event label wording.
Confirmed trap-failure labels now use REVIEW language with score context, keeping the output analytical and non-promising.

* Improved panel lifecycle handling.
The panel now recreates safely when visibility, location, theme, or font size changes.

* Reorganized panel flow.
The panel now prioritizes Workflow, Trap Context, Failure Score, Control Shift, Risk Edge, and Review.


------------------------
Visual Improvements
------------------------

* Improved chart readability by replacing weak native zone text with centered solid badges.

* Kept active trap-thesis zones and completed trap-failure zones visually distinct.

* Preserved enough event labels, zones, risk guides, and target guides for a fuller publication screenshot.

* Reduced text that can disappear inside transparent boxes.

* Improved light-theme and dark-theme readability through filled label backgrounds and contrast-safe text.

* Kept labels offset away from candles while preserving the existing default chart density.


------------------------
Interface & Usability
------------------------

* Preserved panel show / hide control.

* Preserved full panel location options, including top, middle, and bottom placements.

* Preserved dark and light panel themes.

* Preserved chart label font-size and panel font-size controls.

* Improved the panel header so it remains a single merged blue row with only the script name.


------------------------
Behavior Notes
------------------------

This update does not change the core trap-failure scoring logic.

The goal is to improve clarity and usability, not to introduce new predictive behavior.

Users should interpret outputs the same way as before, but with clearer trap context, zone badges, and workflow wording.


------------------------
Limitations Reminder
------------------------

The script remains a rule-based analytical tool.

Market conditions such as liquidity, volatility, timeframe differences, volume quality, and sudden market movement may affect how trap-thesis and control-return states appear.

Outputs should always be interpreted within broader market context.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice or guaranteed trading outcomes.

Users remain responsible for their own decisions.
Release Notes
🔧 UPDATE NOTES - V1.8

This update focuses on score-label clarity, level ownership, and cleaner publication visuals.

The core purpose of the script remains unchanged.
This release prevents the failure score from appearing like a price-level tag when it is actually an event-quality value.

This script continues to function as an analytical and visualization tool.
It does not attempt to predict price direction or provide guaranteed outcomes.


------------------------
What Changed
------------------------

• Removed the right-edge score tag from the default publication view
The failure score remains visible in the panel and confirmed event labels, but it no longer appears as a floating right-edge level tag by default.

• Added Show Score Guide Tag
Users who prefer an extra score badge can still enable it manually.

• Changed optional score tag styling
When enabled, the score badge uses a centered badge style instead of a left-pointing level-tag style.

• Kept right-edge tags focused on true references
Risk and target remain right-edge guide tags because they represent actual planning levels.


------------------------
Visual Improvements
------------------------

• Removed the impression that SCORE points to an empty price area

• Reduced visual ambiguity around right-edge guide tags

• Improved premium chart cleanliness on lower timeframes

• Preserved clear risk and target ownership


------------------------
Interface & Usability
------------------------

• Added Show Score Guide Tag input

• Default score guide tag state is off for cleaner publication screenshots

• Score remains available through the panel and REVIEW / FAIL chart labels

• Panel controls, label font controls, and guide tag controls remain available


------------------------
Behavior Notes
------------------------

This update does not change the core analytical logic of the script.

Trap thesis detection, failure score calculation, control-return confirmation, risk edge, target guide, alerts, and panel states remain unchanged.

The goal is only to prevent score information from looking like an ownerless price-level marker.


------------------------
Limitations Reminder
------------------------

The script remains a rule-based analytical tool.

Market conditions such as volatility, liquidity, timeframe differences, and data quality may affect how signals appear.

Outputs should always be interpreted within broader market context.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice or guaranteed trading outcomes.

Users remain responsible for their own decisions.
Release Notes
UPDATE NOTES - Version 1.9

This update focuses on adding a confirmation-anchored proof layer to the panel.

The core purpose of the script remains unchanged.
This release adds a proof layer that measures how often qualified control-return reviews advanced
in the return direction, and removes the redundant review row.

This script continues to function as an analytical and visualization tool.
It does not attempt to predict price direction or provide guaranteed outcomes.


------------------------
What Changed
------------------------

* Added a Proof Layer (Follow / Hold / React / Flip)
The panel now reports how qualified control-return reviews resolved on the current symbol and
timeframe. Each time a qualified trap-failure review prints, price is tracked forward over a
configurable horizon using the planner risk edge as the risk reference and a continuation of one
risk unit in the return direction as the reference target:
- Follow Rate : share of reviews that advanced one risk unit in the return direction first
- Hold Rate : share whose planner risk edge was not reached through resolution
- React Rate : share that produced an early favorable follow-through reaction
- Flip Rate : share whose planner risk edge was reached, meaning the return failed
A sample size (n) is shown so the rates are read in context, and they display as "building" only
until the first qualified review resolves.

* Removed the redundant review row
The review row largely repeated the workflow row. It was replaced so the panel now carries the
proof layer, keeping the workflow, trap context, failure score, control shift, and risk edge rows.

* Added hidden proof outputs
Follow, Hold, React, and Flip rates are exported as hidden plots so they can be used in alerts
and screeners without adding chart clutter.


------------------------
Visual Improvements
------------------------

* Reduced panel redundancy by removing the review row.

* Preserved the trap thesis zones, centered FAIL badges, event labels, risk-edge and target-guide
lines, and the right-edge guide tags.

* Kept label and zone density controlled with the existing cooldown and retention limits.


------------------------
Behavior Notes
------------------------

This update does not change the core trap, control-return, scoring, risk, or target logic.

The proof rates are descriptive statistics of qualified control-return reviews on the current
symbol and timeframe. They measure how often a qualified review advanced one risk unit in the
return direction before reaching the planner risk edge. The risk-unit target used for the proof
is capped at one risk unit, so it is a follow-through reliability measure and is intentionally
more conservative than the wider on-chart target guide, which remains a separate planning
reference. The proof rates do not change how traps, scores, states, or guides are produced.

Users should interpret outputs the same way as before, now with added reliability context.


------------------------
Limitations Reminder
------------------------

The script remains a rule-based analytical tool.

Proof rates depend on the available history and on how many qualified reviews occurred on the
current symbol and timeframe; a small sample (low n) should be treated with caution. Each review
is counted once, with the entry, risk edge, and risk-unit target frozen at the qualified bar.
Market conditions such as volatility, liquidity, and timeframe differences may affect how reviews
and rates appear.

Outputs should always be interpreted within broader market context.


------------------------
Risk Reminder
------------------------

This script is for educational and analytical purposes only.

It does not provide financial advice or guaranteed trading outcomes.

Users remain responsible for their own decisions.
Release Notes
Version 1.10 — Focused Trap-Map Hierarchy

This update improves the visual priority of the active trap-failure workflow while preserving the script’s existing trap detection, failure scoring, control-shift logic, proof methodology, alerts, and panel behavior.

• Reduced the default number of retained trap zones from 3 to 2. The active thesis and the most relevant recent completed structure now remain visible without allowing older zones and badges to crowd the chart.

• Retained the existing five-label limit, 28-bar label cooldown, and Normal label font size. These settings already provide an appropriate balance between event visibility and chart clarity.

• Preserved all trap detection, failure qualification, control-return evaluation, risk-edge mapping, target guidance, proof tracking, and alert conditions. This release changes the default visual memory only.

Disclaimer

The information and publications are not meant to be, and do not constitute, financial, investment, trading, or other types of advice or recommendations supplied or endorsed by TradingView. Read more in the Terms of Use.