Inspiration
I work as a Senior Front-End Engineer leading distributed teams across multiple product lines. Over time I noticed a pattern that no tool was catching: developers write careful, deliberate decisions into their code — "tokens go in httpOnly cookies, never localStorage," "this cart is ephemeral by design" — and then a well-meaning PR comes in three weeks later that quietly undoes all of it.
The reviewer checks whether the code works. Nobody checks whether it still matches what the original developer meant to build.
I had already built contextify-ai, an open-source npm tool that generates .context.md files alongside code, capturing developer intent as a first-class artifact in the repo. The missing piece was closing the loop: using that intent documentation to actually gate changes at review time. IntentGuard is that missing piece.
What it does
IntentGuard takes a GitHub PR URL, fetches the diff, reads the .context.md intent files for every changed file, and uses GPT-5.6 to compare what the code now does against what the developer originally said it should do.
The output is a structured drift report — per file, with a drift score from 0–10, a verdict (aligned / minor drift / major drift), specific flags for what drifted, and a summary of what still aligns with intent.
A real example from the demo repo: a PR titled "Improve login UX and persist cart" received a Major Drift score of 8/10. IntentGuard flagged that the JWT token was moved from an httpOnly cookie to localStorage (an XSS vulnerability), rate limiting was silently removed, a "remember me" feature was added that was explicitly marked out of scope, and cart persistence was introduced against the documented ephemeral-by-design decision. A standard diff review would likely have approved this PR.
How we built it
The stack is deliberately lean for a 24-hour build:
- Next.js 14 (App Router) for the web UI and API routes
- GPT-5.6 for semantic intent-vs-diff comparison
- GitHub REST API to fetch PR diffs and read
.context.mdfiles directly from the repo - contextify-ai as the upstream tool that generates the intent files developers work with
The core prompt engineering challenge was getting GPT-5.6 to reason about semantic drift rather than syntactic differences. A diff that renames a variable is not drift. A diff that moves a secret from a server-side cookie to a client-accessible response body is major drift — even if the change is only two lines. The prompt frames this explicitly: it gives the model the stated intent, the diff, and asks it to assess alignment against documented decisions, not just describe the change.
Codex generated the GitHub API integration layer and the Next.js route scaffolding, compressing what would have been several hours of boilerplate into under two hours of directed generation.
Challenges we ran into
Getting the prompt right. Early versions of the drift analysis were too literal — flagging any new function or renamed variable as drift. The fix was grounding the prompt in decisions rather than descriptions. The .context.md format from contextify-ai already structures intent as explicit decisions and out-of-scope items, which made it possible to prompt GPT-5.6 to reason against those specifically rather than compare code structure.
Context file coverage. Not every file in a PR has a .context.md alongside it. IntentGuard handles this gracefully — files without context files still get reviewed, but the model is told there is no stated intent and flags this as a gap rather than failing silently. In practice coverage tends to be highest exactly where it matters most, since developers document auth, payments, and core data models most carefully.
Keeping the UI readable under real PR complexity. A PR touching many files generates a lot of output. The file card design — collapsed by default, expandable on click — keeps the overview scannable without hiding the detail judges and reviewers need.
Accomplishments that we're proud of
The demo scenario is not contrived. The drifted PR passes all tests, linters, and a reasonable eyeball review — and still introduces an XSS vulnerability, removes a security control, and violates two explicit scope decisions. IntentGuard catches all five violations automatically in under ten seconds.
Getting GPT-5.6 to distinguish between a legitimate refactor and a genuine intent violation — without producing false positives on every stylistic change — required real prompt iteration. The final prompt produces clean, actionable output that a developer can act on immediately.
Building a working, deployable full-stack tool in under 24 hours while keeping the codebase clean enough for judges to read is something worth noting too.
What we learned
The most important thing is that intent drift is not the same as a bug. The drifted PR in the demo works correctly — login still functions, the cart still updates. The problem is that it silently violated three documented security and scope decisions. That is exactly the class of problem that escapes automated testing, linters, and standard code review because it requires reasoning about why the code was written a certain way, not just what it does now.
GPT-5.6 handles this reasoning well when grounded in developer-authored documentation. The quality of the intent files is the ceiling on the quality of the analysis — which is an argument for investing in tools like contextify-ai that make writing those files part of the normal development workflow rather than an afterthought.
What's next for IntentGuard
The natural next step is a GitHub Action — IntentGuard running automatically as a PR check, posting its drift report as a review comment. That removes the need for the web UI entirely and puts the analysis exactly where developers already are.
A secondary direction is scoring .context.md coverage across a repo over time — surfacing which modules have no stated intent, so teams can prioritize documenting the areas that matter most before the next PR touches them.
Longer term, IntentGuard and contextify-ai together form the foundation of an intent layer for codebases — where what a developer meant to build is as queryable and enforceable as what they actually built.
Log in or sign up for Devpost to join the conversation.