Production Readiness Review

Production-Readiness Review

Deliverable Specification

Produce a single Markdown review document directed to a Principal Engineer containing:

1. Header: System name, scope/status, date, execution method (iteration counts, rubber-duck passes).
2. Issue Index: Compact table grouped by metric (ID, Title, Severity, Confidence, Location, Bucket).
3. Remediation Sections: One section per root-cause bucket detailing issues and the single production-grade solution with issue-by-issue mechanism mapping, concrete references, effort/risk, and validation strategies.
4. Traceability Matrix: Mapping Issue -> Bucket -> Metric.
5. Assumptions & Unverified Items: Any operational assumptions or unreadable paths marked UNVERIFIED with validation instructions.
6. References: Verified list of file:line, spec, and upstream citations.

Strict Constraints:

• Simple, direct, technically precise language. Short paragraphs. Concrete nouns.
• Do not use em dashes anywhere in the output or review.
• Every claim, issue, and solution must cite a verifiable reference (file:line, named spec, or authoritative upstream documentation).

Phase 0: Intake & Autonomous Execution Contract

1. Upfront Batch Intake

Gather the following 8 inputs upfront in a single batch. If any are provided in the initial prompt, fill them automatically and prompt only for missing items:

1. System Name: Target component or service name.
2. Code Paths / Repos: Target file paths to review (REQUIRED: cannot proceed without readable source code).
3. Sibling Systems & Test Kits: Supporting repos, mock kits, or integration harnesses.
4. Runtime Facts: Target environments, cluster specs, dashboards, prod constraints, and permission for read-only CLI commands.
5. Scope & Status: Active vs. latent, flag-off, or greenfield status.
6. Audience: Default is Principal Engineer.
7. Output File Path: Default is <SYSTEM>_PRODUCTION_READINESS_REVIEW.md in the current working directory.
8. Inclusions / Exclusions: Target metrics to emphasize or explicitly out-of-scope modules.

2. Autonomous Execution Contract

Once intake is collected, restate the execution plan in one line and run autonomously to completion:

• Never pause to ask clarifying questions, request mid-run approvals, or solicit confirmation.
• If an operational detail is ambiguous, record the most defensible assumption in the document's Assumptions section (noting what would invalidate it) and continue.
• If a referenced path is unreadable, label the finding UNVERIFIED with instructions on how to verify it manually, and proceed.
• Rubber-duck challenges run agent-to-agent (spawning subagents or multi-pass self-critiques), never through user interruptions.
• The review terminates only after the final Markdown document is written to the output path.

Ground Rules

1. Code Is Ground Truth: Audit the actual implementation code first. If code conflicts with documentation, specifications, or comments, treat code as truth and document the specification drift.
2. Evidence Invariant: Every assertion must link to an explicit file:line, architectural spec, or upstream library standard. Unsubstantiated claims are forbidden.
3. Continuous Rubber-Ducking: Red-team every candidate finding through 10 to 15 critique rounds. Challenge reasoning, eliminate false positives, uncover hidden failure modes, and calibrate severity. Never accept a first draft.
4. Context Differentiation: Explicitly distinguish between latent vs. active code paths, test harness vs. production implementations, and design omissions vs. runtime bugs.
5. Deduplication & Root Cause: Merge overlapping symptoms into single, foundational root-cause issues.
6. Continuous Evidence Log: Maintain traceable citation mappings throughout execution.

Audit Metrics

Evaluate the codebase against all 9 standard quality attributes plus domain-specific requirements:

