How IssueLift Works
IssueLift prepares a contributor before they touch code. It does not write code, auto-generate pull requests, or flood maintainers with bot comments.
By compiling an open issue into an evidence-backed Contribution Contract and Acceptance-to-Test TraceMap, newcomers know exactly what "done" means before spending hours coding.
The 5-Step Pre-Implementation Journey
A transparent workflow bridging GitHub discussions to verified test evidence.
Paste Any Public GitHub Issue URL
Enter a public GitHub issue link (e.g. https://github.com/facebook/react/issues/1000). IssueLift validates the URL structure, ensures it is an open issue rather than a pull request, and initializes a bounded scan context.
Fetch Issue & Bounded Repository Context
IssueLift connects to public GitHub REST endpoints to retrieve issue title, body, state, assignees, author, comments, default branch, repository tree manifest, and setup documentation (README.md, CONTRIBUTING.md).
Gemma 4 Proposes Criteria & Explanations
Google Gemma 4 (gemma-4-26b-a4b-it) processes the untrusted issue body, extracts verbatim acceptance quotes, identifies implicit ambiguities, and synthesizes candidate criteria and maintainer questions conforming to a strict Zod schema.
Deterministic Claim Gate Verifies Path Integrity
Deterministic code validates that every file path suggested by Gemma 4 actually exists in the fetched repository tree. Nonexistent paths are rejected, and TraceMap maps criteria to verified source files, candidate tests, and commands.
Review, Edit Contract & Export Proof Bundle
You inspect the compiled Contribution Contract, edit criteria in-memory, copy a respectful maintainer clarification comment, and download a verifiable Proof Bundle (.md or .json) before writing a single line of code.
Data Flow: From Untrusted Input to Verified Proof
Validates public issue URL. Rejects PRs and invalid hosts. Queries GitHub REST API for issue + repo tree.
Gemma 4 processes issue text with prompt-injection defense. Proposes criteria and maintainer questions via Zod schema.
Claim Gate checks every path against git tree. Drops hallucinated paths to UNKNOWN and logs rejected count.
Generates interactive TraceMap, honest Test Gap Radar, Maintainer Handoff, and exportable Proof Bundle.
Evidence Status Legend & Caveats
IssueLift enforces honest labels. We never masquerade an AI guess as a verified fact.
Directly verified against the fetched repository file tree or documentation manifests.
Caveat: Existence confirms the file is real; it does NOT prove semantic correctness or test coverage.
Inferred by Google Gemma 4 from issue context or comments when explicit quotes are missing.
Caveat: Must be reviewed by the contributor and blessed by maintainers before coding.
Information could not be established from the bounded scan context.
Caveat: IssueLift never fabricates commands or coverage numbers when data is absent.
Hallucinated path or invalid source ID detected and blocked by the deterministic Claim Gate.
Caveat: Demoted to UNKNOWN and logged in the audit ledger to protect maintainer goodwill.
Readiness Gate Verdicts
Before anyone begins writing code, IssueLift assigns a clear readiness state based on concrete evidence.
Issue is open, requirements are well-defined, and candidate source/test files exist in the repository tree.
Requirements are ambiguous, the issue is closed or already assigned, or explicit maintainer approval is needed.
The repository tree was truncated by GitHub API limits or setup documentation is missing.
When the Test Gap Radar reports "NO TEST EVIDENCE FOUND IN SCANNED FILES", IssueLift is describing only the files present in GitHub's bounded tree scan. It means no test file matching the candidate source path pattern was detected in the inspected context. IssueLift never claims "the repository has no tests," nor does it invent false test coverage percentages.
What IssueLift Does NOT Do
IssueLift does not write implementation code or submit speculative PRs. Its goal is human contributor alignment.
Maintainer questions are copy-ready for you to review and post manually. IssueLift never spams issue threads.
Only public GitHub repositories are supported. No authentication tokens or repository credentials are stored.
IssueLift inspects static manifests and trees; it never executes repository scripts or installs dependencies.
First-Scan Checklist & Troubleshooting
Common scenarios encountered during real GitHub scans and how IssueLift handles them.
If a Pull Request URL (`/pull/`) is entered, IssueLift rejects it with an explanatory note. Only pre-implementation issue URLs (`/issues/123`) are supported.
Unauthenticated GitHub REST requests share an hourly limit of 60 calls per IP. When hit, IssueLift reports the reset time and serves cached trees when available.
If `GEMMA_API_KEY` is not configured, IssueLift automatically engages the deterministic baseline compiler. The app continues to operate without mock failures.
Ready to Align on Your First Issue?
Scan a real GitHub issue now. Examine the compiled criteria, inspect candidate tests in TraceMap, and export your Contribution Proof Bundle.