UnderstandGuard

Inspiration

AI coding assistants can generate large changes in seconds, but developers may accept code they cannot fully explain. This velocity introduces Cognitive Debt—code accepted into production that the author cannot debug or defend under pressure.

Traditional linters only check syntax, while passive AI pull request summaries create an illusion of understanding because developers simply skim them. We wanted to solve this by operationalizing the Flipped Interaction Method: instead of the AI passively explaining the code, the AI interviews the developer before code is merged.

What it does

UnderstandGuard is a pre-merge accountability and cognitive debt auditor for AI coding agents:

1. Diff-aware Risk Analysis: Automatically parses unified Git diffs and isolates fragile logic (async concurrency, token persistence, error fallbacks).
2. Reverse Interview: Asks 3 line-specific probing questions directly referencing line numbers and functions in the diff.
3. Real-time Vague Detection: Detects superficial, hand-waving explanations (e.g., "It handles errors gracefully") and displays an active warning alert, updating the author's comprehension score in real-time.
4. Targeted Adversarial Testing: Synthesizes a focused unit test (Vitest or Pytest) that exploits the exact edge case the author could not explain (such as concurrent 401 race conditions during token refresh).
5. Architectural Artifacts: Exports a COGNITIVE_MAP.md featuring a native Mermaid sequence diagram and an objective review verdict badge (Safe to Review vs. High Cognitive Debt – Review Required).

How we built it

• Frontend & Architecture: Built with Next.js 14 (App Router), TypeScript, and Tailwind CSS featuring a dark terminal dashboard aesthetic.
• Diff Parsing: Used parse-diff to map diff hunks and isolate changed lines.
• AI Orchestration: Powered by Google Gemini 1.5 Flash via @google/generative-ai for dynamic question generation and answer scoring.
• Reliable Demo Mode: The app supports a deterministic mock mode (?mock=true) with pre-baked fixtures for reliable demos and judge evaluation; live Gemini generation is available when an API key is configured.
• Devpost Learn Skill Pack: Developed strictly following the Devpost Learn curriculum, with scope.md, prd.md, and spec.md planning artifacts integrated into the root repository.

Challenges we ran into

• Separating Real Understanding from Buzzwords: Crafting scoring heuristics that distinguish genuine architectural reasoning from confident-sounding AI boilerplate.
• Reliable Evaluation Architecture: Ensuring the demo flow can be presented calmly and reliably without API rate limits or network hiccups by supporting both the live Gemini engine and deterministic mock fixtures.

Accomplishments that we're proud of

• Executing a focused, single-task proof of concept that solves a real developer pain point end-to-end in under 2.5 minutes.
• Delivering tangible outputs (COGNITIVE_MAP.md and adversarial Vitest assertions) that bridge the human-AI accountability gap.

What's next for UnderstandGuard

• A lightweight GitHub Action that automatically triggers the Reverse Interview as an interactive PR comment bot.
• Integration into IDE extensions (VS Code / Cursor sidecar) to interview developers right before they git commit.

Built With

• gemini-api
• google-gemini
• mermaid
• next.js
• parse-diff
• react
• tailwind-css
• typescript
• vitest