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

Go filenames consistency design

Context

The repository has inconsistent .go filename semantics in multiple areas (domain-oriented names, endpoint/history-oriented names, mixed singular/plural forms). This slows code navigation because filenames do not consistently communicate data dimension or responsibility.

Goal: refactor .go filenames across the whole repository to a consistent naming model, and align declaration placement with filename responsibility, without changing runtime behavior.

Scope

Applies to all .go files in the repository.

In scope:

• Rename .go files to consistent, responsibility-first names.
• Mechanical updates required by rename/move.
• Move declarations between files when needed so file responsibility is clear.

Out of scope:

• Any behavior or logic changes.
• Non-.go files.
• New feature work.

Requirements

1. .go filename naming is consistent across the repository.
2. Filenames follow responsibility-first conventions:
   • data-dimension names where applicable (spot_*, futures_*, etc.)
   • pluralized collection-oriented files (*_pairs.go, *_prices.go)
   • avoid endpoint/history-oriented naming that obscures responsibility.
3. Declarations in each file match filename responsibility.
4. No public/package behavior change.
5. Resulting PR remains reviewable by grouping changes mechanically and keeping logic untouched.

Design

Naming model

Use a responsibility-first naming model for all .go files:

• A reader should infer the primary responsibility from filename alone.
• Prefer domain/data-dimension names over transport/implementation-history names.
• Use consistent singular/plural convention based on file content (entity vs collection).

Refactor mechanics

1. Inventory .go files by package and classify naming inconsistencies.
2. Define target filename map package-by-package.
3. Rename files with git-aware rename operations.
4. Move declarations when file content does not match filename responsibility.
5. Keep signatures and bodies unchanged.
6. Apply only mechanical reference/import updates required by moves.

Execution strategy for reviewability

• Use focused commits by package or subsystem.
• Keep each commit behavior-neutral.
• Separate any necessary declaration moves from broad rename waves when this improves diff readability.

Error handling and behavior

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

Testing and verification

1. Run project tests after each major package/subsystem batch.
2. Run full project test command before PR.
3. Confirm no functional diff beyond rename/move/mechanical updates.
4. Final check: each renamed file contains declarations aligned with its responsibility.

Risks and mitigations

• Risk: accidental behavior change while moving declarations.
  • Mitigation: keep signatures/bodies unchanged and validate with tests per batch.
• Risk: review noise from repo-wide scope.
  • Mitigation: package-grouped commits, strict mechanical-only edits, and explicit PR summary.
• Risk: large PR becomes hard to review.
  • Mitigation: preserve commit structure and provide a clear rename map in PR description.

Success criteria

• .go filenames are consistent and responsibility-first across the repo.
• Declarations in each file align with filename responsibility.
• Tests pass with no behavior regression.
• PR is understandable through structured, behavior-neutral commits.