Menu
Component skill for creating effective visualizations (terminal-based and image-based) in DataPeeker analysis sessions
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Use when working in a project that has a `.agents/` directory or when the user asks about Conway Architecture, the conway-architecture plugin, domain agents, owned_paths enforcement, or how to coordinate a persistent subagent team that shadows the application's architecture
Use when reading or writing OST (Outcome / Strategy / Tactic) graph data in the `agents` TypeDB database - covers the falsifiability rubric, the three-layer discipline, ID conventions, lifecycle transitions, and the structured Task fields that replace generic descriptions
Use when interacting with a TypeDB 3.x database via the typedb MCP tools (typedb-query, typedb-database_schema, etc.) - covers schema-first workflow, transaction types, TypeQL 3.x syntax (which differs materially from 2.x), and the most common failure modes
Use when analyzing another branch's iteration journals to extract findings, decisions, and insights from divergent work
Use when user wants detailed status report for single autonomy branch including iteration timeline and metrics progression
Use when saving current iteration progress mid-conversation, before context compaction, or at interim pause points
Based on SOC occupation classification
| name | creating-visualizations |
| description | Component skill for creating effective visualizations (terminal-based and image-based) in DataPeeker analysis sessions |
This component skill guides creation of clear, effective visualizations for analytics documentation. Use it when:
Supports two approaches:
interpreting-results skill)Create a TodoWrite checklist for the 4-phase visualization process:
Phase 1: Choose Visualization Type
Phase 2: Structure Data for Display
Phase 3: Create Visualization
Phase 4: Annotate with Context
Mark each phase as you complete it. Include visualizations in numbered markdown files alongside queries and interpretations.
Goal: Select the right visualization format for your data and communication goal.
Ask these questions in order:
1. What type of data am I visualizing?
2. What is my primary communication goal?
3. How many data points?
4. Who is the audience?
DataPeeker supports two complementary approaches:
Choose based on:
Goal: Organize and format data for effective visualization.
Before creating visualization:
1. Sort appropriately:
For ranked data:
- Sort by the metric you want to emphasize (descending for "top N")
- Consider: Alphabetical only if order doesn't matter
For time series:
- Sort chronologically (oldest to newest, or newest first if recent matters)
For categorical:
- Sort by frequency, magnitude, or logical grouping
- Avoid: Random or database-default ordering
2. Round to appropriate precision:
Examples:
- Revenue: Round to thousands or whole dollars (not $1,234.56789)
- Percentages: 1-2 decimal places (14.3%, not 14.285714%)
- Counts: Whole numbers only (1,234 not 1234.0)
- Ratios: 2-3 significant figures (2.4x not 2.3567x)
Rule: Show precision that matches the certainty of your data
3. Add calculated columns:
Useful additions:
- Percentage of total
- Difference from average/baseline
- Rank or percentile
- Running totals or moving averages
- Year-over-year change
4. Consider grouping:
For large datasets:
- Show Top N + "Other" row
- Group by logical categories
- Use ranges/buckets for continuous data
- Separate outliers from main distribution
5. Format for readability:
Best practices:
- Add thousand separators (1,234 not 1234)
- Use consistent decimal places within columns
- Align numbers right, text left
- Include units in headers ($, %, units)
Goal: Build the actual visualization using appropriate format and tools.
DataPeeker supports two complementary visualization approaches:
Use for:
Available formats:
→ See terminal-formats.md for implementation
Use for:
Available formats:
→ See image-formats.md for implementation
Use Terminal formats when:
Use Image formats when:
Can use both:
MANDATORY: All visualizations (bar charts, line plots, histograms, sparklines, scatter plots) MUST use established visualization tools. NEVER create these manually.
✅ ALLOWED - Manual Creation:
❌ PROHIBITED - Manual Creation:
📄 For visualization implementations, use these guides:
This document provides:
The rule: If it visualizes relative magnitudes, trends, or distributions → USE A TOOL. If it's exact numbers in a table → Manual creation is fine.
This document provides:
formats/ directory:
Goal: Add context and guidance so visualization is self-explanatory.
Every visualization should include:
1. Title/Caption:
## [Clear, descriptive title that states what is being shown]
Example:
✓ Good: "Monthly Revenue by Product Category (Jan-Dec 2024)"
✗ Bad: "Revenue Chart"
2. Data source and date:
**Data source:** analytics.db, orders table
**Time period:** Q4 2024 (Oct 1 - Dec 31)
**Last updated:** 2025-11-18
3. Key takeaway (above or below visualization):
**Key Finding:** Electronics drove 42.5% of Q4 revenue despite representing
only 15% of order volume, indicating premium product performance.
4. Units and scale:
- Include $ or % symbols
- Clarify if values are in thousands: ($000s)
- Note if values are indexed or normalized
- Specify timezone for timestamps
5. Context for interpretation:
**Context notes:**
- Q4 includes Black Friday/Cyber Monday (Nov 24-27)
- New product line launched Oct 15, affecting Electronics category
- Shipping delays in December may have suppressed orders
6. Limitations and caveats:
**Caveats:**
- Data excludes returns and cancellations
- International orders converted to USD at average quarterly exchange rate
- First week of October had incomplete data due to system migration
7. What to look for:
**What to notice:**
- Electronics peak in November (holiday season)
- Clothing shows consistent decline (investigate seasonality)
- Sports category smallest but growing fastest (+45% QoQ)
Choose format based on communication goal, not convenience
Make visualizations self-contained
Use consistent formatting within analysis
Highlight what matters
Test readability
Layer detail progressively
Combine formats when helpful
Don't create visualizations for their own sake
Don't use excessive precision
Don't hide important caveats
Don't use misleading scales
Don't over-format
Don't assume reader knows context
Don't forget the "so what?"
## Impact of Pricing Change (Oct 15, 2024)
### Before Pricing Change (Oct 1-14)
- Average Order Value: **$145.67**
- Daily Orders: **234**
- Daily Revenue: **$34,087**
### After Pricing Change (Oct 15-31)
- Average Order Value: **$127.23** (↓ $18.44, -12.7%)
- Daily Orders: **289** (↑ 55, +23.5%)
- Daily Revenue: **$36,769** (↑ $2,682, +7.9%)
**Net effect:** Lower prices increased volume enough to grow total revenue.
⚠️ Use plotext to create histograms - DO NOT create manually
Show distribution with summary statistics:
import plotext as plt
import statistics
# Customer LTV values from query
ltv_values = [423, 687, 892, 2145, ...] # Your data
plt.hist(ltv_values, bins=7)
plt.title('Customer Lifetime Value Distribution')
plt.xlabel('Customer LTV ($)')
plt.ylabel('Number of Customers')
plt.show()
# Show summary statistics
print(f"\nSummary Statistics:")
print(f"Median LTV: ${statistics.median(ltv_values):,.0f}")
print(f"Mean LTV: ${statistics.mean(ltv_values):,.0f}")
print(f"75th percentile: ${statistics.quantiles(ltv_values, n=4)[2]:,.0f}")
See terminal-formats.md Format 4 for complete histogram examples.
✅ Tables are fine for exact values, use plotext/termgraph for visual breakdown
## Customer Segmentation by Purchase Behavior
| Segment | Customers | Avg Orders | Avg LTV | % of Revenue | Strategy |
|:----------------|----------:|-----------:|--------:|-------------:|:--------------|
| **Champions** | 234 | 18.3 | $2,145 | 18.2% | VIP treatment |
| **Loyal** | 1,456 | 8.7 | $892 | 47.3% | Retain & grow |
| **Potential** | 3,678 | 2.4 | $287 | 38.5% | Nurture |
| **At Risk** | 892 | 1.2 | $156 | 5.1% | Win-back |
| **Lost** | 2,134 | 1.0 | $87 | 6.8% | Low priority |
**Key insight:** Top two segments (Champions + Loyal) are only 18% of customer
base but generate 66% of revenue. These 1,690 customers should receive majority
of retention investment.
For visual breakdown, use plotext:
import plotext as plt
segments = ['Champions', 'Loyal', 'Potential', 'At Risk', 'Lost']
revenue = [501030, 1299552, 1055586, 139152, 185658]
plt.simple_bar(segments, revenue, title='Revenue by Customer Segment')
plt.xlabel('Segment')
plt.ylabel('Revenue ($)')
plt.show()
See terminal-formats.md Format 2 for complete bar chart examples.
⚠️ Use plotext or asciichartpy - DO NOT create manually
import plotext as plt
months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec']
revenue = [1.0, 1.1, 1.2, 1.3, 1.4, 1.5,
1.5, 1.6, 1.7, 1.7, 1.9, 2.0] # Revenue in millions
plt.plot(months, revenue)
plt.title('Monthly Revenue Trend with Key Events')
plt.xlabel('Month')
plt.ylabel('Revenue ($M)')
plt.show()
print("\nKey Events:")
print("- Oct 1: Q4 begins, seasonal uptick expected")
print("- Oct 15: Pricing change (-10% on popular items)")
print("- Nov 1: New product line launched (premium segment)")
print("- Nov 24-27: Black Friday/Cyber Monday surge")
print("\nAnalysis: Revenue growth accelerated after new product launch (Nov),")
print("suggesting demand for premium options. Pricing change impact unclear due to")
print("seasonal overlap.")
See terminal-formats.md Format 8 for complete line plot examples.
✅ Tables for exact values, use plotext for visualization
## Purchase Funnel Conversion Rates
| Step | Count | Conversion | Drop-off | Notes |
|:------------------|--------:|-----------:|---------:|:------|
| 1. Site Visitors | 100,000 | 100.0% | — | |
| 2. Product Viewers| 45,000 | 45.0% | 55.0% | High bounce rate |
| 3. Add to Cart | 12,000 | 26.7% | 73.3% | |
| 4. Begin Checkout | 8,500 | 70.8% | 29.2% | Cart abandonment |
| 5. Complete | 3,200 | 37.6% | 62.4% | Payment issues? |
**Overall Conversion:** 3.2%
**Problem areas:**
1. **Bounce rate (55%):** Half of visitors leave without viewing products
- Action: Improve landing page, clearer value proposition
2. **Cart abandonment (29%):** Losing 3,500 potential customers at checkout
- Action: Simplify checkout, add progress indicator
3. **Checkout failure (62%):** Massive drop-off at payment
- Action: URGENT — investigate payment gateway, error messages
**Quick win:** Fixing checkout issues could 2.6x conversion (3.2% → 8.4%)
For funnel visualization, use plotext:
import plotext as plt
steps = ['Visitors', 'Viewers', 'Cart', 'Checkout', 'Purchase']
counts = [100000, 45000, 12000, 8500, 3200]
plt.simple_bar(steps, counts, title='Purchase Funnel')
plt.xlabel('Funnel Step')
plt.ylabel('Count')
plt.show()
See terminal-formats.md Format 2 for complete bar chart examples.
Process skills reference this component skill with:
Use the `creating-visualizations` component skill to present query results
visually, making patterns and insights more accessible to stakeholders.
When creating visualizations during analysis:
This ensures analysis outputs are not just technically correct but also effectively communicated and actionable.
Visualize when:
Use tables when:
Use both when:
Before finalizing any visualization, verify:
If any checklist item fails, revise before including in analysis.