Grammarly Prod Checklist

---
name: grammarly-prod-checklist
description: 'Production readiness checklist for Grammarly API integrations. Use when
  preparing

  a Grammarly integration for production deployment.

  '
allowed-tools: Read, Write, Edit, Bash(curl:*), Grep
version: 1.8.0
license: MIT
author: Jeremy Longshore <jeremy@intentsolutions.io>
tags:
- saas
- grammarly
- writing
compatibility: Designed for Claude Code
---
# Grammarly Production Checklist

## Overview

Grammarly provides AI-powered writing assistance with grammar checking, tone detection, plagiarism scanning, and style suggestions. A production integration processes user-submitted text through Grammarly's API and returns actionable suggestions. Failures mean unchecked content goes live, suggestion latency degrades UX, or sensitive text leaks outside approved processing boundaries.

## Authentication & Secrets

- [ ] `GRAMMARLY_API_KEY` stored in secrets manager (not config files)
- [ ] Client credentials (ID + secret) separated from application code
- [ ] Token refresh logic handles expiry before API calls fail
- [ ] Separate credentials for dev/staging/prod environments
- [ ] Key rotation schedule documented (90-day cycle)

## API Integration

- [ ] Production base URL configured (`https://api.grammarly.com/v1`)
- [ ] Rate limit handling with exponential backoff
- [ ] Text chunking implemented for documents > 100K characters
- [ ] Minimum 30-word validation before sending to API
- [ ] Suggestion categories configured per use case (grammar, tone, clarity)
- [ ] AI detection endpoint integrated if content authenticity required
- [ ] Plagiarism check timeout handling (longer processing for large docs)

## Error Handling & Resilience

- [ ] Circuit breaker configured for Grammarly API outages
- [ ] Retry with backoff for 429/5xx responses
- [ ] Writing score thresholds defined per content type
- [ ] Graceful degradation when API is unavailable (queue, not block)
- [ ] Error responses logged with request IDs for support escalation
- [ ] Partial suggestion results handled (incomplete analysis on timeout)

## Monitoring & Alerting

- [ ] API latency tracked per request type (check, detect, plagiarism)
- [ ] Error rate alerts set (threshold: >5% over 5 minutes)
- [ ] Token refresh failures trigger immediate notification
- [ ] Suggestion acceptance rate tracked for quality feedback loop
- [ ] Daily API usage against plan limits monitored

## Validation Script

```typescript
async function checkGrammarlyReadiness(): Promise<void> {
  const checks: { name: string; pass: boolean; detail: string }[] = [];
  // API connectivity
  try {
    const res = await fetch('https://api.grammarly.com/v1/check', {
      method: 'POST',
      headers: { Authorization: `Bearer ${process.env.GRAMMARLY_API_KEY}`, 'Content-Type': 'application/json' },
      body: JSON.stringify({ text: 'This is a production readiness test sentence for validation.' }),
    });
    checks.push({ name: 'Grammarly API', pass: res.ok, detail: res.ok ? 'Connected' : `HTTP ${res.status}` });
  } catch (e: any) { checks.push({ name: 'Grammarly API', pass: false, detail: e.message }); }
  // Credentials present
  checks.push({ name: 'API Key Set', pass: !!process.env.GRAMMARLY_API_KEY, detail: process.env.GRAMMARLY_API_KEY ? 'Present' : 'MISSING' });
  // Rate limit headroom
  try {
    const res = await fetch('https://api.grammarly.com/v1/usage', {
      headers: { Authorization: `Bearer ${process.env.GRAMMARLY_API_KEY}` },
    });
    checks.push({ name: 'Usage Endpoint', pass: res.ok, detail: res.ok ? 'Accessible' : `HTTP ${res.status}` });
  } catch (e: any) { checks.push({ name: 'Usage Endpoint', pass: false, detail: e.message }); }
  for (const c of checks) console.log(`[${c.pass ? 'PASS' : 'FAIL'}] ${c.name}: ${c.detail}`);
}
checkGrammarlyReadiness();
```

## Error Handling

| Check | Risk if Skipped | Priority |
|-------|----------------|----------|
| Token refresh logic | Silent auth failure blocks all checks | P1 |
| Text chunking | Large documents rejected or truncated | P1 |
| Rate limit handling | Burst traffic triggers 429 cascade | P2 |
| Plagiarism timeout | Stuck requests block content pipeline | P2 |
| Usage monitoring | Surprise plan overage charges | P3 |

## Prerequisites

- A protected production approval, named incident/rollback owners, and an artifact/configuration revision proven in sandbox and staging.
- Baselines for health, latency, quota, consent, retention, and synthetic functionality plus a canary integration.

## Instructions

1. Confirm environment, secret reference, destination allowlist, artifact digest, retention policy, and approval before enabling production.
2. Run health, quota, consent, retention, and behavior probes on the canary using fictitious text only.
3. Monitor aggregate metrics through the observation window; halt on errors, scope/retention drift, or a failed probe.
4. Promote in bounded stages or restore the previous revision, recording the decision and verified rollback.
5. Close only after owner acceptance of the redacted receipt and revocation of temporary credentials.

## Output

Create a readiness receipt with revision, canary, health/latency/quota/retention results, approvals, outcome, and rollback reference. Exclude credentials and text.

## Examples

`revision=r44; canary=synthetic-editor; health=pass; quota=within-budget; consent=pass; retention=none; outcome=promote` is a complete canary decision.

## Resources

- [Grammarly Developer API](https://developer.grammarly.com/)
- [Grammarly Status](https://status.grammarly.com)

## Next Steps

See `grammarly-security-basics` for text data handling and privacy controls.