PostMaster: The Troubleshooting Translator

Inspiration

Technical errors are usually written for machines and specialists—not for the person trying to understand what went wrong.

A developer may receive a stack trace, error code, failed system trace, or several pages of logs and still be left asking:

What actually happened?
Which details matter?
How confident should I be in this diagnosis?
What should I check next?
Could a suggested “fix” make the problem worse?

Many troubleshooting tools either return more technical information or ask an AI model to generate a confident answer from incomplete evidence. PostMaster was inspired by the need for something different: a troubleshooting translator that converts cryptic technical failures into clear, evidence-backed explanations and safer next steps.

What it does

PostMaster accepts symptoms, error messages, logs, and structured system traces and turns them into a readable diagnostic report.

A PostMaster diagnosis can include:

Issue category
Confidence and diagnostic score
Severity and risk level
Matched error patterns
Likely cause
Supporting evidence
Alternative findings
Safe next steps
Unsafe or premature actions to avoid
A structured AHP diagnostic packet for deeper inspection

PostMaster intentionally separates diagnosis from repair. It does not automatically delete files, terminate processes, reset services, or change system settings.

For OpenAI Build Week, PostMaster is being extended with GPT-5.6 CrossCheck. The deterministic engine creates the initial diagnosis, and GPT-5.6 reviews that diagnosis as an adversarial second opinion.

CrossCheck examines:

Whether the conclusion is supported by the available evidence
Which evidence strengthens or weakens the diagnosis
What assumptions remain unverified
Which alternative explanations are still plausible
What information is missing
The safest next verification step
Which actions would be unsafe or premature

The original deterministic findings remain visible and unchanged. GPT-5.6 reviews the diagnosis but does not overwrite the evidence.

How we built it

PostMaster is a TypeScript monorepo built with npm workspaces.

Its major components include:

An AHP core package for structured diagnostic packets
A deterministic classification and troubleshooting engine
A diagnostic orchestration package
A command-line application
A local web application and JSON API
An MCP server
Automated tests and reusable diagnostic fixtures

The deterministic engine runs first and remains usable without an OpenAI API key.

For the Build Week extension, Codex is being used throughout the engineering workflow to:

Inspect and map the existing repository
Identify safe integration points
Design the CrossCheck provider boundary
Create a strict structured response schema
Integrate the OpenAI Responses API
Build the CrossCheck API route and interface
Generate edge-case and failure-mode tests
Diagnose build and test failures
Review the implementation for security and hallucination risks
Improve documentation and demonstration fixtures

The key product and safety decisions remain human-directed:

Deterministic evidence must remain visible and unchanged
GPT-5.6 acts as a reviewer, not the primary classifier
AI statements must distinguish evidence, inference, and uncertainty
Diagnosis must remain separate from automated repair
PostMaster must still function without cloud AI access

Challenges we ran into

The largest challenge was adding GPT-5.6 without weakening PostMaster’s evidence-first design.

It would have been easy to replace the existing diagnosis with a model-generated answer. Instead, the deterministic and probabilistic layers needed to remain clearly separated so users could see what came from confirmed patterns and what came from AI reasoning.

Another challenge was preventing invented evidence. CrossCheck must never claim that a command was run, a file was inspected, or a condition was verified unless that evidence is actually present in the diagnostic packet.

The project also needed to handle:

Malformed model responses
Missing API credentials
Provider failures and timeouts
Unsafe recommendations
Testing without requiring paid API calls
Preserving a fully functional deterministic-only mode
Presenting complex diagnostic information in a clear product experience

Accomplishments that we're proud of

We are proud that PostMaster is more than a generic error-explanation chatbot.

It already provides a working diagnostic system with:

Deterministic classification
Evidence extraction
Confidence scoring
Severity and risk levels
Alternative findings
Safe and unsafe action guidance
Structured AHP packets
CLI, web, API, and MCP access
Automated tests and reusable fixtures

We are especially proud of the CrossCheck architecture.

Rather than treating GPT-5.6 as an unquestioned authority, PostMaster asks it to challenge the first diagnosis, expose unsupported assumptions, identify missing evidence, and recommend the safest way to verify the result.

The central idea is:

PostMaster translates the failure. GPT-5.6 checks whether the translation is justified.

What we learned

This project reinforced that AI is often most useful when it is not treated as the final authority.

Deterministic systems are strong at preserving known evidence and applying explicit rules. Language models are strong at examining ambiguity, generating alternatives, and noticing assumptions.

Combining those strengths can create a more trustworthy diagnostic experience than relying entirely on either one.

We also learned that effective use of Codex is not simply asking it to generate an application. The best results come from treating Codex as an engineering collaborator: