pal-e-docs

Review: Option D sizing engine -- optimized stack with hedging

review-1690-2026-07-02 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- present (depends on #3)
  • [x] Repo -- present
  • [x] User Story -- present
  • [x] Context -- present, references docs/strategy/sizing-models.md
  • [x] File Targets -- present (2 files to create)
  • [x] Feature Flag -- "none"
  • [x] Acceptance Criteria -- present (6 items)
  • [x] Test Expectations -- present (3 tests + run command)
  • [x] Constraints -- present
  • [x] Checklist -- present
  • [x] Related -- present

Traceability

  • [x] story:portfolio-builder label -- AI Portfolio Builder
  • [x] story note verified -- story-kalshi-assistant-portfolio-builder exists in pal-e-docs, listed in project-kalshi-assistant user-stories section
  • [x] arch:app label -- application component
  • [ ] arch note MISSING -- [SCOPE] Create architecture note arch-app for the Rails application component
  • [x] Forgejo issue -- ldraney/kalshi-assistant#5, open

File Targets

  • [ ] app/services/sizing_engine.rb -- ISSUE: file to be created, but the app/ directory does not exist. The repo is currently docs-only. Rails scaffold (issue #1) must be completed first to establish the app/services/ directory structure.
  • [ ] app/services/scenario_analyzer.rb -- ISSUE: same as above -- depends on Rails scaffold existing.
  • [x] docs/strategy/sizing-models.md -- verified: contains Option D math (83/17 split, -$5.77 worst case, all scenario tables). Context reference is accurate.

Repo Placement

OK. Issue filed on ldraney/kalshi-assistant, work targets ldraney/kalshi-assistant. Single repo, no cross-repo concerns.

Dependencies

  • Declared: #3 (Strategy engine -- database schema, board item #1688, sprint:2, backlog). Correct -- the sizing engine needs the strategy/trade schema.
  • Undocumented: #1 (Rails app scaffold, board item #1686, sprint:1, backlog). The app/services/ path assumes a Rails app structure that does not yet exist. This is a hard blocker -- without the Rails framework, there is no directory to create services in and no test runner to execute rails test.
  • Both dependencies are in the backlog column. This ticket (sprint:3) cannot start until sprint:1 (#1) and sprint:2 (#3) complete.

Acceptance Criteria

6 acceptance criteria, all concrete and agent-verifiable:
  • Input/output contracts are well-defined (picks array, budget, contract allocations)
  • Optimization target is clear (brute-force over 50-99% YES/NO ratio)
  • Scenario table output is specified (2^N outcomes with probability and P&L)
  • Scale constraint is bounded (1-10 picks, max 1024 scenarios)
  • Test expectations reference concrete values from docs (83/17 ratio, -$5.77 worst case) which are verified in docs/strategy/sizing-models.md
  • Run command (rails test) is standard for Rails
Criteria are testable. However, count of 6 AC exceeds the >5 decomposition threshold.

Blast Radius

Low. This creates new service classes in a greenfield codebase. No existing code patterns to search for similar issues. No downstream consumers at this stage. The sizing engine is self-contained computation with no external integrations.

Decomposition Assessment

  • File targets: 2 files in 1 repo -- OK (below >3 across >2 repos threshold)
  • Acceptance criteria: 6 -- exceeds >5 threshold
  • Estimated agent time: under 5 minutes -- the math is fully documented in sizing-models.md, and the two services are tightly coupled (scenario_analyzer feeds sizing_engine)
One of three decomposition triggers fires (6 AC > 5). However, the work is tightly coupled -- SizingEngine and ScenarioAnalyzer form a single computation pipeline. Splitting them into separate tickets would create artificial boundaries and add coordination overhead. The 6 AC describes aspects of a single algorithm, not independent features. Recommend the author either consolidate to 5 AC (e.g., merge "returns optimal ratio" into the output AC) or accept the borderline count given the tight coupling.

Recommendation

  • [BODY] Add dependency on #1 (Rails app scaffold) to the Lineage section. Current text mentions only #3 (schema), but the app/services/ path requires the Rails framework to exist. Suggested: "Depends on ldraney/kalshi-assistant #1 (scaffold) and #3 (schema)."
  • [SCOPE] Create architecture note arch-app for the Rails application component. The arch:app label on this and other board items has no backing architecture note in pal-e-docs.
  • [BODY] Consider consolidating AC from 6 to 5 by merging "Returns optimal ratio and expected value" into "Output: contracts to buy for each YES and NO position" (both describe output shape). This avoids the >5 decomposition trigger. Alternatively, accept the 6 AC given the tight coupling of the work.