1111 * <p>Each category maps to a domain of database health/performance that Brain
1212 * monitors. Persona tags determine which categories are prioritized in a user's
1313 * digest.
14+ *
15+ * <h3>Concrete Persona → Signal Mapping</h3>
16+ * <ul>
17+ * <li><b>DBA:</b> idle-in-txn, locks, autovacuum, bloat, join_collapse_limit cliffs,
18+ * plan regressions, config drift</li>
19+ * <li><b>APP_ENG:</b> query/ORM patterns, ACCESS EXCLUSIVE risk (DDL blocking),
20+ * schema changes affecting their tables, slow queries in their code paths</li>
21+ * <li><b>DATA_ENG:</b> ETL load patterns, schema/comment gaps, semantic drift,
22+ * growth anomalies, pipeline-affecting changes</li>
23+ * <li><b>EXEC:</b> cost/capacity trends, top regression, risk summary (3 bullets max)</li>
24+ * </ul>
1425 */
1526public enum InsightCategory {
1627
1728 /**
18- * Query performance issues: slow queries, plan regressions, lock contention .
19- * High relevance for DBA and APP_ENG personas .
29+ * Query performance issues: slow queries, plan regressions, ORM patterns .
30+ * DBA sees plan-level details; APP_ENG sees query patterns from their code .
2031 */
2132 QUERY_PERFORMANCE ("Query Performance" , 30 ),
2233
34+ /**
35+ * Lock and concurrency: idle-in-txn, lock waits, ACCESS EXCLUSIVE blocks.
36+ * Critical for DBA (operational); APP_ENG cares about DDL blocking risk.
37+ */
38+ LOCK_CONCURRENCY ("Lock & Concurrency" , 28 ),
39+
2340 /**
2441 * Index recommendations: missing indexes, unused indexes, ROI candidates.
2542 * High relevance for DBA personas.
@@ -28,39 +45,39 @@ public enum InsightCategory {
2845
2946 /**
3047 * Schema changes: new tables/columns, dropped objects, breaking changes.
31- * High relevance for APP_ENG and DATA_ENG personas .
48+ * APP_ENG: migration/DDL risk. DATA_ENG: semantic drift .
3249 */
3350 SCHEMA_CHANGES ("Schema Changes" , 20 ),
3451
3552 /**
36- * Table growth anomalies: unexpected size increases, row spikes.
37- * Relevant for DBA and DATA_ENG personas .
53+ * Table growth anomalies: unexpected size increases, row spikes, bloat .
54+ * DBA: capacity/vacuum. DATA_ENG: ETL load patterns .
3855 */
3956 GROWTH_ANOMALIES ("Growth Anomalies" , 20 ),
4057
4158 /**
4259 * Brain learning progress: workload changes, config drift, new patterns.
43- * Relevant for DBA personas who care about tuning .
60+ * DBA: tuning opportunities. DATA_ENG: workload characteristic shifts .
4461 */
4562 BRAIN_INTELLIGENCE ("Brain Intelligence" , 15 ),
4663
4764 /**
48- * Configuration and tuning: experiment results, knob recommendations.
49- * High relevance for DBA personas.
65+ * Configuration and tuning: experiment results, knob recommendations,
66+ * join_collapse_limit cliffs. Primary for DBA personas.
5067 */
51- CONFIG_TUNING ("Config & Tuning" , 20 ),
68+ CONFIG_TUNING ("Config & Tuning" , 22 ),
5269
5370 /**
54- * Documentation gaps: tables/columns lacking descriptions.
55- * High relevance for DATA_ENG personas.
71+ * Documentation gaps: tables/columns lacking descriptions, semantic drift .
72+ * High relevance for DATA_ENG personas building BI/analytics .
5673 */
57- DOCUMENTATION_GAPS ("Documentation Gaps" , 10 ),
74+ DOCUMENTATION_GAPS ("Documentation Gaps" , 12 ),
5875
5976 /**
60- * Cost and capacity: spend trends, capacity forecasts.
61- * High relevance for EXEC personas.
77+ * Cost and capacity: spend trends, capacity forecasts, storage waste .
78+ * High relevance for EXEC personas (short summaries) .
6279 */
63- COST_CAPACITY ("Cost & Capacity" , 15 ),
80+ COST_CAPACITY ("Cost & Capacity" , 18 ),
6481
6582 /**
6683 * General alerts from playbooks or system monitoring.
@@ -92,56 +109,76 @@ public int getBaseWeight() {
92109 *
93110 * <p>Returns a multiplier (0.5 to 2.0) that adjusts the category's
94111 * importance based on what the persona cares about.
112+ *
113+ * <h4>Concrete Mapping Rationale</h4>
114+ * <ul>
115+ * <li><b>DBA:</b> Lock/concurrency, query performance, config tuning are operational
116+ * priorities. Idle-in-txn, vacuum, bloat, join_collapse_limit cliffs live here.</li>
117+ * <li><b>APP_ENG:</b> Schema changes (DDL/migration risk), query patterns from their
118+ * code, ACCESS EXCLUSIVE blocking risk matter most.</li>
119+ * <li><b>DATA_ENG:</b> Documentation gaps (semantic drift), schema changes (ETL breaks),
120+ * growth anomalies (load patterns) are primary.</li>
121+ * <li><b>EXEC:</b> Cost/capacity for budget, system alerts for risk, growth for
122+ * capacity planning. Short, actionable.</li>
123+ * </ul>
95124 */
96125 public double getPersonaMultiplier (PersonaTag persona ) {
97126 if (persona == null ) {
98127 return 1.0 ;
99128 }
100129
101130 return switch (persona ) {
131+ // DBA: idle-in-txn, locks, autovacuum, bloat, join_collapse_limit, plan regressions
102132 case DBA -> switch (this ) {
103- case QUERY_PERFORMANCE -> 2.0 ;
104- case INDEX_RECOMMENDATIONS -> 2.0 ;
105- case CONFIG_TUNING -> 1.8 ;
106- case BRAIN_INTELLIGENCE -> 1.5 ;
107- case GROWTH_ANOMALIES -> 1.3 ;
133+ case LOCK_CONCURRENCY -> 2.0 ; // idle-in-txn, lock waits, blocking
134+ case QUERY_PERFORMANCE -> 2.0 ; // plan regressions, slow queries
135+ case INDEX_RECOMMENDATIONS -> 1.8 ; // index ROI
136+ case CONFIG_TUNING -> 1.8 ; // join_collapse_limit, autovacuum tuning
137+ case GROWTH_ANOMALIES -> 1.5 ; // bloat, vacuum need
138+ case BRAIN_INTELLIGENCE -> 1.3 ; // workload shifts
108139 case SYSTEM_ALERTS -> 1.2 ;
109- case SCHEMA_CHANGES -> 0.8 ;
110- case DOCUMENTATION_GAPS -> 0.5 ;
111- case COST_CAPACITY -> 0.7 ;
140+ case SCHEMA_CHANGES -> 0.7 ; // less operational
141+ case DOCUMENTATION_GAPS -> 0.4 ;
142+ case COST_CAPACITY -> 0.6 ;
112143 };
144+ // APP_ENG: query/ORM patterns, DDL blocking risk, schema changes affecting code
113145 case APP_ENG -> switch (this ) {
114- case QUERY_PERFORMANCE -> 1.8 ;
115- case SCHEMA_CHANGES -> 2.0 ;
146+ case SCHEMA_CHANGES -> 2.0 ; // migrations, DDL affecting their tables
147+ case QUERY_PERFORMANCE -> 1.8 ; // slow queries from their code
148+ case LOCK_CONCURRENCY -> 1.6 ; // ACCESS EXCLUSIVE risk during deploys
116149 case INDEX_RECOMMENDATIONS -> 1.2 ;
117- case SYSTEM_ALERTS -> 1.3 ;
118- case GROWTH_ANOMALIES -> 0.8 ;
119- case BRAIN_INTELLIGENCE -> 0.6 ;
120- case CONFIG_TUNING -> 0.5 ;
150+ case SYSTEM_ALERTS -> 1.2 ;
121151 case DOCUMENTATION_GAPS -> 1.0 ;
122- case COST_CAPACITY -> 0.5 ;
152+ case GROWTH_ANOMALIES -> 0.7 ;
153+ case BRAIN_INTELLIGENCE -> 0.5 ;
154+ case CONFIG_TUNING -> 0.4 ;
155+ case COST_CAPACITY -> 0.4 ;
123156 };
157+ // DATA_ENG: ETL patterns, schema/comment gaps, semantic drift, pipeline health
124158 case DATA_ENG -> switch (this ) {
125- case SCHEMA_CHANGES -> 1.8 ;
126- case DOCUMENTATION_GAPS -> 2.0 ;
127- case QUERY_PERFORMANCE -> 1.3 ;
128- case GROWTH_ANOMALIES -> 1.5 ;
129- case INDEX_RECOMMENDATIONS -> 1.0 ;
130- case BRAIN_INTELLIGENCE -> 0.8 ;
159+ case DOCUMENTATION_GAPS -> 2.0 ; // semantic drift, BI quality
160+ case SCHEMA_CHANGES -> 1.8 ; // ETL/pipeline breaks
161+ case GROWTH_ANOMALIES -> 1.6 ; // load patterns, capacity
162+ case QUERY_PERFORMANCE -> 1.3 ; // BI query failures
163+ case BRAIN_INTELLIGENCE -> 1.0 ; // workload shifts
164+ case INDEX_RECOMMENDATIONS -> 0.9 ;
165+ case SYSTEM_ALERTS -> 0.9 ;
166+ case LOCK_CONCURRENCY -> 0.6 ;
131167 case CONFIG_TUNING -> 0.5 ;
132- case SYSTEM_ALERTS -> 1.0 ;
133- case COST_CAPACITY -> 0.8 ;
168+ case COST_CAPACITY -> 0.7 ;
134169 };
170+ // EXEC: cost/capacity/risk summaries (short, 3 bullets max)
135171 case EXEC -> switch (this ) {
136- case COST_CAPACITY -> 2.0 ;
137- case SYSTEM_ALERTS -> 1.5 ;
138- case QUERY_PERFORMANCE -> 1.2 ;
139- case GROWTH_ANOMALIES -> 1.3 ;
140- case INDEX_RECOMMENDATIONS -> 0.5 ;
141- case SCHEMA_CHANGES -> 0.5 ;
142- case BRAIN_INTELLIGENCE -> 0.5 ;
143- case CONFIG_TUNING -> 0.5 ;
144- case DOCUMENTATION_GAPS -> 0.3 ;
172+ case COST_CAPACITY -> 2.0 ; // budget, spend trends
173+ case SYSTEM_ALERTS -> 1.6 ; // risk awareness
174+ case GROWTH_ANOMALIES -> 1.4 ; // capacity planning
175+ case QUERY_PERFORMANCE -> 1.1 ; // top regression headline
176+ case LOCK_CONCURRENCY -> 0.8 ; // only if critical
177+ case INDEX_RECOMMENDATIONS -> 0.4 ;
178+ case SCHEMA_CHANGES -> 0.4 ;
179+ case BRAIN_INTELLIGENCE -> 0.4 ;
180+ case CONFIG_TUNING -> 0.4 ;
181+ case DOCUMENTATION_GAPS -> 0.2 ;
145182 };
146183 };
147184 }
0 commit comments