Production Ready

Perform an evidence-based production-readiness audit.

Adapt the audit to the application's actual stack, architecture, audience, business model, jurisdictions, indexing intent, and operational risk. Do not recommend controls or technologies that are not relevant to the application.

Do not modify application code, dependencies, database schemas, CI/CD, deployment configuration, Dockerfiles, infrastructure, or remote services during the audit. Updating TODO.md is the only default file mutation.

Step 1: Establish Scope

Before evaluating readiness:

• Read AGENTS.md, README.md, TODO.md, and relevant project configuration.
• Identify application entry points, services, datastores, external providers, and deployment targets.
• Inspect package manifests, lockfiles, environment examples, migrations, and existing verification scripts.
• Determine which parts of the application are intended to be production-ready.
• Identify production claims in documentation and compare them with implemented behavior.
• Ask a focused question when missing environment, audience, jurisdiction, or deployment information materially affects the audit.
• State what was reviewed and what was not reviewed.

Determine whether the application is public or private, what data and commercial activities it supports, its audience and known jurisdictions, its use of non-essential tracking, its indexing intent, and whether it represents a local business or publishes third-party content requiring attribution.

Apply every check according to this profile. Classify irrelevant controls as NOT APPLICABLE and unavailable evidence as UNVERIFIED. Do not convert optional best practices into release blockers.

Do not infer legal obligations solely from the technology stack. The audit may identify missing disclosures, inconsistent behavior, or technical consent defects, but it must not claim that legal language is legally sufficient. Recommend qualified legal review where jurisdiction-specific interpretation is required.

For large repositories, prioritize:

1. Authentication and authorization
2. External input and API boundaries
3. Durable state and database lifecycle
4. Payments and other irreversible side effects
5. Background jobs, queues, caching, and concurrency
6. Secrets and environment configuration
7. Error handling and recovery
8. Build, startup, shutdown, and deployment paths
9. Critical user journeys
10. Public routes with privacy, accessibility, or indexing implications

Step 2: Run Relevant Verification

Discover and run existing project commands where applicable:

• Tests
• Linting
• Type checking
• Production build
• Backend tests
• Static analysis
• Dependency or security checks already configured by the project

Run focused checks first and broader checks when warranted.

Do not install dependencies, change package versions, bypass security controls, or alter configuration merely to make verification pass without explicit approval.

Report every check as:

• PASS: Completed successfully
• FAIL: Completed and found a problem
• BLOCKED: Could not run because of a specific prerequisite
• NOT RUN: Intentionally omitted, with the reason

Distinguish failures introduced by current work from apparently pre-existing failures when evidence permits.

A successful build or test suite is useful evidence, but is not sufficient by itself to declare the application production-ready.

Runtime verification

When the application can run locally without external mutation, inspect representative routes and critical journeys. Prefer rendered or runtime evidence for status codes, redirects, metadata, indexing, storage, consent, accessibility, links, assets, and user-visible states.

Do not verify browser-dependent behavior from source presence alone. When runtime inspection is unavailable, classify materially important browser-dependent requirements as UNVERIFIED; do not create separate unverified entries for low-risk polish.

Step 3: Evaluate Readiness

Evaluate only applicable categories.

Use these checklists as investigation prompts, not as a requirement to enumerate every item in the report. Report all findings and material unverified areas, but summarize verified and not-applicable controls unless individual evidence is important to the verdict.

A. Correctness and release integrity

Check for:

• Critical user journeys covered by behavior-focused tests
• Failing tests, lint errors, type errors, or production build failures
• Placeholder, demo, stubbed, or incomplete behavior presented as complete
• Inconsistent API contracts or unvalidated external responses
• Environment-specific behavior missing from verification
• Documentation claims that do not match implemented behavior
• Broken critical journeys, navigation, forms, or state transitions

B. Security and technical privacy

Check for:

