pal-e-docs

Review: Market scanner — continuous polling of same-day games

review-1687-2026-07-02 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Depends on ldraney/kalshi-assistant #1
  • [x] Repo — ldraney/kalshi-assistant
  • [x] User Story — As the watchdog system / scan same-day markets / detect 85% threshold
  • [x] Context — Watchdog strategy background, series tickers, rate limits
  • [x] File Targets — 4 files to create
  • [x] Feature Flag — none
  • [x] Acceptance Criteria — 6 items
  • [x] Test Expectations — unit + integration tests, run command
  • [x] Constraints — Solid Queue, rate limits, 24h history
  • [x] Checklist — PR, tests, no unrelated changes
  • [x] Related — project reference
All sections present per template-issue-feature.

Traceability

  • [x] story:watchdog-trading label — Watchdog Trading
  • [x] story note verified — story-kalshi-assistant-watchdog-trading exists (active, user-story type)
  • [x] story entry verified — found in project-kalshi-assistant user-stories table
  • [x] arch:api label present
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-api for component api
  • [x] arch:app label present
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-app for component app
  • [ ] arch label mismatch — [LABEL] Story note references arch-domain-kalshi-assistant and arch-dataflow-kalshi-assistant, but board item has arch:api and arch:app. These should be reconciled.
  • [x] Forgejo issue — ldraney/kalshi-assistant#2, open

File Targets

  • [x] app/jobs/market_scanner_job.rb — to create (Solid Queue job). No app/ directory exists yet; expected since this depends on issue #1 (Rails scaffold).
  • [x] app/models/market_snapshot.rb — to create (snapshot model). Same dependency on #1.
  • [x] db/migrate/xxx_create_market_snapshots.rb — to create (migration). Same dependency on #1.
  • [x] config/market_series.yml — to create (series config). Same dependency on #1.
All file targets are files to CREATE, not modify. File paths follow Rails conventions. The repo has no Rails structure yet because the prerequisite (issue #1 — Rails scaffold) hasn't been completed. File targets are valid assuming #1 is done first.

Repo Placement

OK. Issue filed on ldraney/kalshi-assistant, Repo section says ldraney/kalshi-assistant. Single repo, no multi-repo concern.

Dependencies

  • Upstream: Depends on issue #1 (Rails scaffold + API client) — documented in Lineage. Board item #1686 is in backlog (sprint:1). This ticket is sprint:2. Correct ordering.
  • Downstream: Board item #1689 "Watchdog — auto-buy when market crosses 85% threshold" (sprint:3, issue #4) logically depends on this scanner. Not documented in this ticket's scope but is in the correct sprint order.
  • Parallel: Board item #1688 "Strategy engine — database schema" (sprint:2, issue #3) is in the same sprint. No apparent conflict — these can run in parallel once #1 is complete.

Acceptance Criteria

6 criteria, all testable by an agent:
  • [x] Background job polls — verifiable via test that job enqueues and runs
  • [x] Scans configured series — verifiable via config iteration test
  • [x] Stores snapshots with specified fields — verifiable via DB assertions
  • [x] Filters same-day/next-day — verifiable via date filtering test
  • [x] Respects rate limits — verifiable via configurable delay check
  • [x] Logs 85% threshold crossing — verifiable via log output assertion
Test expectations are reasonable: unit tests for model validations and filtering logic, integration test for full job execution. Run command rails test is standard Rails.

Blast Radius

  • New repo with no existing production code (only docs and README). Minimal blast radius.
  • Referenced docs exist: docs/api/market-data-guide.md and docs/strategy/watchdog-strategy.md both present in repo.
  • Ticker discrepancy: Issue Context lists 11 series tickers including crypto tickers (KXBTC15M, KXETH15M, KXSOL15M, KXDOGE15M, KXXRP15M, KXBNB15M, KXNEAR15M, KXHYPE15M) and KXWNBA. The market-data-guide.md only documents KXMLBGAME, KXWCGAME, KXMLB, KXNBA, KXNHL. The additional tickers in the issue are not sourced. This should be reconciled — either update the market data guide or cite the source for these tickers in the issue body.

Decomposition Assessment

  • 4 file targets across 1 repo — under the >3 files across >2 repos threshold.
  • 6 acceptance criteria — borderline exceeds the >5 threshold by 1.
  • Estimated agent work: ~5 minutes. Creating 4 tightly coupled files (model, job, migration, config) plus tests for a single feature.
The 6 AC are all aspects of a single scanner component. Decomposition would create artificial sub-tickets with heavy coupling. No decomposition needed — the borderline AC count does not warrant splitting this coherent feature.

Recommendation

  • [SCOPE] Create architecture note arch-api for the Kalshi API client component.
  • [SCOPE] Create architecture note arch-app for the application layer component.
  • [LABEL] Reconcile arch labels: story note references arch-domain-kalshi-assistant and arch-dataflow-kalshi-assistant, but board item uses arch:api and arch:app. Decide which taxonomy to use and align both.
  • [BODY] Cite source for crypto and WNBA tickers in Context section (KXBTC15M, KXETH15M, KXSOL15M, KXDOGE15M, KXXRP15M, KXBNB15M, KXNEAR15M, KXHYPE15M, KXWNBA) or update docs/api/market-data-guide.md to include them.