SpecLock

• 

Inspiration

Software teams often make changes that seem harmless in isolation but quietly violate the requirements that define a product. A new analytics integration might expose information that should remain on-device. A seemingly simple feature might introduce a dependency that contradicts an offline-first design. These conflicts can be difficult to catch when requirements are scattered across documentation and reviews rely on intuition.

We wanted to explore a simple question: What if every proposed product change could be reviewed against explicit requirements, with evidence showing exactly why it might or might not be compatible?

That idea became SpecLock: an evidence-backed change review tool designed to make product constraints more visible, traceable, and actionable before they become implementation mistakes.

What it does

SpecLock evaluates proposed changes against a defined set of product requirements and classifies the outcome into four categories:

• Definite conflict — the proposal explicitly contradicts a requirement.
• Potential conflict — the proposal suggests a possible violation that needs further scrutiny.
• No conflicts detected — the review identifies no conflicts with the available requirements.
• Unable to assess — there is insufficient information to reach a meaningful conclusion.

Each review connects its findings to relevant requirement IDs and supporting evidence from the proposal. Instead of returning an unexplained verdict, SpecLock helps users understand which constraint is involved and what evidence supports the assessment.

The current demonstration uses a fictional product called Northstar Notes, with requirements covering local-only data, privacy-preserving analytics, offline functionality, and exclusions such as cloud synchronization and account systems.

SpecLock also supports review history and proposal revisions, making it possible to examine how a change evolves and compare a revision with its parent review.

How we built it

We built SpecLock as a web application with a React and TypeScript frontend, using a Vite-based development and production build workflow.

The central review engine uses deterministic, rule-based logic rather than relying on a live AI model or an external API. Proposed changes are evaluated against explicit baseline requirements, and findings are presented with requirement references and supporting proposal evidence.

We designed the interface around three connected areas:

1. Proposal workspace — enter a proposed product change or use a scenario to explore the review workflow.
2. Project baseline — inspect the requirements against which the proposal is evaluated.
3. Findings and evidence — understand the review outcome, associated requirements, and supporting evidence.

We also implemented review history and revision relationships, alongside a dark, developer-focused interface designed to keep the proposal, constraints, and findings visible within one workspace.

Testing and refinement were important parts of the implementation. We added regression coverage for classification behavior, improved the handling of external data transmission language, and refined the layout to make the review action and evidence easier to access.

Challenges we ran into

One of our biggest challenges was distinguishing a genuine requirement violation from language that merely sounds risky. A proposal can mention analytics, storage, or an external service without necessarily proving that a specific requirement has been violated. The review engine therefore needs to distinguish explicit conflicts from ambiguity and insufficient evidence.

We encountered a classification issue in which a proposal describing data being sent to an external service was not consistently recognized by the transmission rules. We updated the matching logic and added regression tests to help prevent the same failure from returning.

Another challenge was presenting findings in a way that makes them useful rather than mysterious. A classification without a clear connection to a requirement is difficult to verify. We focused on linking findings to requirement IDs and preserving the exact proposal text used as evidence.

We also worked to balance information density with usability. The baseline must remain readable, the primary review action must be accessible, and the findings area must communicate its purpose even before the first review is run.

Accomplishments that we're proud of

• Built a working, deterministic review engine that evaluates proposed changes against explicit product requirements.
• Implemented four distinct review outcomes to represent conflicts, potential risks, clean reviews, and insufficient information.
• Connected findings to relevant requirement IDs and supporting proposal evidence.
• Added review history and revision relationships to support traceable change evaluation.
• Created an integrated three-column workbench for proposals, baseline requirements, and findings.
• Added regression tests for a real classification bug involving external data transmission.
• Kept the core review workflow independent of external APIs, API keys, and network-dependent AI inference.

Most importantly, SpecLock is more than a screen that produces a verdict: its central design goal is to make the reasoning behind a review inspectable.

What we learned

We learned that useful change review is not just about detecting possible problems. It is also about communicating the strength of the evidence behind each conclusion.

A reliable tool must distinguish what is explicitly contradicted, what deserves further investigation, what appears compatible with the known requirements, and what cannot yet be determined. Treating these outcomes as interchangeable would create false confidence.

We also learned that traceability matters at both the product and implementation levels. Requirement identifiers, evidence, revision relationships, and regression tests help make review results easier to inspect and maintain.

Finally, we found that deterministic behavior can be valuable in its own right. For this project, predictable rules and inspectable evidence make the review process easier to test and demonstrate without implying that every ambiguous product decision can be fully automated.

What's next for SpecLock

Our next priorities are to complete end-to-end verification, strengthen coverage for ambiguous and edge-case proposals, and refine the revision comparison experience.

We also want to explore richer requirement management, clearer explanations of uncertainty, and ways to help teams incorporate evidence-backed reviews into their existing development workflows.

The long-term vision is for SpecLock to help teams catch requirement conflicts earlier, understand why a proposed change deserves attention, and preserve a traceable connection between product intent and implementation decisions.

Built With

• analysis
• css
• developer
• engineering
• html5
• javascript
• library
• privacy
• react
• rule-based
• software
• static
• systems
• testing
• tools
• typescript
• vite
• vitest