• Authentication and authorization at trusted server or database boundaries
• Missing object-level, tenant-level, or role-level access checks
• Server-side validation of untrusted input
• SQL injection, cross-site scripting, CSRF, SSRF, path traversal, open redirects, and unsafe file handling where applicable
• Secrets exposed to browser bundles, logs, fixtures, source control, or error output
• Overly permissive CORS, cookies, session settings, redirects, or security headers
• Missing or weakened PostgreSQL privileges, Row Level Security, or service-role boundaries
• Abuse controls for expensive, privileged, or public endpoints
• Personal-data collection beyond what the represented journey requires
• Sensitive information sent unnecessarily to third parties
• Private or sensitive routes exposed through indexing, metadata, caches, logs, or errors

Do not claim a dependency vulnerability based only on age or apparent version. Use configured scanners, authoritative advisories, or other concrete evidence.

Never print secret values during the audit.

C. Data integrity and recovery

Check for:

• Safe, forward-only schema migration practices
• Compatibility between schemas, application types, queries, and RPC contracts
• Transactional and concurrency-safe state transitions
• Idempotency for retried writes, jobs, webhooks, payments, and notifications
• Defined handling for partial failure and interrupted operations
• Backup, restore, rollback, and recovery expectations appropriate to the data
• Retention, archival, deletion, and privacy behavior
• Cache invalidation and stale-data behavior
• Safe handling of destructive or irreversible operations

Never apply migrations or mutate remote data during the audit.

D. Reliability and failure handling

Check for:

• Startup validation for required configuration
• Timeouts, cancellation, bounded retries, and backoff where appropriate
• Graceful shutdown and resource cleanup
• Queue, worker, scheduler, and webhook recovery
• Duplicate processing and race-condition risks
• External provider failure handling
• Visible error states rather than silent failure
• Health and readiness signals appropriate to the deployment model

Retries must not hide permanent failures or create duplicate side effects.

E. Observability and operations

Check for:

• Actionable structured logging without secret or private-data leakage
• Error reporting with enough context to diagnose failures
• Metrics for critical availability and business flows
• Health checks, readiness checks, or equivalent platform signals
• Runbooks or recovery procedures for important failure modes
• Clear environment configuration and deployment prerequisites
• Release, rollback, and recovery procedures appropriate to the application

Match recommendations to likely operational risk. Do not require enterprise-scale observability for a small personal application.

F. Performance and scalability

Check for:

• N+1 queries and unnecessary repeated network calls
• Unbounded queries, loops, queues, retained objects, or background work
• Missing pagination or limits on potentially large datasets
• Blocking operations in latency-sensitive or concurrent paths
• Cache behavior that threatens correctness or creates uncontrolled cost
• Frontend bundle, rendering, and request waterfalls on critical paths
• Stateful assumptions incompatible with the intended deployment model

Treat performance concerns as findings only when supported by code-path evidence, measurements, or a clear scaling bound. Do not prescribe caching or architectural complexity without an identified need.

G. Frontend behavior and user experience

Check for:

• Responsive behavior on supported viewport sizes
• Loading, empty, success, error, disabled, and offline states where applicable
• Recovery from failed requests and stale data
• Hydration, server/client boundary, and rendering problems
• Layout shifts or blocked interactions on critical journeys
• Clear feedback for submissions and irreversible actions
• Browser compatibility required by the application's stated support
• Graceful handling of failed images, embeds, and external resources

Preserve the existing design system unless a redesign is requested.

H. Configuration and dependency hygiene

Check for:

• Reproducible dependency installation through lockfiles
• Supported runtime versions documented or enforced
• Environment examples that list names without real secrets
• Fail-fast validation for required environment variables
• Separation of public and server-only configuration
• Unused, obsolete, or risky dependencies when supported by evidence
• Debug settings, test credentials, or development behavior enabled in production paths

Do not add or update dependencies during the audit.

I. Legal, consent, and public trust surfaces

Where applicable, check for:

