# 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 |
