CodeForPhilly / CodeForPhilly/codeforphilly-ng

docs: document operator-facing scripts (cutover-dry-run, cutover-mailout, reconcile, setup-dev-data)

Open
#114 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
1
Forks
1
Avg merge
5d 3h
Merged PRs (30d)
9

Description

## Gap

Four \`apps/api/scripts/*\` operator-facing scripts exist with no doc entry in \`docs/operations/\` or the relevant spec:

| Script | What it does | Where it should be documented |
|---|---|---|
| \`cutover-dry-run.ts\` | Walks the full cutover pipeline against a non-prod target — used during T-3 staging rehearsal | \`docs/operations/cutover.md\` (T-3 section) |
| \`cutover-mailout.ts\` | Sends T+90 unclaimed-account reminder emails | \`docs/operations/cutover.md\` (T+90 section) or \`specs/behaviors/account-migration.md\` |
| \`reconcile.ts\` | Walks Person records and flags private-store orphans (used at cutover + ongoing) | \`docs/operations/runbook.md\` (maintenance) — referenced once in \`specs/behaviors/private-storage.md:99\` but no operator instructions |
| \`setup-dev-data.ts\` | Seeds gitsheets with minimal sheet configs for local boot | \`specs/architecture.md\` Build/dev section + \`CLAUDE.md\` local setup |

## Why it matters

Pre-cutover, the staging rehearsal (#54) needs operators to know these exist + how to invoke them. Local-setup contributors hit \`setup-dev-data.ts\` on first run and may not know what they're running.

Identified during the 2026-05-30 post-cutover-blog spec-drift audit.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start by reading apps/api/scripts/cutover-dry-run.ts, cutover-mailout.ts, reconcile.ts, and setup-dev-data.ts, then compare them with docs/operations/cutover.md, docs/operations/runbook.md, specs/behaviors/account-migration.md, specs/behaviors/private-storage.md, specs/architecture.md, and CLAUDE.md. Document each script's purpose, invocation, and operational context in the locations named by the issue, including the existing private-storage reference. Done means operators can find and understand all four scripts for cutover, maintenance, and local setup.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.