orbit-scribe

Inspiration

Every merge request contains valuable engineering knowledge: design decisions, rejected approaches, reviewer feedback, implementation tradeoffs, and operational considerations. Unfortunately, most of that context disappears after the merge. Months later, teams often find themselves asking the same questions: Why was this implemented this way? What alternatives were considered? What assumptions were made?

We were inspired by the idea that repositories should preserve not only code, but also the reasoning behind the code. Orbit-Scribe was created to capture institutional knowledge at the moment it is generated and make it a permanent part of the development lifecycle.

What it does

Orbit-Scribe is a GitLab Duo agent that automatically converts merged Merge Requests into structured, searchable documentation.

When a merge request is assigned to Orbit-Scribe and completed, the agent:

Retrieves the MR diff
Reads reviewer comments and discussions
Collects linked issue context
Reviews pipeline results
Generates a structured changelog entry
Creates a developer-friendly explanation of the change
Commits the generated documentation back into the repository
Posts a comment on the merge request with links to the documentation
Notifies the team through Slack

The result is a self-documenting codebase that continuously accumulates knowledge without requiring developers to perform additional documentation work.

How we built it

Orbit-Scribe was built on GitLab's Agent Platform and GitLab Duo capabilities.

Our workflow consists of several stages:

Event Detection – The agent is assigned to a merge request and monitors merge events.
Context Collection – It gathers diffs, MR discussions, linked issues, metadata, and pipeline information.
Knowledge Extraction – An LLM analyzes both the code changes and human discussions to identify key decisions, implementation details, and reviewer insights.
Documentation Generation – The agent produces structured markdown documentation including summaries, rationale, risks, and maintenance notes.
Repository Integration – Generated files are committed directly into the repository under version control.
Team Communication – Slack notifications and MR comments provide immediate visibility to stakeholders.

By storing documentation alongside the source code, we ensure that project knowledge evolves with the codebase rather than becoming fragmented across external systems.

Challenges we ran into

Distilling meaningful context

Merge request discussions often contain side conversations, suggestions, and iterative feedback. Separating important engineering decisions from conversational noise was one of our biggest challenges.

Generating useful documentation

We wanted documentation that engineers would actually read. Finding the balance between comprehensive explanations and concise summaries required multiple iterations of prompting and document structure.

Preserving reviewer insights

Reviewer comments often contain the most valuable institutional knowledge. Capturing those insights accurately while avoiding duplication or unnecessary verbosity was a difficult problem to solve.

Seamless workflow integration

Developers already deal with many tools and processes. We needed Orbit-Scribe to operate automatically without creating additional friction or requiring manual intervention.

Accomplishments that we're proud of

Built a fully autonomous GitLab Duo agent that transforms merge requests into documentation.
Successfully combined code diffs, reviewer discussions, issue context, and pipeline data into a single knowledge source.
Automated the entire documentation workflow with zero developer effort.
Stored generated documentation directly in repositories, making it version-controlled and discoverable.
Created a system that helps preserve institutional knowledge and reduces future onboarding and maintenance costs.
Integrated team notifications through Slack to keep documentation visible and actionable.

What we learned

One of our biggest realizations was that documentation problems are often knowledge-capture problems.

Teams usually understand their systems while changes are being reviewed, but that understanding fades over time. Capturing context at merge time proved far more effective than expecting developers to document decisions later.

We also learned that reviewer discussions contain significantly more architectural and operational context than code diffs alone. Combining both sources produces much richer documentation than analyzing code changes in isolation.

Finally, we gained valuable experience building AI-powered developer tooling that fits naturally into existing workflows instead of requiring behavior changes from engineers.