foxhunt/docs/plans/2026-03-01-workspace-cleanup-design.md

Workspace Cleanup — Design

Date: 2026-03-01 Scope: Delete stale docs, create/update READMEs, delete plan docs, clean worktrees

Problem

92 scattered .md files (test reports, quick-starts, analyses) across crates/services. 137 historical plan docs in docs/plans/. 13 crates/services missing README.md. 12 crates missing lib.rs doc comments. 3 tracked .serena tool artifacts. 4 stale worktrees (~13GB).

Phase 1: Delete Stale Docs

Scattered .md files to delete (92 total)

crates/data/ (1):

• tests/EDGE_CASE_FINDINGS.md

crates/database/ (1):

• QUICK_START.md

crates/ml/ (18):

• PERFORMANCE_TRACKING.md, MAMBA2_CONFIGURATION_FIX.md, PERFORMANCE_QUICK_START.md
• MAMBA2_DIMENSION_ANALYSIS.md, QUICKSTART_GPU_BENCHMARK.md
• docs/codebase-cleanup/DQN_PARAMETER_CONSISTENCY_AUDIT.md
• docs/dqn_hyperopt_parameter_audit.md, docs/GPU_BENCHMARK_GUIDE.md
• docs/dqn_hyperparameters_analysis.md, docs/QAT_GRADIENT_CHECKPOINTING_WORKAROUND.md
• docs/QAT_GUIDE.md, hyperparams/README.md
• profiling_reports/TFT_INT8_MEMORY_PROFILING_GUIDE.md, profiling_reports/MEMORY_COMPARISON_CHART.md
• src/benchmark/TFT_BENCHMARK_README.md, src/checkpoint/README.md
• tests/TFT_TEST_REPORT.md, tests/MAMBA_TEST_COVERAGE.md
• trained_models/production/tft_real_data/TRAINING_REPORT.md

crates/risk/ (1):

• docs/TEST_COVERAGE_REPORT.md

crates/storage/ (1):

• tests/S3_TEST_COVERAGE.md

crates/trading_engine/ (2):

• docs/audit_trail_persistence_usage.md, docs/TEST_COVERAGE_REPORT.md

crates/trading_engine/src/types/.serena/ (3 tracked files):

• memories/types_crate_fix_progress.md (+ parent dir)

services/api_gateway/ (8):

• tests/INTEGRATION_TEST_REPORT.md, tests/RATE_LIMITER_TEST_REPORT.md
• src/metrics/README.md, tests/README.md, benches/README.md
• METRICS_DEPLOYMENT.md, METRICS_ARCHITECTURE.md, REVOCATION_CACHE_USAGE.md
• BENCHMARKS.md, ML_TRAINING_PROXY_INTEGRATION.md, RATE_LIMITER_IMPLEMENTATION.md

services/backtesting_service/ (7):

• tests/SERVICE_TESTS_REPORT.md, tests/COVERAGE_MAPPING.md
• tests/fixtures/README.md, tests/fixtures/PERFORMANCE.md
• tests/fixtures/QUICKSTART.md, tests/fixtures/ARCHITECTURE.md
• docs/DBN_LOADING_PERFORMANCE_REPORT.md
• DBN_REPOSITORY_USAGE.md, ADVANCED_QUERIES_QUICKREF.md

services/broker_gateway_service/ (5):

• DEPLOYMENT.md, MONITORING_IMPLEMENTATION.md, METRICS_QUICK_REF.md
• docs/API.md, docs/TROUBLESHOOTING.md, docs/DEPLOYMENT.md

services/ml_training_service/ (2):

• HYPERPARAMETER_TUNING.md, TRIAL_EXECUTOR_USAGE.md

services/trading_service/ (2):

• src/streaming/README.md, docs/ml_integration_design.md
• tests/common/README.md

services/trading_agent_service/ (1):

• README_TLS.md

bin/fxt/ (7):

• CONFIG_FILE_SUPPORT.md, TUNE_COMMAND_README.md
• docs/AUTHENTICATION.md, docs/ML_TRADING_COMMANDS.md, docs/USAGE.md
• tests/INTEGRATION_TEST_GUIDE.md, tests/TEST_EXECUTION_README.md

testing/ (13):

• api-gateway-load/CHEAT_SHEET.md, api-gateway-load/QUICK_START.md
• e2e/E2E_TEST_GUIDE.md
• integration/e2e_helpers/INFRASTRUCTURE_VALIDATION.md
• integration/e2e_helpers/USAGE_EXAMPLES.md
• integration/e2e_helpers/QUICKSTART.md
• integration/e2e_helpers/VALIDATION_REPORT.md
• integration/e2e_helpers/QUICK_START_INFRASTRUCTURE.md
• integration/fixtures/README.md
• service-integration/README_DBN_INTEGRATION.md

Plan docs (137)

Keep docs/plans/ as historical reference. No action needed.

Worktrees (4)

• .claude/worktrees/real-metrics-overhaul (1KB, abandoned) — delete
• .claude/worktrees/autonomous-agents (2.4GB) — delete
• .claude/worktrees/numeric-type-unification (4.2GB) — delete
• .claude/worktrees/training-deploy (6.5GB) — delete

Empty directories after deletion

Remove empty docs/, profiling_reports/, .serena/ directories left behind.

Phase 2: READMEs + Doc Comments

Missing crate READMEs (8):

config, ctrader-openapi, market-data, ml-data, model_loader, risk-data, trading-data, training_uploader

Missing service READMEs (4):

api_gateway, data_acquisition_service, trading_agent_service, tests

Missing bin README (1):

bin/fxt

Update existing READMEs (22):

All existing READMEs get refreshed with standard template.

Standard template:

# <name>
<one-line purpose>

## Key Types / API
<bullet list of primary public types or endpoints>

## Usage
<how to use this crate/service>

## Configuration
<env vars, feature flags if applicable>

lib.rs doc comments (12 crates):

Add //! <crate-name> — <purpose> to top of lib.rs for crates missing them.

Phase 3: Verify

• SQLX_OFFLINE=true cargo check --workspace
• SQLX_OFFLINE=true cargo clippy --workspace --lib -- -D warnings
• Confirm no broken doc links

Risk

Low. Only deleting .md files and creating new ones. No Rust code changes except //! doc comments (which can't break compilation).