SpecGuardian

• 

  agent-chat

Inspiration

SpecGuardian came from a frustration we kept seeing in open source and team projects: lots of fast commits, lots of “AI slop,” and too many pull requests that looked complete but missed what the issue actually asked for. We wanted to stop the cycle of shipping code that passes checks but fails intent, because that creates rework, confusion, and burnout for maintainers. The core motivation was simple: if contributors are giving real effort, their work should map to real requirements, not just generate diff noise.

What it does

SpecGuardian verifies intent-to-implementation alignment for merge requests. It reads the linked issue (including comments where requirements often change), analyzes what the code in the MR actually does, then compares both sides and reports where things are aligned, misaligned, missing, ambiguous, or out of scope. Instead of replacing code review, it improves it by surfacing requirement gaps first, so reviewers can focus on quality after correctness is confirmed. In short, it catches “not what we asked for” before merge and deployment.

How we built it

We built SpecGuardian through a lot of structured discussion, whiteboarding, and iterative brainstorming around real contributor pain points. The system became a 3-step pipeline: requirement extraction, implementation analysis, and alignment verification. We designed each step to stay focused on one responsibility, then chained them into an automated flow that can run on merge request triggers. Along the way, we used practical examples from our own project history to tune how the output should look: specific, actionable, and easy for developers to fix quickly.

Challenges we ran into

The hardest part was turning messy human intent into something machine-verifiable. Requirements are not always clean; they evolve in comments, conflict with earlier notes, or leave ambiguity that can be interpreted multiple ways. We also had to deeply read research papers and connect theory to real SDLC value, which took serious time and debate. Another challenge was balancing strictness and usefulness: too strict and the tool becomes noisy, too loose and it misses costly misalignment. Getting that tradeoff right required multiple rounds of brainstorming, failure cases, and refinement.

Accomplishments that we're proud of

We are proud that SpecGuardian moves beyond basic linting or style checks and tackles a high-impact problem that many teams silently accept. We created a workflow that can produce clear alignment reports with meaningful categories and severity, giving teams a practical way to reduce rework before merge. We are also proud of the product framing: this is not “more review overhead,” it is a way to protect developer time and maintainer trust. Most importantly, we turned a common open-source pain into a repeatable process teams can actually use.

What we learned

We learned that requirement drift is not a rare edge case, it is a default state in collaborative software work. We also learned that comments and discussion threads often contain the most important updates, so any serious verification tool must treat them as first-class inputs. From a systems perspective, decomposition mattered: separating extraction, analysis, and verification made the pipeline easier to reason about and improve. We also learned that useful AI in engineering is less about “generate more code” and more about reducing costly mistakes. If $C_{late}$ is the cost of finding an issue late and $C_{early}$ is the cost of finding it in review, our goal is to keep teams in the zone where $C_{late} \gg C_{early}$ never becomes their default reality.

What's next for SpecGuardian

Next, we want to make SpecGuardain more adaptive and team-aware by learning project-specific requirement patterns, terminology, and risk thresholds over time. We plan to improve ambiguity handling so it can propose clarification questions before code review stalls, and to add tighter feedback loops that help contributors resolve gaps faster. We also want richer analytics to show trend-level impact, like reduced rework and faster alignment across releases. Longer term, we see SpecGuardain as a reliability layer across the SDLC: not just catching mismatches in merge requests, but continuously improving how teams define, discuss, and deliver intent at scale.

Built With

• agents
• ai
• duo
• gitlab