# FINAL PRODUCTION READINESS REVIEW

This application is about to ship to production.

Perform an exhaustive production-readiness review of the ENTIRE repository.

The review is complete only when you have inspected every relevant part of the codebase and cannot
reasonably identify any additional meaningful findings.

This is NOT a first pass.

Do not sample files.

Do not stop after finding "enough" issues.

Do not stop after reviewing only the important modules.

Inspect the complete repository.

Complexity findings should normally be classified as P2.

Escalate them to P1 only when the unnecessary complexity directly contributes to production bugs,
data integrity risks, reliability issues, security problems, or makes correctness significantly
harder to guarantee.

================ PRIMARY GOAL ================

Your primary objective is to prevent production problems.

Priorities:

1. Bugs
2. Data integrity
3. Reliability
4. Architecture flaws
5. Project inconsistencies
6. Security & Privacy
7. Legal / Licensing / Compliance
8. Performance
9. UX
10. Maintainability

Prioritize real production impact over stylistic preferences.

================ USE AVAILABLE DOMAIN SKILLS ================

Whenever specialized skills, documentation, repository-specific guidance, framework expertise, or
domain-specific review skills are available, proactively use them when relevant.

Use available skills as authoritative guidance for the technologies and patterns actually used by
the project.

However, always validate recommendations against the project's actual architecture and requirements.

Do not report purely stylistic differences.

Only report findings with a concrete impact on correctness, maintainability, performance, security,
reliability, or UX.

Do not force generic best practices onto the project when they do not apply to its actual
architecture.

================ TODO.MD IS THE DELIVERABLE ================

Create and continuously maintain TODO.md.

Do NOT wait until the end.

After finishing every major review area:

- verify findings
- immediately write confirmed findings into TODO.md
- save the file
- continue with the next area

Assume execution may terminate at any time.

Never keep confirmed findings only in context.

TODO.md is your persistent checkpoint and the primary deliverable.

================ REPOSITORY COVERAGE ================

Inspect every relevant production artifact, including:

- source files
- tests
- build files
- build configuration
- dependency declarations
- lockfiles and version catalogs
- application configuration
- environment configuration
- manifests
- resources
- assets
- database schemas
- migrations
- serialization models
- API clients
- networking
- storage
- caching
- authentication
- authorization
- release/debug configuration
- CI/CD configuration
- deployment configuration
- infrastructure configuration
- scripts
- automation
- documentation
- licenses
- NOTICE files
- bundled third-party code
- generated code when relevant
- configuration templates
- feature flags
- development tooling that can affect production

Actually inspect every relevant file.

Do not assume similar files are correct.

Do not skip files because they appear simple.

Do not treat generated, configuration, or infrastructure files as automatically safe.

================ UNDERSTAND THE APPLICATION ARCHITECTURE ================

First understand the repository's architecture, major components, boundaries, dependencies, sources
of truth, persistence mechanisms, external integrations, and important runtime flows.

Identify:

- application entry points
- major modules
- domain boundaries
- data ownership
- sources of truth
- persistence mechanisms
- external systems
- background processing
- synchronization mechanisms
- state management
- error handling
- retry mechanisms
- recovery mechanisms
- security boundaries
- deployment boundaries

Do not review files only in isolation.

Understand how important components interact.

================ TRACE COMPLETE DATA AND CONTROL FLOWS ================

Trace important flows completely across the system.

For each critical flow, follow the lifecycle from input to final observable result.

Depending on the application, this may include:

- user input
- API requests
- validation
- business logic
- transformations
- persistence
- caching
- external services
- background processing
- queues
- events
- notifications
- filesystem operations
- database operations
- synchronization
- deletion
- updates
- retries
- cancellation
- concurrency
- application restart
- process termination
- recovery
- failure handling
- authentication
- authorization
- logging
- analytics
- external side effects

Identify important application invariants and verify that they hold across every relevant code path.

Examples:

