| Field | Value |
|---|---|
| Product | LeanCI |
| Tagline | Deep AI PR review that was previously too expensive to run on every PR |
| Document type | Product Requirements Document (PRD) |
| Status | Draft v1.0 — approved for planning; no implementation yet |
| Owner | Product / Architecture (hackathon team) |
| Last updated | 2026-07-30 |
| Primary event context | Build with Paritok (submit by 2026-08-05 12:00am PDT) |
| Related strategy | Compression-native agentic PR review (LeanCI) |
LeanCI is a GitHub Action + backend AI agent that performs dependency-aware pull request reviews. Unlike tools that primarily summarize or lint the diff, LeanCI expands review context to changed files, imports, call sites, tests, and related modules, routes that context through Paritok for measured token compression, then runs an agentic review against an upstream LLM.
The product’s core bet is economic, not rhetorical: deep, multi-file AI review becomes affordable on every PR because Paritok cuts input tokens (~74% on coding-agent workloads) while preserving paths, symbols, and errors that matter for code understanding.
Hackathon MVP ships a working Action, a live demo monorepo with a planted cross-file bug, a cost receipt (uncompressed vs compressed), and proof that the same high-severity finding is caught on both paths. Stretch goals include budget ceilings, multi-language support, and org-level economics dashboards.
Positioning one-liner: Competitors sell smarter comments; LeanCI sells viable cost-per-finding for dependency-aware agentic review.
Human reviewers cannot deeply read every PR. AI review tools fill the gap, but most either:
- Stay shallow — comment on the diff hunk without tracing callers, callees, shared types, or tests; or
- Go deep and burn money — agentic review that
read_files across the repo on every PR quickly becomes too expensive for high-velocity teams.
Modern coding agents send large tool schemas, file reads, and accumulating history every turn. For PR review that intentionally expands beyond the diff, input tokens dominate cost. Teams respond by:
- Disabling deep review on small PRs
- Sampling only some PRs
- Accepting shallow diff-only review
- Paying seat-based SaaS without visibility into cost per finding
Industry signal: GitHub’s own agentic workflows required systematic token audits and optimizations (tool pruning, CLI vs MCP, daily auditor/optimizer loops) to cut spend on the order of ~37–62% on instrumented workflows. Cost is a first-class production constraint, not an afterthought.
Blind prompt compression can drop paths, identifiers, and error strings that code review depends on. Generic compressors are weak on coding-agent trajectories. Paritok is purpose-trained for those trajectories and retains solve quality on SWE-bench-style workloads while compressing hard — making it a fit for review agents that must keep symbols intact.
Engineering teams need dependency-aware AI code review on every PR, but the token cost of expanding to call sites, imports, and tests makes deep agentic review economically impractical. Existing tools optimize review UX or seat price, not measured cost-per-review with load-bearing context compression.
| Segment | Why they care |
|---|---|
| Startup / scale-up engineering teams on GitHub | High PR volume; cannot afford human depth on every change; sensitive to API spend |
| Platform / DevEx engineers | Own CI cost, Actions minutes, and AI tooling standards |
| Security-conscious product teams | Want cross-file defect detection (authz, data flow) without enterprise AI review bills |
| Segment | Why they care |
|---|---|
| Open-source maintainers | Want deep review on contributor PRs within a hard budget |
| Regulated / self-hosted teams | Prefer Action + own keys + optional self-hosted Paritok over opaque SaaS |
| Monorepo /gs | Deep review without full-repo RAG tax on every PR |
- Teams that only want PR summaries / changelog generation
- Non-GitHub VCS (GitLab/Bitbucket) in MVP
- Non-technical stakeholders as primary operators
- Context: Reviews 8–15 PRs/day; misses cross-module regressions
- Goals: Catch broken contracts between packages; reduce review latency
- Pain: AI tools nitpick style; miss “caller still uses old enum”
- Success: High-signal comments with file:line citations; few false alarms
- Context: Owns GitHub Actions, Copilot/AI spend, CI budgets
- Goals: Standardize AI review org-wide without surprise bills
- Pain: Seat pricing and opaque token burn; no cost-per-finding metrics
- Success: Dashboard/receipts showing $/PR and token reduction; hard caps
- Context: 12 engineers, fast shipping, thin review culture
- Goals: Safety net for junior PRs without hiring more seniors
- Pain: CodeRabbit-class spend feels heavy; Copilot review feels shallow
- Success: “Deep enough” review at a fraction of naive agent cost
- Context: Volunteer time; noisy contributor PRs
- Goals: Overnight/CI review within fixed monthly API budget
- Pain: Agentic tools blow budget on large diffs
- Success: Budget-aware deep review that still catches real bugs
When a pull request is opened or updated, I want a dependency-aware AI review that understands how my change affects callers, imports, and tests, so I can merge faster without missing cross-file bugs — without paying full-context agent prices.
| Job | Outcome |
|---|---|
| Expand context beyond the diff | Related files included by graph/heuristic, not vibes alone |
| Compress context safely | Token reduction measured; critical symbols retained |
| Produce actionable findings | Severity, rationale, file:line, optional suggested fix |
| Prove economics | Show uncompressed vs compressed cost on every run |
| Prove quality | Same planted/high-severity issue caught under compression |
| Fit existing workflow | Native GitHub Action; comments on the PR |
| Stay operable | Fail soft on tool errors; never block merge unless configured |
AI code review moved from novelty to default infrastructure (tens of millions of Copilot reviews; dedicated vendors at scale). Buyers now compare depth, noise, integrations, and total cost of ownership — seat fees plus underlying model/Actions usage.
- Agentic review (tool-calling, multi-file reads) is becoming expected — and expensive.
- FinOps for AI agents is emerging (proxies, budgets, daily auditors).
- Context compression is shifting from research (LLMLingua) to coding-agent-native middleware (Paritok).
- Teams want evidence: not “we save tokens,” but $/review and finding parity.
| Existing emphasis | Missing emphasis |
|---|---|
| Comment quality / UX | Cost-per-finding as hero metric |
| Seat SaaS | Compression-native self-hosted/Action path |
| Diff + linters + light graph | Explicit dependency expansion + measured Paritok savings |
| Post-hoc usage audits | In-band compression on every review turn |
LeanCI occupies: compression-native, dependency-aware, economics-first agentic PR review.
Pricing and features change frequently; figures below are directional (mid-2026 public comparisons) for positioning, not contractual quotes.
| Product | Primary promise | Strengths | Weaknesses vs LeanCI |
|---|---|---|---|
| CodeRabbit | Dedicated deep PR review | Strong recall, multi-SCM, linters, configurability; ~$24/user/mo Pro | Seat-centric TCO; not positioned as Paritok-style measured compression middleware; opaque model path |
| GitHub Copilot Code Review | Convenient native review | Bundled with Copilot; zero setup; high volume | Usage/credits + Actions costs; less “economics-first”; depth/config vary by plan |
| Greptile | Codebase-aware review | RAG over repo; good for large codebases | Still RAG/token heavy; not compression-native |
| Ellipsis / Sourcery / others | Summaries, language-specific nits | Easy adoption | Shallower dependency reasoning |
| Cursor Bugbot / IDE agents | Dev-time bug finding | Strong in-editor loop | Not CI-native org standard for every PR |
| DIY agent + BASE_URL | Full control | Flexible | No productized expansion policy, receipts, or Action UX |
| Paritok alone | Compress coding-agent context | Best-in-class agent compression | Not a review product |
- Beat CodeRabbit on: transparent cost-per-review, open Action architecture, Paritok-attributed savings, hackathon-visible economics.
- Beat Copilot Review on: explicit dependency expansion policy + compression receipts as first-class artifacts.
- Do not try to beat on: day-one language coverage, 40+ linters, multi-SCM — out of MVP scope.
LeanCI is the only PR review approach designed so that dependency expansion is default and Paritok compression is load-bearing infrastructure, with cost-per-finding as the primary product metric.
Compression-native agentic code review (CI / GitHub Actions)
For GitHub engineering teams who need cross-file confidence on every PR, LeanCI is a dependency-aware review Action that compresses agent context with Paritok so deep review stays economically feasible. Unlike seat-priced review SaaS or diff-only Copilot comments, LeanCI makes cost-per-review and finding parity visible on every run.
- Deep by default — expand to related code, not just the hunk
- Lean by design — Paritok is required infrastructure, not a badge
- Honest metrics — measured tokens/cost; no vanity compression claims
- CI-native — ships where merge decisions happen
Make dependency-aware AI PR review cheap enough to run on every pull request.
| Prop | Proof in product |
|---|---|
| Cross-file bug detection | Planted bug spanning changed file + caller/test is found |
| Measured savings | Receipt: tokens/cost with vs without Paritok |
| Quality under compression | Same severity finding on compressed path |
| Operational simplicity | One Action + secrets; comment posted to PR |
| Founder/practitioner credibility | Uses coding-agent trajectories the way Paritok was trained |
- “Replaces human review”
- “100% false-positive free”
- “Works perfectly on all languages on day one”
- Compression savings without measurement
Requirements are tagged: P0 = MVP, P1 = stretch for hackathon if time, P2 = post-hackathon.
| ID | Requirement | Priority |
|---|---|---|
| FR-1 | Run on pull_request events (opened, synchronize, reopened) via GitHub Action |
P0 |
| FR-2 | Support manual workflow_dispatch for demo/repro |
P0 |
| FR-3 | Idempotent re-review on new pushes (update or post new review comment per policy) | P0 |
| FR-4 | Optional path filters / skip labels (e.g. leanci:skip) |
P1 |
| ID | Requirement | Priority |
|---|---|---|
| FR-10 | Collect changed files from the PR diff | P0 |
| FR-11 | Expand to imports/dependencies referenced by changed files (language-appropriate heuristic) | P0 |
| FR-12 | Expand to call sites / reverse references within a bounded search (e.g. ripgrep/symbol heuristic) | P0 |
| FR-13 | Expand to related tests (naming/convention + import edges) | P0 |
| FR-14 | Enforce hard caps: max files, max bytes, max tool turns | P0 |
| FR-15 | Prefer AST/precise graph over regex when available | P1 |
| FR-16 | Incremental review: only re-expand delta since last commit | P2 |
| ID | Requirement | Priority |
|---|---|---|
| FR-20 | Agentic loop with tools: list/read files, search repo, optional test metadata read | P0 |
| FR-21 | All LLM-bound agent traffic routed through Paritok (hosted GPU server for hackathon) | P0 |
| FR-22 | Produce structured findings: severity, title, file, line (if known), rationale, optional fix sketch | P0 |
| FR-23 | Focus categories: correctness, regressions, API contract breaks, security footguns, missing tests | P0 |
| FR-24 | Suppress pure style/nits unless configured (default: high-signal only) | P0 |
| FR-25 | Dual-run mode for demo: uncompressed baseline vs Paritok path (measurement) | P0 |
| FR-26 | Single-run production mode: Paritok-only (no double spend) | P1 |
| ID | Requirement | Priority |
|---|---|---|
| FR-30 | Record original vs compressed input tokens (Paritok /stats and/or provider usage) |
P0 |
| FR-31 | Estimate USD cost using documented model rates; label assumptions | P0 |
| FR-32 | Publish a Cost Receipt on the PR (comment or check summary) | P0 |
| FR-33 | Metrics: cost/review, cost/finding, token reduction %, latency | P0 |
| FR-34 | Optional hard budget ceiling (abort gracefully with partial results) | P1 |
| FR-35 | Export JSON artifact of metrics for CI | P1 |
| ID | Requirement | Priority |
|---|---|---|
| FR-40 | Post PR comment summarizing findings + receipt | P0 |
| FR-41 | Inline review comments when line mapping is confident | P1 |
| FR-42 | GitHub Check Run with pass/fail policy (default: neutral/success even with findings) | P1 |
| FR-43 | Link to run logs / raw JSON findings | P0 |
| ID | Requirement | Priority |
|---|---|---|
| FR-50 | Configure via Action inputs + repo secrets (PARITOK_API_KEY, provider key, GITHUB_TOKEN) |
P0 |
| FR-51 | Never echo secrets in logs or PR comments | P0 |
| FR-52 | Apache-2.0 license; credit Paritok in README | P0 |
| FR-53 | .leanci.yml policy file (severity, path allow/deny, severity threshold) |
P1 |
| ID | Requirement | Priority |
|---|---|---|
| FR-60 | Public demo monorepo with planted cross-file bug | P0 |
| FR-61 | Automated assertion: compressed path finds planted bug | P0 |
| FR-62 | Side-by-side token/cost comparison in demo output | P0 |
| FR-63 | ≤3 minute demo video script support (clear narrative beats) | P0 |
| ID | Category | Requirement | Priority |
|---|---|---|---|
| NFR-1 | Performance | MVP review completes within 8 minutes p95 for demo-sized PR (≤15 files expanded) | P0 |
| NFR-2 | Performance | Target ≤3 minutes for typical small PR after optimization | P1 |
| NFR-3 | Reliability | Action fails soft: posts error comment; does not crash the workflow job unnoticed | P0 |
| NFR-4 | Accuracy | Planted-bug catch rate 100% on demo suite (compressed path) | P0 |
| NFR-5 | Economics | Demonstrate ≥50% input-token reduction vs uncompressed dual-run on demo PR (stretch ≥70% if workload matches Paritok’s sweet spot) | P0 |
| NFR-6 | Security | Least-privilege pull-requests: write, contents: read; no persistent storage of private code beyond job logs |
P0 |
| NFR-7 | Privacy | Hackathon demo uses public repos; document private-repo threat model | P0 |
| NFR-8 | Observability | Every run emits machine-readable metrics JSON | P0 |
| NFR-9 | Portability | Linux Action runner; Python 3.11+ agent | P0 |
| NFR-10 | Usability | New user can install Action and get a review with ≤10 minutes setup | P0 |
| NFR-11 | Compliance | Clear disclosure that AI may be wrong; humans remain merge authority | P0 |
| NFR-12 | Cost control | Dual-run measurement mode must be opt-in outside demos (avoid 2× spend) | P1 |
Developer opens/pushes PR
→ GitHub Action starts LeanCI job
→ Checkout PR head
→ Collect diff + expand dependency set (capped)
→ Start/connect Paritok (hosted GPU)
→ Agent reviews via tools (reads/search) through Paritok → upstream LLM
→ (Demo mode) optional uncompressed baseline measurement run
→ Aggregate findings + cost receipt
→ Post PR comment (+ optional check)
→ Upload metrics artifact
Developer reads findings, fixes or dismisses, merges
Add workflow YAML from template
→ Set repo secrets (Paritok + LLM provider)
→ Open test PR on demo or real repo
→ Verify comment + receipt appear
→ Tune severity / path filters
Open Actions run summary / PR receipt
→ See tokens original vs compressed, $ estimate, findings count
→ Compute cost/finding
→ Decide to enable on more repos or set budget cap
Paritok or LLM error / budget exceeded / expansion empty
→ Capture error class
→ Post “LeanCI could not complete” comment with next steps
→ Exit non-zero or neutral per config (default: fail job for visibility in hackathon; soft in prod policy)
Open demo PR link
→ See planted bug finding cited with file:line
→ See cost receipt with Paritok attribution
→ Optionally open dashboard/stats proof
→ Watch ≤3 min video walking the same path
| Metric | Definition | MVP target |
|---|---|---|
| Cost per review | Estimated USD for the Paritok-path review (input-dominated; state assumptions) | Show clear reduction vs uncompressed baseline on same PR |
| Cost per finding | Cost per review / count of P0–P1 findings | Lower than uncompressed path at equal finding set |
| Token reduction % | 1 - compressed_input / original_input on agent turns Paritok touches |
≥50% on demo PR; aspire to ~70%+ on tool-heavy runs |
| Finding quality | Precision/recall proxy via planted bugs + manual rubric | 100% recall on planted cross-file bug; ≤2 low-value nits on demo |
| Latency | Wall time Action start → comment posted | ≤8 min demo; track distribution |
| Metric | Definition |
|---|---|
| Files expanded | Count and bytes of context included beyond diff |
| Tool turns | Agent steps until completion |
| Inline mapping rate | % findings with confident line comments |
| Error rate | % runs ending in failure comment |
| Judge demo clarity | Blind test: stranger understands value in ≤3 min video |
LeanCI is successful for the hackathon if judges can answer yes to all:
- Is Paritok load-bearing (not a bolt-on)?
- Is there measured token/cost reduction?
- Is the review dependency-aware (not diff-only)?
- Would a real team understand why to adopt this?
- Does it actually run end-to-end?
- GitHub Action workflow template
- Backend/agent service or in-runner agent (Python) with tool loop
- Dependency expansion for one primary language (recommend Python or TypeScript; pick one for MVP)
- Paritok hosted GPU integration (
use_gpu_server/ BASE_URL pattern) - Upstream LLM via OpenAI-compatible or Anthropic API through Paritok
- PR comment: findings + cost receipt
- Dual-run measurement mode for demo
- Public demo monorepo + planted cross-file bug
- README with setup, Apache-2.0, Paritok credit/badge
- Metrics JSON artifact
- Demo video script alignment (≤3 minutes)
- GitLab/Bitbucket
- Full precise call graph for all languages
- Autofix PRs / apply patches
- Seat billing, multi-tenant SaaS control plane
- Learning from emoji reactions
- 40+ linters bundle
- Guaranteed security certification
- Always-on dual-run in “production” mode
| Stretch | Description | Why |
|---|---|---|
| S1 | Second language expansion (TS ↔ Python) | Broadens demo credibility |
| S2 | Inline GitHub review comments | Stronger UX |
| S3 | Hard budget ceiling with partial results | FinOps story |
| S4 | .leanci.yml policy pack |
Configurability vs CodeRabbit narrative |
| S5 | Org rollup script for cost/finding across repos | DevEx persona love |
| S6 | Content-addressed cache of compressed file segments across PRs | Portfolio token savings (advanced) |
| S7 | Paritok GitHub issues with reproducers | Judging bonus |
| S8 | Check Run gating on severity | Enterprise-ish |
- Paritok is available via hosted GPU with API key; dashboard attributes usage for verification.
- Paritok behaves as middleware: compresses tool results/history/schemas; upstream LLM still required.
- Hackathon submission requires public GitHub repo, Apache-2.0, live or reproducible demo URL, Paritok account email on Devpost.
- MVP language tooling assumes standard layouts (
src/,tests/, package imports) sufficient for heuristic expansion. - GitHub-hosted runners can reach Paritok + LLM APIs; secrets configured by user.
- Dual-run doubles LLM spend — acceptable for demo only.
- “Dependency-aware” MVP = bounded heuristic expansion, not perfect program analysis.
- Finding line numbers may be approximate when reading compressed context; prefer citing path + symbol when unsure.
- Team can complete MVP in remaining hackathon window (~days, not weeks).
- Judges are Paritok founders; measured compression on coding-agent workflows outweighs generic AI polish.
| Risk | Impact | Likelihood | Mitigation |
|---|---|---|---|
| Perceived as “another AI reviewer” | Loses originality vs CodeRabbit | High | Hero = receipt + cross-file planted bug; messaging is economics-first |
| Paritok integration issues (auth silent pass-through, API quirks) | Fake savings / failed demos | Medium | Health checks; fail if compression ratio ~= 1.0 unexpectedly; learn from Segpilot findings |
| Compression drops critical symbol → miss bug | Quality failure | Medium | Planted-bug gate; severity-focused prompts; allow expand_context usage; keep recent window uncompressed if needed |
| Scope creep (multi-language, SaaS) | Nothing ships | High | One language; Action-only; freeze stretch until P0 green |
| Dual-run cost / latency | Slow demo, $$ burn | Medium | Cache expansion set; limit turns; run dual-run only on demo workflow |
| Noisy findings | Judge distrust | Medium | Default high-signal rubric; max N findings posted |
| GitHub API rate limits | Flaky Action | Low | Minimize API calls; reuse checkout |
| Competitor Traceback confusion | Narrative bleed | Low | Clear CI/PR category; never paste-stack-trace positioning |
| Private code leaving runner | Security concern | Medium | Document data flow; public demo for hackathon |
| Timeboxed calendar (due Aug 5) | Incomplete submission | High | Vertical slice first: one PR, one bug, one receipt |
Title: “The cross-file bug you can’t see in the diff — reviewed at 1/3 the token cost.”
- Demo monorepo: small service with
payments/charge.py(changed) andapi/checkout.py(caller) + test that doesn’t cover the mismatch. - Planted bug: PR updates validation helper return semantics; caller still assumes old behavior → money/path error. Diff alone looks plausible.
- Open PR showing “innocent” diff.
- Action runs LeanCI (badge in progress).
- Comment appears:
- Finding: caller/contract break with file:line citations for both files
- Cost receipt: uncompressed tokens/$ vs Paritok tokens/$ and % saved
- Expansion summary: N files beyond diff (list)
- Optional: show Paritok dashboard/stats attribution.
- Video voiceover ties to: “Deep review only pencils out because compression is in the loop.”
- Planted bug found on Paritok path
- Receipt shows material token reduction
- Judges never need to run code locally (but repo is reproducible)
- AC-1: On a sample PR, LeanCI posts a review comment automatically via GitHub Action.
- AC-2: Expansion includes ≥1 non-diff file that is a caller, import, or test related to the change.
- AC-3: Agent traffic for the review path uses Paritok; usage attributable to hackathon Paritok account.
- AC-4: Cost receipt shows original vs compressed input tokens and estimated USD for the demo PR.
- AC-5: Token reduction on demo PR is ≥50% or documented explanation with still-positive savings if workload is short-context (must not claim fake %).
- AC-6: Planted cross-file bug is reported with rationale referencing both sides of the dependency.
- AC-7: Dual-run (or equivalent) shows finding parity for the planted bug on compressed path.
- AC-8: README enables a stranger to run the Action on the demo repo with documented secrets.
- AC-9: Repo is public, Apache-2.0, credits Paritok with required link/badge.
- AC-10: Metrics JSON artifact uploaded for the demo run.
- AC-11: End-to-end demo completable in ≤8 minutes wall time on demo PR.
- AC-12: No secrets appear in PR comments or public logs.
- AC-H1: Devpost submission includes project URL, repo, Paritok email, description emphasizing how Paritok was used, and ≤3 min demo video.
- AC-H2: Video explicitly shows measured savings + dependency-aware finding (not only a chatbot).
- AC-H3: (Bonus) ≥1 actionable Paritok GitHub issue filed with repro.
- Diff-only LLM summary without expansion
- Paritok mentioned only in README without runtime integration
- Unmeasured “we probably saved tokens” claims
- Style-only nitpicking as the primary output
- MVP language: Python vs TypeScript?
- Agent host: in-runner only vs small hosted API (Render/Fly) for demo stability?
- Upstream model default for hackathon (Claude vs GPT vs Gemini via OpenAI-compatible)?
- Dual-run always-on for demo workflow only — confirm to avoid accidental 2× prod spend.
- Branding: keep LeanCI or finalize alternate public name before Devpost?
| Version | Date | Notes |
|---|---|---|
| 1.0 | 2026-07-30 | Initial PRD from locked LeanCI concept; no implementation |
End of PRD.
Next expected artifact (on request only): technical design / implementation plan — not code.