agnes-the-ai-analyst/docs/archive/superpowers/plans/2026-04-09-dead-code-cleanup.md

Dead Code & Legacy Artifact Cleanup

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Remove 17 dead files, fix broken Makefile, and clean up legacy artifacts that survived the v1→v2 migration.

Architecture: Pure deletion + one Makefile rewrite. No functional changes — only removing code/files that are never imported, referenced, or executed.

Tech Stack: git rm, pytest

Source: Deep audit of all tracked files with grep-verified zero-reference confirmation (2026-04-09).

---

Task 1: Remove dead scripts

These scripts have zero references anywhere in the codebase.

Files to delete:

• scripts/collect_session.py — unused SessionEnd hook

• scripts/generate_user_sync_configs.py — replaced by DuckDB API

• scripts/standalone_profiler.py — replaced by src/profiler.py

• scripts/remote_query.sh — references non-existent module

• scripts/update.sh — calls src.data_sync and docs/data_description.md (both gone)

• scripts/setup_views.sh — depends on deleted sync_data.sh

• scripts/test_sync.sh — rsync diagnostics for resolved Issue #197

• scripts/activate_venv.sh — Docker uses direct venv paths

• scripts/backfill_gap.sh — one-time Jira backfill with hardcoded issue ranges

• scripts/sync_config_template.yaml — v1 sync config template

• Step 1: Delete all dead scripts

git rm scripts/collect_session.py \
      scripts/generate_user_sync_configs.py \
      scripts/standalone_profiler.py \
      scripts/remote_query.sh \
      scripts/update.sh \
      scripts/setup_views.sh \
      scripts/test_sync.sh \
      scripts/activate_venv.sh \
      scripts/backfill_gap.sh \
      scripts/sync_config_template.yaml

• Step 2: Run tests

Run: pytest tests/ -q --tb=short Expected: All 654 pass (none of these scripts are imported by tests)

• Step 3: Commit

git commit -m "chore: remove 10 dead scripts from v1 architecture"

---

Task 2: Remove legacy config example and root artifacts

Files to delete:

• config/data_description.md.example — v1 markdown-based table config, replaced by DuckDB table_registry
• llms.txt — describes v1 modules (src/data_sync.py, webapp/app.py, etc.) that don't exist

Note on data_description.md: src/profiler.py still references docs/data_description.md (line 95) but handles its absence gracefully (logs warning, skips). The .example file is just a template — removing it doesn't affect runtime.

• Step 1: Delete files

git rm config/data_description.md.example llms.txt

• Step 2: Run tests

Run: pytest tests/ -q --tb=short Expected: All pass

• Step 3: Commit

git commit -m "chore: remove legacy data_description.md.example and outdated llms.txt"

---

Task 3: Remove completed planning docs from dev_docs

These are implementation plans for features that are done.

Files to delete:

• dev_docs/plan-rsync-fix.md — rsync fix (Issue #197, resolved)

• dev_docs/plan_parquet_types_fix.md — parquet type fix (Issues #185-187, resolved)

• dev_docs/plan-corporate-memory.md — corporate memory governance (fully implemented)

• Step 1: Delete files

git rm dev_docs/plan-rsync-fix.md \
      dev_docs/plan_parquet_types_fix.md \
      dev_docs/plan-corporate-memory.md

• Step 2: Commit

git commit -m "chore: remove completed planning docs (rsync fix, parquet types, corporate memory)"

---

Task 4: Remove unused notification examples

examples/notifications/ contains 3 Python scripts for a notification feature that was never built.

Files to delete:

• examples/notifications/data_freshness.py

• examples/notifications/metric_report.py

• examples/notifications/revenue_drop.py

• Step 1: Check if examples/ has anything else

git ls-files examples/

If only these 3 files, delete the entire directory.

• Step 2: Delete

git rm -r examples/

• Step 3: Commit

git commit -m "chore: remove unused notification examples (feature not implemented)"

---

Task 5: Fix or replace broken Makefile

The validate-config target imports src.config.Config which doesn't exist. The Makefile also references .venv/bin/python (not Docker).

File: Makefile

• Step 1: Rewrite Makefile

Replace entire content with a minimal, working version:

# Agnes AI Data Analyst — Development Makefile

.PHONY: help test lint dev docker

help:
	@echo "Available targets:"
	@echo "  make test     Run test suite"
	@echo "  make dev      Start FastAPI dev server"
	@echo "  make docker   Build and start Docker Compose"
	@echo "  make lint     Run ruff linter (if installed)"

test:
	pytest tests/ -v --tb=short

dev:
	uvicorn app.main:app --reload

docker:
	docker compose up --build

lint:
	@ruff check . 2>/dev/null || echo "ruff not installed: pip install ruff"

• Step 2: Run make test

Run: make test Expected: All tests pass

• Step 3: Commit

git add Makefile
git commit -m "fix: rewrite Makefile — remove broken validate-config, add working targets"

---

Task 6: Update scripts/README.md

After deleting 10 scripts, the README should reflect what's left.

File: scripts/README.md

• Step 1: Rewrite scripts/README.md

# Scripts

Utility and migration scripts for Agnes AI Data Analyst.

## Active Scripts

| Script | Purpose |
|--------|---------|
| `generate_sample_data.py` | Generate sample data for development/demo |
| `duckdb_manager.py` | DuckDB database management utilities |
| `init.sh` | Initial server setup (install deps, create dirs) |

## Migration Scripts (one-time use)

| Script | Purpose |
|--------|---------|
| `migrate_json_to_duckdb.py` | Migrate v1 JSON state files to DuckDB |
| `migrate_parquets_to_extracts.py` | Migrate v1 parquet layout to extract.duckdb |
| `migrate_registry_to_duckdb.py` | Migrate v1 table registry to DuckDB |

• Step 2: Commit

git add scripts/README.md
git commit -m "docs: update scripts/README.md after dead script cleanup"

---

Execution Order

All tasks are independent except Task 6 (depends on Task 1).

Recommended: run sequentially (Task 1-6) for clean git history.

Verification after all tasks:

# Tests pass
pytest tests/ -v --tb=short

# No broken imports
python -c "from app.main import create_app; print('OK')"

# Makefile works
make test

Summary

Action	Files	Lines removed (est.)
Dead scripts	10 files	~800
Legacy config + llms.txt	2 files	~250
Completed plans	3 files	~300
Notification examples	3 files	~150
Makefile rewrite	1 file	~60 (replaced)
scripts/README.md	1 file	updated
Total	19 files removed, 2 rewritten	~1,500 lines