- persisted references remain valid
- related records remain consistent
- caches cannot silently diverge from the source of truth
- operations are atomic where required
- partial failures cannot leave invalid state
- retries cannot duplicate irreversible operations
- concurrent operations cannot corrupt state
- deleted data cannot remain unintentionally accessible
- authorization cannot be bypassed through alternate paths
- external side effects cannot occur without the required state transition

Adapt these invariants to the actual application.

================ VERIFY BEFORE REPORTING ================

Every finding begins as a hypothesis.

Before reporting it:

- inspect surrounding code
- inspect callers
- inspect callees
- inspect related modules
- inspect configuration
- inspect tests
- inspect framework behavior when relevant
- inspect error handling
- try to disprove your own finding

Search for:

- validation
- transactions
- synchronization
- locking
- concurrency controls
- lifecycle handling
- framework guarantees
- retry logic
- recovery logic
- existing safeguards
- feature flags
- configuration conditions
- platform guarantees
- tests covering the behavior

Only report findings that survive verification.

Avoid false positives.

Prefer 20 high-confidence findings over 100 speculative ones.

================ USE TESTS WHEN HELPFUL ================

If a suspicious implementation can be verified by a useful test, write one.

Use tests to distinguish real bugs from false positives.

If the test proves the implementation is correct and provides long-term regression value:

- keep the test
- add a short code comment if the behavior is non-obvious

If a test exposes a real production bug:

- preserve the regression test
- document the finding in TODO.md
- include the test as evidence

Do not report a bug merely because code initially looked suspicious.

================ REVIEW CATEGORIES ================

## 1. Bugs & Data Integrity

Aggressively search for:

- crashes
- incorrect behavior
- data corruption
- data loss
- inconsistent state
- invalid persisted state
- transaction issues
- race conditions
- concurrency issues
- lifecycle issues
- cancellation bugs
- retry bugs
- duplicate operations
- stale state
- cache inconsistencies
- resource leaks
- recovery failures
- partial failure handling
- edge cases
- large-data issues
- invalid assumptions
- incorrect error handling
- silent failures
- state-machine errors
- incorrect ordering of operations

Persistent data integrity has the highest priority.

## 2. Architecture

Look for:

- incorrect ownership
- multiple sources of truth
- duplicated business rules
- hidden coupling
- architectural inconsistencies
- incorrect abstraction boundaries
- circular dependencies
- inappropriate dependency direction
- reliability risks caused by architecture
- security boundaries that are incorrectly placed
- components with responsibilities that do not belong together

Only report architecture issues with concrete consequences.

## 3. KISS PRINCIPLE / AVOID UNNECESSARY COMPLEXITY

Treat unnecessary complexity as a defect.

A solution is considered defective if it is significantly more complex than necessary to achieve the
same behavior without providing proportional benefits.

Follow the KISS principle throughout the review.

Always ask:

- Can this be implemented with fewer moving parts?
- Can responsibilities be consolidated?
- Can an abstraction be removed?
- Can the control flow be simplified?
- Is there a more direct solution that is equally correct?
- Is this flexibility actually required by the application?
- Does this design solve a real problem or merely a hypothetical future one?
- Does the added abstraction materially improve correctness or maintainability?

Actively look for:

- over-engineered abstractions
- unnecessary architectural layers
- needless indirection
- premature optimization
- excessive genericity
- unnecessary interfaces
- wrapper components that provide little value
- boilerplate introduced only for architectural purity
- overly fragmented business logic
- state machines that are more complex than the problem requires
- multiple implementations of the same responsibility
- complex control flow that could be significantly simplified
- frameworks or patterns used where straightforward code would be clearer
- designs that make debugging or reasoning unnecessarily difficult

Do NOT report complexity merely because another implementation would be shorter.

Only report unnecessary complexity when it provides little or no practical value or makes the system
harder to understand, verify, maintain, test, or evolve.

If the current implementation is intentionally sophisticated because it solves a real requirement,
do not report it.

For every confirmed complexity finding, include a high-level refactoring plan.

The refactoring plan should describe:

- why the current design is unnecessarily complex
- which abstractions or layers can be removed, merged, or simplified
- which responsibilities should be consolidated
- what the resulting architecture should look like
- the expected improvements in readability, maintainability, reliability, and testability

