DevLens

• 

Inspiration

Every developer has felt it — you join a new codebase, open a ticket, and spend the first two hours just figuring out where to start. Documentation is either missing, outdated, or scattered across wikis, READMEs, and Slack threads. We wanted to fix that at the source: not by asking developers to write better docs, but by making the codebase document itself automatically.

What it does

DevLens is a suite of six GitLab Duo agents and flows that keep your codebase and its documentation permanently in sync — with no manual effort.

DevLens Guide is a conversational assistant that helps any developer understand the codebase instantly. Ask it about a service, the architecture, or recent changes, and it reads the actual docs and source to give you a grounded, cited answer.

DevAssist goes further. Give it an issue, MR, or work item link and it tells you exactly which files to change and why — after discovering the repo structure, reading the architecture, and tracing through the relevant source code itself.

DevLens DocCheck watches every new issue. The moment one is created, it identifies the relevant feature, surfaces the right docs and source files, and posts them as a comment to orient the developer before they even ask.

DevLens DocSync triggers whenever an MR is assigned to it. It reads the changed code, generates or updates the feature documentation, refreshes the architecture diagram, prepends a changelog entry, adds inline code comments, and opens a dedicated documentation MR — all in one automated pipeline.

DevLens DocGeneration handles the cold-start problem. When DocCheck finds that no docs exist for a feature, it asks the developer if they want docs generated. One confirmation reply later, DocGeneration scans the source, writes full structured documentation, and opens an MR.

DevLens IncidentCommander automates incident response end to end. When a pipeline fails or an incident issue is created, it diagnoses the root cause from logs and commits, searches past incidents for similar resolutions, consults the architecture to trace service dependencies, commits a hotfix, opens an MR, and posts a structured incident report — all without a human in the loop.

How we built it

DevLens is built entirely on the GitLab Duo Agent Platform. Each component is a YAML-defined agent or flow that composes GitLab's native tools — get_repository_file, list_repository_tree, gitlab_blob_search, create_commit, create_merge_request, and more — into intelligent, multi-step pipelines.

The system is designed around one principle: discover, never assume. Every agent starts by reading the actual repository structure before doing anything else. No hardcoded paths, no assumptions about folder names or file conventions. This makes DevLens work on any GitLab project out of the box.

The multi-agent flows like IncidentCommander chain specialised agents together, each passing a structured handover to the next. Diagnostician feeds Historian, Historian feeds Architect, Architect feeds Fixer, Fixer feeds Reporter — a clean pipeline where each agent does one job and does it well.

Challenges we ran into

Discovery over assumption was the hardest constraint to enforce consistently. Early versions hardcoded docs/ paths everywhere. Getting every agent to truly discover structure dynamically — and use those discovered paths for both reads and writes — required careful, systematic revision across every prompt.

Tool correctness caught us more than once. find_files is IDE-only and silently fails in ambient flows. blob_search is not a valid tool name — gitlab_blob_search is. These kinds of subtle mismatches don't throw obvious errors, they just produce agents that skip steps quietly.

Agentic reliability is inherently harder than scripting. Getting agents to consistently populate the actions list in create_commit with full inline content — rather than referencing it by name and leaving it empty — required precise prompt wording that leaves no room for interpretation.

Context window management in long multi-agent pipelines like IncidentCommander means every agent must carry the full prior context forward verbatim, or the later agents lose critical information. Designing the handover format carefully was essential.

Accomplishments that we're proud of

A fully automated documentation pipeline that requires zero configuration and works on any GitLab repository structure. DocSync can go from an MR being assigned to a complete documentation MR being opened — architecture diagram, changelog, feature docs, and inline code comments included — with no human input at all.

The IncidentCommander pipeline is something we're particularly proud of. Five specialised agents, each expert in one phase of incident response, collaborating to go from a raw failed pipeline to a committed hotfix and structured incident report — fully automated.

The system is also genuinely composable. DocCheck and DocGeneration are designed to hand off to each other naturally. DevLens Guide benefits directly from everything DocSync and DocGeneration produce. The flows reinforce each other.

What we learned

Prompt engineering for agentic systems is a fundamentally different discipline from prompt engineering for chat. You are not writing instructions for one conversation — you are writing a specification for a process that must be reliable, deterministic enough to produce consistent structure, and robust to ambiguity in the input.

The most important lesson: vagueness is a bug. Phrases like "generate the content" or "include the relevant files" sound clear to a human but give an LLM just enough room to skip the step. Every instruction that involves producing output needs to say exactly where that output goes and in what form.

We also learned that a well-designed tool list is part of the prompt. Every tool in the toolset is an implicit permission. Tools that don't belong — like find_files in an ambient flow — create surface area for failure.

What's next for DevLens

Smarter scope detection — moving beyond conventional commit format to infer feature scope from changed file paths, labels, and issue content, so DocSync works even on repos that don't follow a commit convention.

Cross-repository support — extending DevAssist and DocCheck to work across a GitLab group, not just a single project, for teams with microservice architectures split across multiple repos.

Documentation quality scoring — a flow that periodically audits the docs folder, compares it against the current source, and opens issues for docs that are stale, missing, or inconsistent with the code.

Two-way IncidentCommander — closing the loop by automatically updating the changelog and architecture docs after a hotfix is merged, so incidents leave the codebase better documented than they found it.

Built With

• claude
• gitlab
• gitlabduo