• Policies and disclosures appropriate to the observed data processing and business model, linked from relevant user surfaces
• Policy identity, dates, contact details, and claims consistent with implemented behavior and external providers
• Terms acceptance separated from optional marketing or purpose-specific consent
• Consent that is informed, unbundled, unselected by default, recorded when required, and as easy to withdraw as to grant
• Non-essential storage, analytics, advertising, personalization, and session replay blocked until required consent
• Cookie disclosures and controls matching actual storage and network activity
• Account deletion, export, preferences, unsubscribe, and suppression behavior matching represented functionality
• Appropriate identity, licensing, attribution, and provenance for public content, claims, testimonials, media, and third-party assets

J. Accessibility and inclusive interaction

Evaluate public pages and critical user journeys against the application's stated accessibility standard, or use WCAG 2.2 Level AA as the default technical target.

Check where applicable:

• Structure: language, titles, landmarks, headings, and semantic HTML
• Content: alternative text, decorative images, captions, and media equivalents
• Forms and controls: accessible names, labels, instructions, consent, states, validation, and actionable errors
• Interaction: keyboard access, focus order, visible focus, skip navigation, and focus management
• Components: correct roles, states, relationships, and announcements for dynamic interfaces
• Presentation: contrast, zoom, reflow, target size, reduced motion, and non-color indicators
• Critical journeys: accessible authentication and manual keyboard verification in addition to automated checks

K. Public-site integrity, SEO, and discoverability

For public-facing routes, check applicable site-integrity controls. Apply SEO and indexing controls only to pages intended to be indexed:

• Page identity: descriptive titles, primary headings, descriptions, language, social metadata, and absence of placeholder content
• URL identity: canonical URLs, redirects, duplicate handling, and correct status codes
• Indexing: robots directives, authentication boundaries, robots.txt, and a sitemap containing canonical indexable URLs
• Navigation: crawlable internal links, no important orphan pages, descriptive link text, breadcrumbs where useful, and a genuine custom 404 response
• Assets and delivery: favicon, application icons, content types, encoding, viewport configuration, and missing-resource behavior
• Structured data: valid schema aligned with visible content, including local business data only for actual local or service-area businesses
• Internationalization: correct locale, language, and alternate-language metadata
• Trust and safety: valid attribution links and error pages without secrets, private data, stack traces, or inappropriate internal details

Do not treat robots.txt as access control. Sensitive routes must remain protected even when crawling is disallowed.

Do not require every route in the sitemap. Exclude private, redirected, duplicate, non-canonical, error, parameter-only, and noindex routes.

Do not report absent SEO features as defects for internal, authenticated-only, temporary, or intentionally non-indexed applications.

Step 4: Classify Evidence

Classify each evaluated item as:

• VERIFIED: Evidence supports that the requirement is satisfied
• FINDING: Evidence shows a concrete deficiency or material risk
• UNVERIFIED: Readiness depends on unavailable information or testing
• NOT APPLICABLE: The requirement does not apply

Every finding must include:

• Severity
• Category
• Evidence with a file and line reference, command result, route, or configuration reference
• Affected behavior
• Production impact
• Concrete remediation
• Verification criteria for considering it resolved

For route-level findings, include:

• The affected URL or route pattern
• Whether it is public, authenticated, indexable, or intentionally excluded
• Source evidence and, where available, rendered or HTTP evidence
• Whether the issue affects a shared layout, a route group, or one page

Policy presence alone is not verification. Compare policy claims with observed code, configuration, storage, network requests, forms, providers, and account behavior.

Prefer runtime or rendered evidence for generated metadata, status codes, redirects, structured data, consent behavior, and browser storage.

Do not present hypothetical concerns as confirmed defects. Label uncertainty explicitly.

Step 5: Assign Severity

Critical

A demonstrated vulnerability, data-loss risk, authorization bypass, secret exposure, or failure that makes production operation unsafe.

High

A likely production incident, major reliability failure, broken critical journey, unrecoverable operational gap, or serious security weakness.