Do NOT prescribe implementation-level changes unless necessary.

Describe the desired architectural direction and end state so another coding agent can determine the
most appropriate implementation.

Prefer incremental refactoring plans that preserve behavior and minimize migration risk.

## 4. Consistency

Search repository-wide for:

- project rule violations
- inconsistent implementations
- inconsistent validation
- inconsistent error handling
- inconsistent state management
- inconsistent concurrency handling
- inconsistent API usage
- inconsistent architectural patterns
- duplicated solutions to the same problem
- code that ignores established project patterns
- AI-generated code that ignores established project patterns

Explain both the expected project pattern and the deviation.

Prefer systemic findings over individual duplicated findings.

## 5. Security & Privacy

Review:

- secrets
- credentials
- permissions
- access control
- authentication
- authorization
- sensitive logging
- local storage
- networking
- encryption
- data exposure
- input validation
- injection risks
- insecure defaults
- session handling
- token handling
- third-party integrations
- analytics
- telemetry
- user data exposure
- sensitive data lifecycle
- insecure configuration
- production/debug differences

Only report evidence-based issues.

Do not report theoretical security concerns without a credible attack path or concrete risk.

## 6. Legal / Licensing / Compliance

Perform a dedicated licensing and compliance review where applicable.

Inspect:

- direct dependencies
- transitive dependencies
- bundled code
- assets
- fonts
- icons
- SDKs
- copied code
- license files
- NOTICE files
- attribution requirements
- repository-specific compliance requirements

Look for:

- GPL
- LGPL
- AGPL
- incompatible licenses
- missing attribution
- missing NOTICE obligations
- unknown licensing
- copied code with unclear origin
- dependencies whose license terms conflict with the intended distribution

Before reporting:

Verify:

- dependency
- version
- actual license
- direct/transitive status
- production usage
- actual legal relevance

Do not report speculative legal issues.

If compliance requirements are application-specific and cannot be verified from the repository,
explicitly state the limitation.

## 7. Performance

Review the performance characteristics relevant to the actual application.

Consider:

- CPU usage
- memory usage
- database performance
- I/O
- network usage
- startup
- rendering
- background work
- battery/resource consumption where applicable
- unnecessary work
- repeated computation
- excessive allocations
- inefficient queries
- unbounded operations
- scalability
- large datasets
- concurrency
- caching

Ignore insignificant micro-optimizations.

Prioritize performance problems that can materially affect production users, infrastructure cost,
reliability, or scalability.

## 8. UX

Review meaningful production UX issues relevant to the application.

Consider:

- loading states
- errors
- recovery
- feedback
- cancellation
- stale UI
- navigation
- empty states
- offline behavior
- retry behavior
- destructive operations
- accessibility
- confusing state transitions
- inconsistent behavior
- data-loss scenarios
- unexpected side effects

Focus on meaningful production UX issues rather than subjective design preferences.

## 9. Maintainability

Finally look for:

- duplicated logic
- excessive complexity
- poor separation of concerns
- unnecessary abstractions
- difficult-to-test code
- misleading naming that causes correctness risks
- fragile dependencies between components
- obsolete code
- dead code that creates real maintenance risk
- temporary solutions that became permanent

Avoid subjective cleanup.

Only report maintainability issues when they create meaningful long-term engineering cost or
increase the probability of defects.

================ FINDING FORMAT ================

Each TODO entry must contain:

- Priority
- Category
- Location
- Related locations
- Problem
- Root Cause
- Impact
- Failure Scenario
- Expected Behavior
- Fix Direction
- Verification
- Evidence

Describe enough context that another coding model can fix the issue without rediscovering it.

Do not prescribe exact implementation unless necessary.

Every finding must be actionable, evidence-based, and independently understandable.

================ SYSTEMATIC SEARCH ================

Whenever you find a bug pattern:

Search the entire repository for similar occurrences.

Whenever you find a violated rule:

Search the entire repository for additional violations.

Whenever you find a risky architectural pattern:

Search where else it appears.

Whenever you find a security issue:

Search for the same vulnerability pattern throughout the repository.

Whenever you find an inconsistent implementation:

Search for all implementations of the same responsibility.

Prefer one systemic finding over many duplicate findings when the same root cause affects multiple
locations.

However, include all relevant locations in the finding.

================ TEST SUITE REVIEW ================

Review the existing test suite as production code.

Look for:

- missing coverage of critical invariants
- outdated tests
- flaky tests
- tests validating incorrect behavior
- tests that do not actually verify their intended behavior
- redundant tests
- missing failure-path coverage
- missing concurrency coverage
- missing recovery coverage
- missing persistence coverage
- opportunities to add durable regression tests

Do not equate high test coverage with high confidence.

Evaluate whether the tests actually protect the application's important invariants and production
failure modes.

================ SEARCH FOR TECHNICAL DEBT MARKERS ================

Search the repository for:

- TODO
- FIXME
- HACK
- XXX
- temporary workarounds
- disabled tests
- ignored tests
- skipped tests
- commented-out production logic
- feature flags
- deprecated APIs
- obsolete configuration
- known limitations

Verify whether they still represent real issues.

Do not automatically report every TODO or FIXME.

Only report items that represent meaningful production risk, correctness problems, security
concerns, maintainability problems, or incomplete functionality.

================ CONFIGURATION CONSISTENCY ================

Review configuration consistency across all relevant environments.

Check:

- development vs production differences
- debug vs release differences
- staging vs production differences
- obsolete configuration
- conflicting settings
- stale feature flags
- environment-specific behavior
- missing production configuration
- unsafe defaults
- dependency configuration consistency
- build configuration consistency
- deployment configuration

Look specifically for cases where development behavior differs materially from production behavior
and can hide production defects.

================ DEPENDENCY HYGIENE ================

Review:

- obsolete dependencies
- duplicate libraries
- overlapping libraries
- unused dependencies
- vulnerable dependencies
- conflicting dependencies
- unnecessary dependencies
- dependencies with excessive scope
- dependencies that can be removed without losing required functionality
- dependency version inconsistencies

Do not report a dependency merely because it is old or could theoretically be replaced.

Prioritize dependencies that create concrete security, reliability, maintenance, licensing, build,
or production risks.

================ FINAL COMPLETENESS CHECK ================

Before finishing, verify:

✓ Every relevant source file inspected
✓ Every relevant test inspected
✓ Build configuration inspected
✓ Dependencies inspected
✓ Licensing inspected
✓ Security inspected
✓ Configuration inspected
✓ Persistence mechanisms inspected
✓ External integrations inspected
✓ Critical data flows traced end-to-end
✓ Concurrency reviewed
✓ Lifecycle and failure handling reviewed
✓ Retry and recovery reviewed
✓ Repository-wide consistency search completed
✓ Similar bug patterns searched globally
✓ Technical debt markers reviewed
✓ Test suite quality reviewed
✓ TODO.md reread completely

If any answer is "no", continue reviewing.

The review is finished only when:

- the complete repository has been inspected
- important application flows have been traced end-to-end
- findings have been verified
- similar patterns have been searched globally
- TODO.md is fully up to date
- duplicate findings have been consolidated
- unsupported findings have been removed
- severity has been recalibrated where appropriate
- every remaining finding is evidence-based
- every finding is actionable
- no additional meaningful findings can reasonably be identified

================ FINAL PRINCIPLES ================

- Be systematic.
- Be skeptical of your own conclusions.
- Investigate before reporting.
- Verify before concluding.
- Persist findings continuously.
- Use tests when they improve confidence.
- Optimize for correctness, not speed.
- Prioritize production impact.
- Follow the project's actual architecture.
- Use available domain-specific expertise when relevant.
- Search globally for recurring problems.
- Prefer high-confidence findings over speculation.
- Do not report stylistic preferences as defects.
- Do not report complexity without meaningful consequences.
- Do not ask questions unless genuinely blocked.
- Do not stop early.
- The primary deliverable is TODO.md.
