jeremylongshore/tons-of-skills-marketplace / plugins/community/jeremy-firestore/skills/firestore-operations-manager
firestore-operations-manager
VerifiedManage Firebase/Firestore operations including CRUD, queries, batch processing, and index/rule guidance. Use when you need to create/update/query Firestore documents, run batch writes, troubleshoot missing indexes, or plan migrations. Trigger with phrases like "firestore operations", "create firestore document", "batch write", "missing index", or "fix firestore query".
| File | Kind | Size |
|---|---|---|
| ARD.md | markdown | 9.8 KB |
| PRD.md | markdown | 6.7 KB |
| SKILL.md | skill md | 2.9 KB |
| references/errors.md | markdown | 7.7 KB |
| references/examples.md | markdown | 7.0 KB |
| references/implementation.md | markdown | 7.0 KB |
| scripts/setup-firestore.shexecutable | script | 1.6 KB |
PRD.md
View on GitHub# PRD: Firestore Operations Manager Skill
## Problem Statement
Firestore operations at scale require deep knowledge of batch write mechanics, composite index design, security rules authoring, and migration strategies. Developers routinely hit production issues -- missing composite indexes that crash queries, write contention on hot documents, security rules that silently block legitimate operations, and data migrations that lose documents or corrupt fields.
These problems share a root cause: Firestore's document model and operational constraints (500-write batch limit, 1-write-per-second-per-document sustained, mandatory composite indexes for multi-field queries) are well documented but poorly surfaced at development time. Errors appear only at runtime, often in production.
## Target Users
| Persona | Description | Key Need |
|---------|-------------|----------|
| Firebase developer | Building apps on Firestore, intermediate skill | Correct CRUD patterns, query optimization, index guidance |
| Backend engineer | Migrating data or building ingestion pipelines | Safe batch operations with checkpoints and rollback |
| Data team | Managing production Firestore data at scale | Migration strategies, schema evolution, cost control |
| Security-conscious developer | Writing or auditing Firestore security rules | Rules that pass emulator tests and enforce least privilege |
## Success Criteria
1. **Zero data loss on migrations**: Batch operations include checkpointing so that a failure at document 50,000 of 100,000 resumes from 50,000, not from 0.
2. **Correct indexes on first deploy**: Composite indexes are identified before deployment, not discovered via runtime FAILED_PRECONDITION errors.
3. **Rules pass emulator tests**: Security rules generated by this skill pass `@firebase/rules-unit-testing` validation against expected access patterns.
4. **Batch operations under limits**: All batch writes stay within the 500-operation limit per commit; all transactions complete within the 270-second server-side deadline.
5. **Paginated reads by default**: Queries returning potentially large result sets use cursor-based pagination, not unbounded `.get()`.
## Scope
### In Scope
- Document CRUD (create, read, update, delete) with proper error handling
- Batch writes (up to 500 operations per commit) with retry logic
- Transactions for multi-document atomic operations
- Composite index detection and `firestore.indexes.json` generation
- Security rules authoring with helper functions and field-level validation
- Emulator-first testing workflow for rules and queries
- Data migrations: backfill new fields, transform existing fields, move between collections
- Cursor-based pagination for large result sets
- Write contention mitigation (distributed counters, sharding)
- Cost estimation for read/write patterns
### Out of Scope
- Firestore-to-BigQuery export streaming (use Firestore Extensions)
- Real-time listener architecture design
- Firestore in Datastore mode
- Cross-database replication or multi-region configuration
- Vertex AI vector search in Firestore (covered by firebase-vertex-ai skill)
## Functional Requirements
### FR-1: Schema-Aware CRUD
The skill must detect the existing collection schema (by reading sample documents) before proposing writes. New fields added via `update()` must not overwrite existing data unless explicitly requested.
### FR-2: Batch Write Management
Batch writes must:
- Chunk operations into groups of 500 (Firestore limit per `batch.commit()`)
- Log progress every N documents (configurable, default 1,000)
- Write a checkpoint document after each successful batch so the operation can resume
- Retry failed batches with exponential backoff (3 attempts, 1s/2s/4s delays)
### FR-3: Composite Index Generation
When the skill generates a query with multiple `where()` clauses or a `where()` + `orderBy()` combination, it must also produce the corresponding composite index entry for `firestore.indexes.json`.
### FR-4: Security Rules
Generated rules must:
- Deny all access by default (no `match /{document=**} { allow read, write: if true }`)
- Use helper functions for authentication and ownership checks
- Include field-level validation for create and update operations
- Be testable with `@firebase/rules-unit-testing`
### FR-5: Migration Operations
Migrations must:
- Support backfill (add field to existing documents) and transform (modify field values)
- Write a checkpoint after each batch to a `_migrations/{migrationId}` document
- Support dry-run mode that reads but does not write
- Produce a summary (documents processed, skipped, failed)
### FR-6: Pagination
Queries that may return more than 100 documents must use `startAfter()` cursor-based pagination. The skill must produce both the query code and the pagination cursor management logic.
## Non-Functional Requirements
- **Throughput**: Batch operations must sustain 500 writes per second against Firestore without triggering rate limits (using staggered batch commits).
- **Idempotency**: Migrations must be idempotent -- running the same migration twice produces the same result without duplicating data.
- **Cost transparency**: For operations affecting > 1,000 documents, the skill must estimate Firestore read/write costs using current pricing ($0.06/100k reads, $0.18/100k writes).
- **Emulator compatibility**: All generated code must work against the Firestore emulator (`localhost:8080`) with no modification.
## Dependencies
| Dependency | Version | Purpose |
|------------|---------|---------|
| firebase-admin | >= 12.0 | Server-side Firestore access |
| @firebase/rules-unit-testing | >= 3.0 | Security rules testing |
| Firebase CLI | >= 13.0 | Emulator, rules deploy, index deploy |
| Node.js | >= 18 LTS | Runtime for Admin SDK scripts |
## Risks and Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| Hot document write contention | Writes to same doc > 1/sec cause ABORTED errors | Use distributed counters or sharded writes for high-throughput paths |
| Composite index build time | New indexes take minutes to hours for large collections | Deploy indexes before code that depends on them; use `firebase firestore:indexes` to check status |
| Security rules too restrictive | Legitimate operations blocked in production | Test all access patterns against emulator before deploy |
| Migration halfway failure | Partial data state if script crashes mid-batch | Checkpoint after each batch; resume from last checkpoint |
| Unbounded reads | Forgetting `.limit()` on a million-doc collection | Enforce pagination for any query without a known small result set |
| Stale reads in transactions | Reading outside transaction sees older data | Always read within `runTransaction()` when consistency matters |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |