docs: document operator-facing scripts (cutover-dry-run, cutover-mailout, reconcile, setup-dev-data)
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 76/100
- Issue type
- Documentation
- Clarity
- Clearly specified
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- documentation
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.
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.
- Dominant language
- TypeScript
- Stars
- 1
- Forks
- 1
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 25
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from CodeForPhilly/codeforphilly-ng
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
-
MarkdownEditor toolbar: use Radix Toolbar from radix-ui instead of the hand-rolled roving tabindex Openenhancement
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
-
Difficulty 2/5 1-3 hours Newbie friendliness 74/100
All issues in CodeForPhilly/codeforphilly-ng
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
copse-dev/agent-pane#2953 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Eynzof/Hermes-CN-Desktop#610 ·
-
bug clawsweeper:linked-pr-open clawsweeper:needs-live-repro clawsweeper:no-new-fix-pr impact:message-loss issue-rating: 🐚 platinum hermit P2 regression
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
-
enhancement
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
-
calcite-components needs triage refactor
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
Esri/calcite-design-system#15203 ·