| Positioning |
Tagline: "The explainable cleaning layer for pandas — decision-preserving data hygiene." |
README.md:7 |
"Decision-preserving data hygiene" is abstract jargon; doesn't highlight Polars or explain what the tool does in 10s. |
High drop-off from search & GitHub discovery. |
Low |
P0 |
Rewrite to: "Automated, explainable data cleaning for pandas and Polars — repair messy tabular data safely and see exactly what changed." |
| Positioning |
README hero lacks 10-second category mental model. |
README.md:26-38 |
Visitors don't immediately know how FreshData relates to Profilers vs Validators vs ML quality tools. |
Confusion about whether FreshData replaces pandas, Great Expectations, or ydata-profiling. |
Low |
P0 |
Add comparison matrix: Profilers (describe), Validators (test rules), ML-DQ (detect issues), FreshData (safely repair & explain). |
| Positioning |
No before/after visual demonstration. |
README.md:91-109 |
Current quickstart shows only a summary text without showing the messy input DataFrame and resulting output. |
Visitors cannot visualize the transformation or trust the result without running code. |
Low |
P0 |
Insert a compact, tabular Before $\rightarrow$ Detection $\rightarrow$ Decision $\rightarrow$ Repair $\rightarrow$ Audit block. |
| Onboarding |
Package naming mismatch: PyPI is freshdata-cleaner, import is freshdata. |
pyproject.toml:7-9 |
Users typing pip install freshdata fail or get wrong package; README warning is buried under install code block. |
Direct drop-off during first onboarding step. |
Low |
P0 |
Place high-visibility installation callout banner at the very top of README and docs. |
| Onboarding |
First-time contributor path requires reading full architecture. |
CONTRIBUTING.md:11-12, docs/community/first-pr.md
|
first-pr.md is an index of labels rather than a step-by-step tutorial (clone $\rightarrow$ venv $\rightarrow$ test $\rightarrow$ edit $\rightarrow$ PR). |
First-time contributors hesitate to take on issues. |
Medium |
P1 |
Create docs/contributing/first-contribution.md with a zero-friction, copy-paste workflow. |
| Discoverability |
GitHub Topics on repo are minimal/unoptimized. |
GitHub metadata & pyproject.toml:18-35
|
Repository is not ranking for high-intent search terms like data-cleaning, missing-values, data-quality, polars. |
Low organic GitHub search discovery. |
Low |
P0 |
Update GitHub repository topics with 15 developer search intent keywords (documented in admin-actions.md). |
| Discoverability |
No problem-based searchable cookbook. |
docs/ directory |
Documentation is organized by library subpackage rather than developer search queries. |
Developers searching "how to handle missing values pandas" do not land on FreshData. |
Medium |
P1 |
Build docs/cookbook/ with 7+ search-intent-focused problem/code/output guides. |
| Community |
Missing issue templates for integrations and benchmarks. |
.github/ISSUE_TEMPLATE/ |
Only bug_report.yml, feature_request.yml, and documentation.yml exist. No structured way to report benchmarks or request ecosystem integrations. |
Reduced contributor engagement on performance and ecosystem growth. |
Low |
P1 |
Add integration_request.yml and benchmark_result.yml issue forms. |
| Community |
PR template lacks performance and compatibility impact prompts. |
.github/pull_request_template.md |
PR template does not prompt contributors to document performance impact, backward compatibility, or docs updates. |
Review overhead for maintainers; accidental performance regressions. |
Low |
P1 |
Update PR template with structured questions (Why?, How tested?, Performance impact?, Docs updated?). |
| Community |
Contributor roadmap references merged/closed issues. |
docs/community/contributor-roadmap.md:34,88-92,107 |
Mentions clean_csv (#19), pyjanitor (#9), duckdb out-of-core (#52, #53), which are already merged. |
Contributors waste time investigating already-solved tasks or lose confidence in roadmap. |
Medium |
P1 |
Overhaul contributor-roadmap.md with 10+ fresh, verified open contributor tasks across Level 1, 2, and 3. |
| Proof & Safety |
Safety invariants (refusal to touch IDs, target columns) not demonstrated visibly. |
README.md, benchmarks/
|
Users fear automated cleaners will corrupt primary keys, leak target labels, or silently invent fake data. |
Adoption resistance in production environments. |
Medium |
P0 |
Add "Safety / Trust Proof" section with concrete examples of what FreshData explicitly refuses to alter. |
| Proof & Safety |
Benchmark README lacks execution commands and environment details. |
benchmarks/README.md |
Benchmarks are mentioned, but reproducibility steps and hardware requirements are brief. |
Developers doubt performance claims without clear local reproduction commands. |
Medium |
P1 |
Overhaul benchmarks/README.md documenting datasets, 9 standardized metrics, runner commands, and limitations. |
| Examples |
Flagship examples in examples/ are fragmented and lack numbered consistency. |
examples/ directory |
Missing 01_csv_cleaning.py and 03_duplicate_detection.py; integrations are scattered. |
Inconsistent developer trial experience. |
Medium |
P1 |
Standardize examples/01 to 05 and add dedicated examples/integrations/ recipes. |
| Distribution |
No structured developer marketing or launch materials. |
Codebase root |
No drafted social posts, demo scripts, blog post outlines, or launch checklists. |
Inability to launch a coordinated developer advocacy push on HN, Reddit, Twitter/X, and PyData. |
Medium |
P1 |
Create marketing/ directory containing 6 ready-to-publish assets and a community release cadence. |
| Metrics |
No defined framework for tracking adoption and contributor velocity. |
Project documentation |
Growth is measured only by vanity star counts rather than the activation funnel (Discovery $\rightarrow$ Activation $\rightarrow$ Contribution). |
Misaligned maintainer priorities. |
Low |
P1 |
Create docs/growth/metrics.md with explicit 30-day, 90-day, and 12-month traction milestones. |