Gokul Rajaram Proposes ProductSpec Open Standard For AI-Readable Intent

GR

Gokul Rajaram@gokulrTECH

DECISION TRACE: OPEN STANDARD FOR AUDIT TRAILS Decision Trace has now added to the open source ProductSpec project. (links in comments) The reason is simple: specs drift. A team writes a product spec. Engineering starts building. A workaround ships. A test codifies behavior nobody wrote down. A prototype changes. An AI eval threshold moves. A success metric gets instrumented differently. Some of these are good decisions. Some are accidental drift. Either way, the original Product Spec no longer tells the full story. The ProductSpec standard captures committed intent: what problem we are solving, what the hypothesis is, what is in scope, what must pass before launch, and what success should look like after launch. Decision Trace captures what happens after intent meets reality. It records: • what changed • why it changed • who approved it • what evidence existed • what drift was detected • whether the team updated the spec, updated the implementation, accepted the tradeoff, or reopened the work The loop is: Intent → Implementation → Drift → Decision → Revised Intent That last step matters. The spec should not be silently overwritten by whatever shipped. Accidental behavior should not become intent by default. The implementation also cannot be ignored. Code is reality. Tests are reality. Shipped UX is reality. Analytics are reality. Eval runs are reality. The useful layer is reconciliation. Decision Trace is the audit trail for that reconciliation. It is not a section inside ProductSpec. It is an optional companion standard. ProductSpec says what the team currently intends. Decision Trace explains how that intent changed over time. A typical repo can now look like this: specs/checkout-redesign.product-spec.md specs/checkout-redesign.decision-trace.json The open source project now includes: • ProductSpec: the open standard for software intent before implementation • Decision Trace: the companion standard for decisions, drift, revisions, and outcomes • JSON Schema for Decision Trace • A working example trace • Parser and validation tests that keep the format real Builders: if you care about specs, agents, GitHub-native workflows, AI evals, product decisions, or keeping intent and implementation in sync, please contribute.