b7f831e170
docs: tick off completed boxes in sub-project 1 plan (housekeeping)
2026-06-20 00:11:01 -06:00
53010b89dd
docs: add DB + reconciliation implementation plan (30 tasks, 7 phases)
...
Implements the spec at docs/superpowers/specs/2026-06-19-cyclone-db-reconciliation-design.md.
Phase 1 — Backend foundation (T1-T3): SQLAlchemy dep, db.py skeleton,
PRAGMA user_version migration runner, 0001_initial.sql with 6 tables.
Phase 2 — ORM models (T4-T6): Batch, Claim, Remittance, CasAdjustment,
Match, ActivityEvent + ClaimState enum.
Phase 3 — Reconciliation pure functions (T7-T8): match() with date
window + multi-claim fallback, apply_payment/apply_reversal,
split_unmatched.
Phase 4 — Store facade refactor (T9-T12): CycloneStore replaces
InMemoryStore with same public API + list_unmatched / manual_match /
manual_unmatch; reconcile.run orchestrator wired into store.add().
Phase 5 — API additions (T13-T17): db.init() in startup,
GET /api/reconciliation/unmatched, POST /match, POST /unmatch,
parse-835 response includes reconciliation summary; TODO marker
removal verification.
Phase 6 — Frontend (T18-T26): ClaimState types, api.listUnmatched/
matchRemit/unmatchClaim, useReconciliation hook, ClaimStateBadge
primitive (7 states, same palette), Reconciliation page, sidebar
nav entry, vitest worktree exclude.
Phase 7 — Docs + smoke (T27-T30): README persistence section + DB
URL docs, tick off sub-project 1 plan boxes, full end-to-end smoke
procedure, merge to main.
Total: 30 tasks across 7 phases. TDD discipline per task with
~32 new backend tests + ~4 new frontend tests. Target after
completion: 210 backend + 7 frontend tests passing.
2026-06-19 20:51:31 -06:00
cf9af8e1d9
docs: add DB + reconciliation design spec (sub-project 2 of 4)
...
Replaces the in-memory store with SQLite via SQLAlchemy 2.0; adds
automatic 837P ↔ 835 reconciliation on every 835 parse; ships a
manual /reconciliation page; extends the claim lifecycle to a
7-state model with reversal handling.
Key decisions (locked from brainstorming):
- SQLite at ~/.local/share/cyclone/cyclone.db, overridable via
CYCLONE_DB_URL (Postgres escape hatch)
- SQLAlchemy 2.0 sync ORM; PRAGMA user_version migration runner
- Strict auto-match on patient_control_number (CLM01 == CLP01)
within +/-7 days of service_date
- 7-state claim model with reversal that sets Claim.state=REVERSED
and preserves prior state on Match.prior_claim_state
- Reconciliation triggered inside store.add() after ERA persist;
fail-soft (logged + activity event, never blocks parse)
- 3 new API endpoints; new /reconciliation page; same palette
and aesthetic voice as sub-project 1
Spec is approved-section-by-section and self-reviewed.
2026-06-19 20:42:44 -06:00
d7ef35dd9a
docs: add production-readiness implementation plan (33 tasks, 4 phases)
...
Phases:
1. Backend (T1-T10): cyclone.store module, 6 GET routes, NDJSON streaming,
parse persistence, uvicorn 127.0.0.1 bind, full test suite run
2. Frontend (T11-T27): react-query wiring, 5 new UI primitives (Skeleton,
EmptyState, ErrorState, FilterChips, Pagination), Layout-level refetch
indicator, 5 page refactors (Claims, Remittances, Providers, ActivityLog,
Upload), 6 hooks, 3 keyframes, api.test.ts
3. Docs (T28-T32): 4 reference notes (837p, 835, x12naming, co-medicaid),
root README rewrite
4. Smoke (T33): end-to-end manual test with full acceptance checklist
Self-review included at end of plan (spec coverage table + placeholder
scan + type consistency check).
For agentic workers: superpowers:subagent-driven-development (recommended)
or superpowers:executing-plans.
2026-06-19 18:43:17 -06:00
078de28cc4
docs: add live-data UX section + aesthetic acceptance checks
...
- Replace 7.6 (skeleton) with hairline + scanline-shimmer design that
matches the existing precision-instrument voice (Cabinet Grotesk + Geist
Mono, true-black + electric-blue, hairline chrome, radial light + grain)
- Add 7.7 Live-data UX patterns: skeleton variants, EmptyState primitive,
ErrorState primitive, Layout-level refetch indicator, Active filter chips,
newly-streamed row highlight, status color alignment, pagination footer
- Add 13.1 visual / aesthetic acceptance checks
- Voice decision: stay the course — additive only, no new accent / typeface /
layout primitive / light theme
2026-06-19 18:36:39 -06:00
9e34f22cb3
docs: add production-readiness design spec (local-only, sub-project 1 of 4)
2026-06-19 18:31:40 -06:00
5ed59ef01a
Add 837P parser implementation plan
...
- 12 tasks: project skeleton, exceptions, segments, models, payer config,
fixtures, validator, parser orchestrator, CO fixture, writer, CLI, README
- TDD throughout; each task has 4-6 bite-sized steps with full code
- Optional prodfile smoke test (skipped if docs/prodfiles absent)
- Self-review checklist confirms full spec coverage
2026-06-19 15:12:04 -06:00
d9dc8a86bd
Add 837P parser design spec
...
- Approved design for the Python 837P parser module under backend/
- Pydantic v2, click CLI, structural + CO Medicaid validation
- One JSON file per claim, summary.json, continue-on-failure
- Includes .gitignore for the Python + Node stack
2026-06-19 15:07:52 -06:00
Tyler
Cyclone