subhopam das closed issue #5: Write a compelling README with demo screenshots/GIF at GitLab AI Hackathon / Participants / kapillamba4

subhopam das
2026-03-20T01:41:07Z

Priority: 🟡 High (First impression for judges)

The current README just says "For instructions on how to get started take a look at the onboarding issue". This is the first thing judges see. It needs to sell the project.

What the README should include

Hero section: "GitLab Oracle" name, one-line tagline ("Instant answers about why your code exists"), badges (pipeline status, license)

Problem statement: The Chesterton's Fence problem condensed to 3-4 sentences (from Problem.md)

Demo GIF/screenshot: Show the Oracle answering a question on an MR comment thread. This is the single most impactful thing.

How it works: 3-step visual explanation:

Ingest - Indexes merged MRs, discussions, diffs, commits, and linked issues

Embed - Generates vector embeddings using sentence-transformers + pgvector

Query - Semantic search with multi-factor ranking (similarity, recency, discussion depth, source type)

Architecture diagram: Simplified version of the one in ARCHITECTURE.md

Key features:

RAG pipeline over GitLab project history

Multi-factor ranking (40% similarity, 20% recency, 20% discussion depth, 10% source type, 10% resolution)

GitLab Duo Agent Platform integration (custom agent + flow)

Automatic MR comment callback

Issue and MR cross-referencing

Tech stack: GitLab Duo Agent Platform, FastAPI, pgvector, sentence-transformers, python-gitlab

Quick start: How to deploy and configure

GitLab Duo integration: How to trigger via @oracle mention

Bonus points

Link to the AI Catalog listing

Include 2-3 example Q&A pairs showing real answers

Add a "Why this matters" section with the metrics from Problem.md (68% of devs fear modifying unfamiliar code, 15-25% of dev time on legacy code)