Medium

A meaningful but non-blocking deficiency in resilience, observability, performance, accessibility, privacy implementation, public-site integrity, or operational readiness.

Low

Minor hardening, polish, metadata, discoverability, or documentation work with limited production impact.

UNVERIFIED is an evidence classification, not a severity. Record why the evidence is unavailable, the potential production impact, how to verify it, and whether the missing evidence blocks the verdict.

Apply severity contextually:

• Do not automatically assign Critical severity to privacy or consent findings. Base severity on demonstrated data, audience, jurisdiction, and regulatory risk.
• Treat inaccessible authentication, checkout, essential forms, or account controls more severely than isolated presentation defects.
• Treat indexing of private or sensitive content as a security or privacy issue rather than merely SEO.
• Treat ordinary favicon, metadata, breadcrumb, sitemap, internal-link, and structured-data defects as Medium or Low unless they break a critical journey or expose protected content.
• Missing legal text is not automatically High. Consider actual data processing, commercial activity, audience, and launch context.
• Use UNVERIFIED rather than asserting noncompliance when jurisdiction or legal applicability is unknown.
• Do not inflate severity to make the report appear thorough.

Step 6: Update TODO.md

Updating TODO.md is the only default file mutation allowed during the audit.

Do not modify TODO.md when no unresolved findings, status changes, or material unverified blockers need to be recorded.

When an update is required, invoke update-docs and follow its canonical TODO.md structure.

• Add confirmed unresolved findings not already represented.
• Record material unverified release blockers when additional evidence is required.
• Include severity, category, affected file or route, and verification criteria where practical.
• Merge duplicate findings.
• Update stale entries when repository evidence shows they are inaccurate.
• Move verified resolutions to the Completed section.
• Preserve historical entries.
• Do not include secrets, private personal data, transient command output, or speculative findings.

Step 7: Produce the Report

Use this structure:

Production Readiness Verdict

Choose one:

• READY: No known release blockers remain and all critical boundaries were verified
• READY WITH CONDITIONS: No demonstrated critical blocker remains, but listed conditions or unverified areas must be accepted
• NOT READY: One or more Critical or High release blockers remain
• INDETERMINATE: Critical evidence was unavailable, so readiness cannot be established

Apply verdicts in this order:

1. Use INDETERMINATE when evidence for a critical boundary is unavailable.
2. Otherwise, use NOT READY when a Critical or High release blocker remains.
3. Otherwise, use READY WITH CONDITIONS for material non-critical conditions or unverified areas.
4. Use READY only when no known blockers or material conditions remain and all critical boundaries were verified.

Include a brief rationale.

Scope

State:

• What was reviewed
• What was not reviewed
• Which categories were not applicable
• Material assumptions about environment, audience, jurisdiction, or deployment

Verification Results

List every command or runtime check with:

• PASS
• FAIL
• BLOCKED
• NOT RUN

Release Blockers

List Critical and High findings in priority order.

Other Findings

List Medium and Low findings in priority order.

Unverified Areas

List missing evidence, why it matters, and how to verify it.

Verified Strengths

Briefly identify important controls that were actually verified. Do not pad this section with generic praise.

TODO.md Changes

Summarize items added, updated, moved, or marked stale.

Recommended Next Action

Name the single most important next action.

End by asking whether the user wants the findings implemented. Do not begin implementation until the user approves it.

Behavior Rules

• Be evidence-based and specific.
• Review production-critical paths end to end.
• Prioritize security, data integrity, recovery, and critical journeys before public-site polish.
• Match recommendations to the application's actual scale and risk.
• Do not confuse best practices with release blockers.
• Do not claim readiness when critical evidence is missing.
• Do not deploy, push, publish, communicate externally, or mutate remote services.
• Do not modify application code, dependencies, schemas, infrastructure, or configuration during the audit.
• Updating or creating TODO.md is the sole default mutation.
• Ask before implementing any remediation.