crypto-price-bot/docs/superpowers/specs/2026-04-27-market-filenames-data-dimension-design.md

Market filenames data-dimension design

Context

internal/data/market currently has mixed filename semantics (trading_pairs.go, future_price.go, spot_price.go, alpha_tokens.go). This slows code navigation because filenames do not consistently communicate data dimension.

Goal: refactor market package filenames to consistent data-dimension naming, and align function placement with filename responsibility, without changing runtime behavior.

Scope

Applies only to files in internal/data/market.

In scope:

• Rename files to consistent names by data dimension.
• Mechanical updates needed due to file rename/move.
• Move functions between renamed files when needed so file responsibility is clear.

Out of scope:

• Any behavior or logic changes.
• New feature work.
• Refactors outside internal/data/market except mechanical references.

Requirements

1. File naming in market package is consistent by data dimension.
2. Target filenames:
   • spot_pairs.go
   • futures_pairs.go
   • spot_prices.go
   • futures_prices.go
   • keep alpha_tokens.go
3. Function placement matches filename responsibility.
4. No public/package behavior change.
5. Resulting PR focuses on refactor readability and low review noise.

Design

Naming model

Use pluralized, data-dimension based filenames:

• *_pairs.go for symbol/pair resolution concerns.
• *_prices.go for price retrieval/processing concerns.

File-level responsibilities

• spot_pairs.go: Spot pair/symbol resolution code.
• futures_pairs.go: Futures pair/symbol resolution code.
• spot_prices.go: Spot price read/transform code.
• futures_prices.go: Futures price read/transform code.
• alpha_tokens.go: Alpha-token specific logic (unchanged file name).

Refactor mechanics

1. Rename existing files to target names using git-aware rename.
2. Inspect each renamed file for responsibility mismatch.
3. Move declarations to the matching file when mismatch exists.
4. Keep function signatures and call behavior unchanged.
5. Apply only mechanical import/reference updates if any are required.

Error handling and behavior

No new error handling paths are introduced. Existing control flow and error behavior remain unchanged.

Testing and verification

1. Run package tests for market-related code.
2. Run project test command used by repository.
3. Confirm no functional diff beyond file rename/moves.
4. Final check: each renamed file contains only code matching its data dimension.

Risks and mitigations

• Risk: accidental behavior change while moving declarations.
  • Mitigation: keep signatures/body unchanged; validate with tests.
• Risk: review noise from mixed mechanical and logic edits.
  • Mitigation: avoid logic edits entirely; keep commit focused on naming/responsibility alignment.

Success criteria

• Market package filenames follow the target naming scheme.
• Code in each file matches its filename responsibility.
• Tests pass with no behavior regression.
• PR is reviewable as a refactor-only change set.