Sportstime/.planning/phases/05-cloudkit-crud/05-02-PLAN.md

---
phase: 05-cloudkit-crud
plan: 02
type: execute
domain: data-pipeline
---

<objective>
Add sync verification and individual record management to cloudkit_import.py.

Purpose: Enable verification that CloudKit matches local data, plus ability to manage individual records.
Output: Enhanced cloudkit_import.py with --verify, --get, --update-record, and --delete-record flags.
</objective>

<execution_context>
~/.claude/get-shit-done/workflows/execute-phase.md
~/.claude/get-shit-done/templates/summary.md
</execution_context>

<context>
@.planning/PROJECT.md
@.planning/ROADMAP.md
@.planning/STATE.md
@.planning/phases/05-cloudkit-crud/05-01-PLAN.md

**Relevant source files:**
@Scripts/cloudkit_import.py

**Tech stack available:** Python 3, requests, cryptography, CloudKit server-to-server API
**Established patterns:** query_all() for full record retrieval, compute_diff() for change detection, sync_diff() for smart sync

**Prior plan context:**
- Plan 05-01 adds change detection and smart sync
- query_all() returns dict of recordName -> record data
- compute_diff() identifies new/updated/unchanged/deleted
</context>

<tasks>

<task type="auto">
  <name>Task 1: Add sync verification with --verify flag</name>
  <files>Scripts/cloudkit_import.py</files>
  <action>
Add sync verification to confirm CloudKit matches local canonical data.

1. Add `--verify` flag to argparse:
   - Query CloudKit for all record types
   - Compare counts with local data
   - Report discrepancies

2. Add `verify_sync(ck, data_dir, verbose)` function:
   - For each record type (Stadium, Team, Game, LeagueStructure, TeamAlias, StadiumAlias):
     - Query CloudKit count
     - Get local count from JSON files
     - Compare and report
   - Output format per type:
     ```
     Stadium: CloudKit=32, Local=32 [OK]
     Game: CloudKit=5758, Local=5760 [MISMATCH: 2 missing in CloudKit]
     ```

3. Add spot-check verification:
   - Random sample 5 records per type (if count matches)
   - Verify field values match between CloudKit and local
   - Report any field mismatches found

4. Add `--verify-deep` flag:
   - Full field-by-field comparison of ALL records (not just sample)
   - Report each mismatch with recordName and field name
   - Warning: "Deep verification may take several minutes for large datasets"

5. Menu integration:
   - Add option 14: "Verify sync (quick)"
   - Add option 15: "Verify sync (deep)"

Avoid: Modifying any data during verification. This is read-only.
  </action>
  <verify>
```bash
cd Scripts && python cloudkit_import.py --verify --verbose
```
Should output verification report showing CloudKit vs local counts with OK/MISMATCH status.
  </verify>
  <done>--verify flag reports accurate comparison between CloudKit and local data for all record types</done>
</task>

<task type="auto">
  <name>Task 2: Add individual record management commands</name>
  <files>Scripts/cloudkit_import.py</files>
  <action>
Add commands for managing individual records by ID.

1. Add `--get <type> <id>` flag:
   - Query single record by recordName
   - Print all field values in formatted output
   - Example: `--get Stadium stadium_nba_td_garden`

2. Add CloudKit `lookup(record_names)` method:
   - Use records/lookup endpoint for efficient single/batch lookup
   - Return list of records

3. Add `--update-record <type> <id> <field>=<value>` flag:
   - Lookup record to get current recordChangeTag
   - Update specified field(s)
   - Handle CONFLICT error with retry
   - Example: `--update-record Stadium stadium_nba_td_garden capacity=19156`

4. Add `--delete-record <type> <id>` flag:
   - Lookup record to get recordChangeTag
   - Delete single record
   - Confirm before delete (unless --force)
   - Example: `--delete-record Game game_mlb_2025_ari_phi_0401`

5. Add `--list <type>` flag:
   - Query all records of type
   - Print recordNames (one per line)
   - Support `--list <type> --count` for just the count
   - Example: `--list Stadium` prints all stadium IDs

6. Error handling:
   - Record not found: "Error: No Stadium with id 'xyz' found in CloudKit"
   - Invalid type: "Error: Unknown record type 'Foo'. Valid types: Stadium, Team, Game, ..."

Avoid: Deleting records without confirmation. Updating records without checking conflict.
  </action>
  <verify>
```bash
cd Scripts && python cloudkit_import.py --get Stadium stadium_nba_td_garden
```
Should print all fields for the specified stadium record.

```bash
cd Scripts && python cloudkit_import.py --list Game --count
```
Should print the count of Game records in CloudKit.
  </verify>
  <done>Individual record management commands work: --get, --list, --update-record, --delete-record</done>
</task>

</tasks>

<verification>
Before declaring plan complete:
- [ ] `--verify` reports accurate count comparison for all record types
- [ ] `--verify-deep` performs full field comparison with mismatch reporting
- [ ] `--get <type> <id>` retrieves and displays single record
- [ ] `--list <type>` lists all recordNames for type
- [ ] `--update-record` updates field with conflict handling
- [ ] `--delete-record` deletes with confirmation
- [ ] Interactive menu has options 14-15
- [ ] No regressions to existing functionality
</verification>

<success_criteria>

- Verification accurately detects sync discrepancies
- Individual record operations work for all record types
- Conflict handling prevents data corruption
- All CRUD operations now fully supported
- Phase 5 complete
</success_criteria>

<output>
After completion, create `.planning/phases/05-cloudkit-crud/05-02-SUMMARY.md`
</output>