CLAUDE.md

1# CLAUDE.md
2 
3# OutputLens Agent Operating Manual
4 
5Version: 1.0
6 
7This document provides context, rules, architecture guidance, product philosophy, UX standards, and implementation constraints for AI agents working on OutputLens.
8 
9Read this file before making any code, product, UX, architecture, copywriting, database, or business logic decisions.
10 
11---
12 
13# Product Overview
14 
15OutputLens is an institutional-grade risk intelligence platform.
16 
17The platform helps investors understand uncertainty before entering trades.
18 
19OutputLens does not attempt to predict markets.
20 
21OutputLens does not provide investment advice.
22 
23OutputLens does not generate buy or sell signals.
24 
25OutputLens quantifies potential outcomes and presents them through probability distributions, risk metrics, scenario analysis, and AI-assisted explanations.
26 
27The central product experience is analysis.
28 
29Everything else exists to support, enhance, monitor, or explain analysis.
30 
31---
32 
33# Core Mission
34 
35Help investors think like risk managers.
36 
37Most retail platforms encourage prediction.
38 
39OutputLens encourages probability-based decision making.
40 
41Every feature should improve one or more of:
42 
43- Risk understanding
44- Decision quality
45- Probability awareness
46- Portfolio awareness
47- Uncertainty management
48 
49If a proposed feature does not improve one of these areas, reconsider whether it belongs in the product.
50 
51---
52 
53# Core Philosophy
54 
55## Probability Over Prediction
56 
57OutputLens answers:
58 
59"What could happen?"
60 
61OutputLens does not answer:
62 
63"What will happen?"
64 
65Never present outputs as forecasts.
66 
67Never imply certainty.
68 
69Never imply future price direction.
70 
71---
72 
73## Risk Before Return
74 
75Risk information should always appear before upside information.
76 
77Priority order:
78 
791. Risk Score
802. VaR
813. Expected Shortfall
824. Tail Risk
835. Regime
846. Scenario Outcomes
857. Potential Upside
86 
87---
88 
89## Explain Complexity Simply
90 
91Sophisticated quantitative outputs should be translated into plain English.
92 
93Users should not need a finance degree to understand results.
94 
95Complexity belongs in calculations, not explanations.
96 
97---
98 
99## Institutional Tone
100 
101OutputLens should feel:
102 
103- Professional
104- Analytical
105- Calm
106- Quantitative
107- Objective
108 
109Avoid:
110 
111- Hype
112- Social trading language
113- Meme investing
114- Gambling terminology
115- Emotional copy
116 
117Think:
118 
119- Bloomberg Terminal
120- FactSet
121- BlackRock Aladdin
122- Institutional research reports
123 
124Not:
125 
126- Robinhood
127- Crypto casinos
128- Social trading apps
129 
130---
131 
132# Product Structure
133 
134OutputLens consists of the following major product areas.
135 
136---
137 
138## Dashboard
139 
140Purpose:
141 
142Provide a high-level overview of portfolio health.
143 
144Primary Components:
145 
146- Portfolio Risk Score
147- Portfolio VaR
148- Expected Drawdown
149- Market Regime
150- Risk Alerts
151- Analysis Usage
152- AI Insights
153- Watchlist
154- Market Snapshot
155 
156Dashboard Question:
157 
158"What requires attention today?"
159 
160---
161 
162## Analysis Workspace
163 
164Core product.
165 
166Users enter:
167 
168- Asset
169- Direction
170- Position Size
171- Time Horizon
172 
173Output:
174 
175- Simulation Results
176- Risk Metrics
177- Scenario Analysis
178- Regime Analysis
179- Distribution Analysis
180- AI Commentary
181 
182The Analysis Workspace is the highest-priority feature in the entire platform.
183 
184Protect this workflow.
185 
186---
187 
188## Analysis History
189 
190Stores previous analyses.
191 
192Purpose:
193 
194Track risk evolution over time.
195 
196Must support:
197 
198- Historical comparison
199- Performance tracking
200- Distribution review
201 
202---
203 
204## Portfolio Analysis
205 
206Portfolio-level aggregation of:
207 
208- Risk
209- Exposure
210- Correlation
211- Concentration
212- Scenario sensitivity
213 
214---
215 
216## Morning Briefing
217 
218Daily summary of:
219 
220- Risk changes
221- Regime changes
222- Portfolio health
223- Important observations
224 
225Morning Briefing is not a news feed.
226 
227---
228 
229## Risk Journal
230 
231Historical archive of:
232 
233- Analyses
234- Decisions
235- Risk observations
236 
237---
238 
239## Risk Pulse
240 
241Live monitoring layer.
242 
243Tracks:
244 
245- Risk score changes
246- Regime shifts
247- Tail risk changes
248 
249Purpose:
250 
251Detect deteriorating conditions.
252 
253---
254 
255## Regime Monitor
256 
257Tracks market state transitions.
258 
259Purpose:
260 
261Identify changing market environments.
262 
263---
264 
265## Risk Alerts
266 
267User-defined monitoring system.
268 
269Triggers when:
270 
271- Risk exceeds thresholds
272- Regime changes occur
273- Correlation spikes emerge
274 
275---
276 
277## Scenario Builder
278 
279Allows users to create stress scenarios.
280 
281Scenarios are stress tests.
282 
283Scenarios are not predictions.
284 
285---
286 
287## Stress Test Workspace
288 
289Runs positions against:
290 
291- Bull environments
292- Base environments
293- Bear environments
294- Custom shock events
295 
296---
297 
298## VaR Calculator
299 
300Calculates:
301 
302- Parametric VaR
303- Historical VaR
304- Monte Carlo VaR
305 
306---
307 
308## Correlation Scanner
309 
310Identifies:
311 
312- Hidden concentration risk
313- Portfolio overlap
314- Diversification quality
315 
316---
317 
318## Market Heatmap
319 
320Provides broad market context.
321 
322Purpose:
323 
324Context only.
325 
326Not a signal engine.
327 
328---
329 
330## Position Sizer
331 
332Provides risk-based sizing calculations.
333 
334Purpose:
335 
336Risk management.
337 
338Not trade recommendations.
339 
340---
341 
342## Earnings Risk
343 
344Evaluates historical earnings-event volatility.
345 
346Purpose:
347 
348Understand event risk.
349 
350---
351 
352## Volatility Analysis
353 
354Evaluates:
355 
356- Historical volatility
357- Regime volatility
358- Relative volatility
359 
360---
361 
362## Drawdown Analysis
363 
364Evaluates:
365 
366- Historical drawdowns
367- Recovery periods
368- Underwater duration
369 
370---
371 
372# Analysis Pipeline
373 
374All analysis follows the same lifecycle.
375 
3761. User submits analysis.
3772. Market data retrieved.
3783. Risk engine processes inputs.
3794. Simulations generated.
3805. Distribution constructed.
3816. Risk metrics calculated.
3827. Regime evaluated.
3838. Scenarios generated.
3849. AI commentary generated.
38510. Results persisted.
38611. Dashboard updated.
387 
388No workflow should bypass this pipeline.
389 
390---
391 
392# Risk Metrics
393 
394## Win Probability
395 
396Percentage of simulated paths ending positive.
397 
398Not a prediction.
399 
400Not a guarantee.
401 
402---
403 
404## Value at Risk (VaR)
405 
406Estimated maximum expected loss within a specified confidence interval.
407 
408Examples:
409 
410- VaR 90
411- VaR 95
412- VaR 99
413 
414---
415 
416## Expected Shortfall
417 
418Average loss beyond the VaR threshold.
419 
420Represents severe downside exposure.
421 
422---
423 
424## Tail Risk
425 
426Probability of extreme negative outcomes.
427 
428Higher tail risk requires greater caution.
429 
430---
431 
432## Risk Score
433 
434Composite indicator.
435 
436Used for ranking and monitoring.
437 
438Must never be described as expected return.
439 
440---
441 
442## Regime
443 
444Current market condition classification.
445 
446Examples:
447 
448- Bullish
449- Bearish
450- Transitional
451- Elevated Volatility
452 
453Regimes are probabilities.
454 
455Not forecasts.
456 
457---
458 
459# AI Commentary Rules
460 
461AI commentary exists to explain.
462 
463AI commentary does not calculate.
464 
465The risk engine is the source of truth.
466 
467---
468 
469## Allowed
470 
471AI may:
472 
473- Explain risk metrics
474- Explain distributions
475- Explain scenarios
476- Explain volatility
477- Explain regime conditions
478- Summarise portfolio risk
479- Highlight changes
480 
481---
482 
483## Forbidden
484 
485AI must never:
486 
487- Predict future prices
488- Recommend trades
489- Recommend buying
490- Recommend selling
491- Recommend leverage
492- Provide financial advice
493- Guarantee outcomes
494 
495---
496 
497## Bad Examples
498 
499"AMZN will likely rise."
500 
501"This stock should outperform."
502 
503"Buy this position."
504 
505"Target price is $250."
506 
507---
508 
509## Good Examples
510 
511"Downside risk remains elevated."
512 
513"The distribution suggests wider uncertainty."
514 
515"Tail exposure has increased."
516 
517"The current regime implies increased volatility."
518 
519---
520 
521# Subscription Tiers
522 
523## Free
524 
525Includes:
526 
527- 3 analyses per month
528- Limited simulation access
529- Basic risk metrics
530- 7-day history
531- US market support
532 
533---
534 
535## Starter
536 
537Includes:
538 
539- Expanded analysis limits
540- AI commentary
541- Regime Monitor
542- Earnings Risk
543- Drawdown Analysis
544- Volatility Analysis
545- Position Sizer
546 
547---
548 
549## Pro
550 
551Includes:
552 
553- Correlation Scanner
554- Risk Alerts
555- Portfolio Analytics
556- Unlimited History
557- Export Features
558 
559---
560 
561## Trader
562 
563Includes:
564 
565- API Access
566- Advanced Monitoring
567- Larger Portfolio Limits
568- Priority Processing
569 
570---
571 
572# Engineering Rules
573 
574## Business Logic
575 
576Never place business logic inside React components.
577 
578Use:
579 
580- Services
581- Hooks
582- Utility layers
583- Backend functions
584 
585---
586 
587## Source of Truth
588 
589Risk calculations are authoritative.
590 
591AI commentary is secondary.
592 
593Visualisations are derived.
594 
595---
596 
597## Determinism
598 
599Prefer deterministic outputs whenever possible.
600 
601Avoid hidden behaviour.
602 
603Avoid unexplained scores.
604 
605---
606 
607## Data Handling
608 
609Cache market data.
610 
611Reduce redundant API requests.
612 
613Prioritise performance and consistency.
614 
615---
616 
617## Security
618 
619Never expose:
620 
621- Internal model parameters
622- API secrets
623- Proprietary calculations
624- Internal confidence thresholds
625 
626---
627 
628# UX Rules
629 
630Always communicate:
631 
632- Probability
633- Risk
634- Uncertainty
635- Distribution
636 
637Avoid:
638 
639- Certainty
640- Forecasting
641- Target prices
642- Trading signals
643 
644---
645 
646# Design Principles
647 
648OutputLens should feel:
649 
650- Institutional
651- Premium
652- Quantitative
653- Professional
654 
655Design should be:
656 
657- Information dense
658- Data focused
659- Low distraction
660- Dark-theme friendly
661 
662Avoid:
663 
664- Excessive animation
665- Gamification
666- Celebration effects
667- Social features
668 
669---
670 
671# Future Feature Evaluation
672 
673Before building a feature ask:
674 
6751. Does it improve risk understanding?
6762. Does it improve decision quality?
6773. Does it increase probability awareness?
6784. Does it align with probability-first thinking?
6795. Does it avoid prediction-based behaviour?
680 
681If any answer is no, reconsider the feature.
682 
683---
684 
685# Agent Decision Framework
686 
687When uncertain:
688 
689Choose the option that:
690 
691- Improves risk visibility
692- Improves explainability
693- Improves decision support
694- Reduces ambiguity
695- Preserves institutional credibility
696 
697Never choose the option that:
698 
699- Increases speculation
700- Encourages gambling behaviour
701- Prioritises excitement over accuracy
702- Mimics retail trading apps
703 
704---
705 
706# Internal Motto
707 
708The market is not a prediction problem.
709 
710It is a probability distribution.
711 
712Everything in OutputLens should reinforce that idea.
713