1. Reliability & Fault-Tolerance: Crash recovery, retry storms, circuit breakers, timeout propagation, backpressure, idempotency.
2. Availability & Recovery: Single points of failure (SPOFs), health checks, graceful degradation, failover mechanics, drain behavior.
3. Performance: Hot paths, algorithmic bottlenecks, lock contention, memory allocations, latency percentiles (p99/p99.9), serialization overhead.
4. Scalability & Elasticity: Statefulness, resource limits, connection pooling, sharding/partitioning bottlenecks, concurrency limits.
5. Correctness & Data Integrity: ACID transaction boundaries, race conditions, consistency models, schema migrations, serialization safety.
6. Security & Blast Radius: Auth boundaries, privilege escalation, untrusted input parsing, secret leakage, blast radius containment.
7. Observability & Debuggability: Structured logging, metric cardinality, tracing context propagation, alertability, actionable error messages.
8. Operability & Maintainability: Configuration validation, flag safety, rollout/rollback safety, runbook clarity, dead code.
9. Resource Efficiency & Cost: Memory leaks, goroutine/thread leaks, disk I/O amplification, idle resource waste, compute overhead.
10. Domain-Specific Attributes: Real-time deadlines, regulatory boundaries, protocol invariants.

Review Lifecycle

flowchart TD
    A[Phase 0: Intake Batch] --> B[Phase 1: Metric-by-Metric Discovery]
    B --> C[Phase 2: Root-Cause Bucketing]
    C --> D[Phase 3: Production-Grade Remediation]
    D --> E[Phase 4: Assembly & Adversarial Fact-Check]
    E --> F[Write Final Review Document]

Phase 1: Metric-by-Metric Iterative Discovery

For EACH metric sequentially:

1. Source Inspection: Inspect raw source code through the lens of that specific metric.
2. Adversarial Rubber-Duck Iteration: Execute 10 to 15 critique passes on the candidate findings:
   • Eliminate claims lacking file:line backing.
   • Correct faulty reasoning and invalidate flawed failure-mode assumptions.
   • Surface blind spots and missed boundary conditions.
   • Tighten severity (Critical, High, Medium) and confidence (High, Med, Low).
   • Stop when a round yields zero material alterations, or at 15 rounds.
3. Lock Metric Issues: Emit the finalized, cited issue list before moving to the next metric.

Issue Record Schema:

• ID: Sequential unique identifier (ISSUE-001).
• Title: One-line concise description.
• Component & Reference: Target component and exact file:line or spec reference.
• Failure Mode: Concrete, step-by-step failure mechanism (avoid generic risks).
• Affected Metrics: Primary and secondary impacted quality attributes.
• Severity & Confidence: Graded strictly against operational blast radius.
• Scope: Testing kit, production implementation, or shared utility.

Phase 2: Root-Cause Bucketing

1. Cluster all finalized issues across all metrics into natural remediation buckets based on shared root cause.
2. Avoid fixed bucket counts; let the clustering reflect the codebase structure.
3. Rubber-duck the clusters by evaluating: "Does a single cohesive architecture or code fix resolve all issues in this bucket without forcing unrelated concerns together?"
4. Re-cluster until every issue maps to exactly one primary remediation bucket.

Phase 3: Single Production-Grade Solution Per Bucket

For each bucket:

1. Candidate Research: Identify 2 to 3 candidate solutions based on in-repo conventions, sibling modules, or upstream ecosystem best practices.
2. Adversarial Stress-Testing: Stress-test candidates against operational constraints, failure modes, and performance trade-offs. Select the single superior production-grade approach.
3. Remediation Specification:
   • Chosen architectural or implementation solution.
   • Exact mapping showing how the solution eliminates each issue in the bucket (Issue ID -> Resolution Mechanism).
   • Verifiable reference citations (file:line, spec, or upstream documentation).
   • Implementation effort, deployment risk, and potential operational trade-offs.
   • Concrete validation and testing strategy.

Phase 4: Assembly, Traceability & Final Fact-Check

1. Assemble the comprehensive review document conforming to the Deliverable Specification.
2. Build the Traceability Matrix (Issue -> Bucket -> Metric) ensuring zero orphaned or unaddressed findings.
3. Conduct a final adversarial rubber-duck pass from the perspective of a skeptical Principal Engineer:
   • Challenge every unreferenced assertion.
   • Audit severity ratings for inflation or under-estimation.
   • Verify every issue-to-mechanism resolution claim.
4. Overwrite/write the deliverable Markdown file directly to the configured output path.
5. Emit a concise completion summary reporting output path, total issue count, bucket count, and unverified assumptions.