Guiding Human Validation of LLM-Generated Code via Verifiable Literate Programming

Abstract: Vibe coding democratizes software development by allowing users to generate code via natural-language (NL) interaction with LLMs. However, the code is reliable only when it faithfully implements the user's intent, which is difficult and labor-intensive for users to validate. Existing validation methods either rely on LLM-assisted automated testing, which suffers from prompt ambiguity and model fallibility, or involve users only in partial software artifacts such as prompts and test cases, which may overlook corner cases and program details. Motivated by a bug study of LLM-generated code, we find that detailed human feedback is essential, as failures often stem from underspecified requirements or subtle semantic deviations. This paper presents verifiable literate programming (VLP), a human-in-the-loop framework designed to make the review/validation process of LLM-generated code accessible to users at all programming levels. At its core, VLP proposes unambiguous NL-based documentation as a readable intermediate layer between prompts and code. The documentation demonstrates concrete program semantics and enables users to provide feedback on potential intent-code mismatches. It supports human-involved, end-to-end repair and validation via three techniques: (i) an NL-style literate language with unambiguous syntax and mostly deterministic code-to-documentation translation, (ii) LLM-based fine-grained mismatch detection that uses trace links between prompts and documentation to focus users' review effort on suspicious documentation lines, and (iii) a verification module that leverages user-validated documentation to derive API-usage checks and formal properties, which are then verified against the generated code using model checking. Our evaluation shows that VLP improves code pass@1 from 28.7%-73.2% to 65.4%-93.5% with reasonable user effort.

• The paper proposes Verifiable Literate Programming, a human-guided framework that validates LLM-generated code via deterministic NL documentation.
• It employs trace-link recovery and mismatch detection to identify intent-level errors, boosting pass@1 performance from 28.7%–73.2% to 65.4%–93.5%.
• Integrating automated verification with iterative repair, the approach minimizes user effort while increasing transparency and code reliability.

Verifiable Literate Programming: Human-Guided Validation of LLM-Generated Code

Motivation and Problem Setting

LLMs have become central in "vibe coding"—a paradigm in which users generate code through natural-language (NL) prompts. However, a critical bottleneck is ensuring that the produced code faithfully aligns with user intent, especially for non-programmers. Existing approaches to code validation rely predominantly on LLM-powered automated testing or involve users in partially validating artifacts (e.g., prompts, test cases), both of which have measurable limitations. Automated methods are fundamentally constrained by prompt ambiguity and LLM fallibility, often failing to capture subtle semantic gaps or nuances in user requirements. Human-in-the-loop methods, typically exposing users only to partial program aspects, are insufficient, as they cannot guarantee that generated code meets nuanced intent or catches underspecified or domain-specific errors (2607.02333).

A systematic bug analysis using BigCodeBench-Hard, Claude Opus 4.7, and DeepSeek V4 Flash revealed that the primary sources of failure are underspecified prompts and subtle semantic deviations. Notably, over 80% of observable bugs were intent-level misalignments that could, in principle, be reviewed by users through NL documentation corresponding to program semantics.

Verifiable Literate Programming: Framework Overview

Verifiable Literate Programming (VLP) is introduced as a comprehensive, human-in-the-loop validation framework designed to strengthen the integrity of LLM-generated code. The core insight is to synthesize a faithfully readable intermediate documentation layer between the user's NL prompt and the generated code. This layer exposes concrete program semantics and supports fine-grained human feedback.

VLP operates via the following intertwined mechanisms:

1. NL-Style Literate Language: Generated code is translated into an unambiguous, structured, and mostly deterministic NL "literate" language. This translation preserves control flow, data flow, and explicit assertion properties. Nontrivial code fragments are flagged for targeted LLM-assisted summarization.
2. Trace-Link-Guided Mismatch Detection: VLP recovers traceability links between prompt requirements and documentation fragments, applying a taxonomy-guided LLM to detect and flag potential mismatches for user review. The interface highlights only suspicious documentation, dramatically reducing cognitive load.
3. Automated Downstream Verification: Once documentation is user-validated, VLP extracts formal properties and API-usage checks, verifying them against the generated code using bounded model checking or LLM-powered verification modules.

This architecture supports iterative repair: user feedback updates the documentation and triggers targeted code modifications, followed by additional conjunctions of model checking and human review until alignment is achieved or a termination condition is met.

Figure 1: Conventional literate programming workflow versus verifiable literate programming (VLP) workflow. In VLP's user validation, "Take Suggestion" confirms a detected mismatch or fix, "Keep Doc" retains documentation, and "Comment" solicits clarification.

Figure 2: Workflow and major components of VLP, highlighting generation, NL documentation construction, trace link recovery, user validation, targeted repair, and automated verification.

Empirical Analysis and Bug Taxonomy

A granular bug taxonomy was constructed from failures encountered with DeepSeek V4 Flash and Claude Opus 4.7 on BigCodeBench-Hard. Two main observations emerged. First, most logic-related bugs (e.g., missing steps, implementation of wrong operations, or incorrect operand values) are visible at the intent-level NL, confirming the viability of documentation-based review. Second, Python- or API-specific failures (e.g., misuse of library calls, argument mismatches) often elude even expert NL inspection without detailed language/library knowledge.

Figure 3: Bug taxonomy of code generated by DeepSeek V4 Flash and Claude Opus 4.7, showing logic and API-specific failure modes quantified over BigCodeBench-Hard.

This motivates VLP's division of semantic responsibilities: use human-in-the-loop NL documentation for intent-level review, and automated verification tools for language/library-specific correctness.

Literate Language and Documentation Construction

The intermediate literate language constructed by VLP is an NL-style LALR(1) grammar, supporting precise, unambiguous mappings from code to documentation. The translation is deterministic for most Python constructs (declarations, arithmetic, conditionals, loops), while specialized code patterns (notably API invocations and higher-order constructs) are earmarked for LLM-summarized NL paraphrasing within a tightly controlled grammar. Assertion-based properties, written in a Hoare-style, allow users to validate function contracts and invariants at a high-level.

Documentation is hierarchically structured for focused validation: collapsible blocks demarcate functions and classes, with suspicious lines (as flagged by mismatch detection) auto-expanded for user inspection, minimizing validation overhead.

Fine-Grained Mismatch Detection and User Interface

VLP's mismatch detection component leverages implementation-relevant traceability link recovery (TLR). The system decomposes both the prompt and the documentation into fine-grained behavioral or conditional "units," building semantic links between them using an LLM judge validated against a taxonomy derived from the bug study. This enables targeted auditing for seven principal mismatch types:

• Missing or redundant steps
• Prompt underspecification/domain ambiguity
• Incorrect/wrong API usage or operand
• Wrong execution flow or operation

Only flagged NL-form documentation lines are presented to users, together with validation questions, supporting iterative clarification or acceptance.

Automated Downstream Verification

Upon user validation of documentation, VLP invokes two verification paths:

1. Python-Specific API Verification: Automated LLM-powered checking that APIs and library calls meet syntactic and semantic requirements.
2. Bounded Model Checking: By translating NL assertion properties to executable statements (using, e.g., CrossHair), VLP performs symbolic execution to systematically test for property violations within practical bounds, feeding counterexamples back into the repair loop as appropriate.

Experimental Results

VLP was evaluated on BigCodeBench-Instruct (BCB) and QuantCodeEval (QCE), which respectively stress API usage with complex instructions and challenge domain-specific coding in quantitative finance.

Strong Numerical Improvements

• Pass@1 Performance: On BCB and QCE, VLP increases pass@1 from an initial 28.7%–73.2% (default LLM output) to 65.4%–93.5% when using guided human (or simulated) review. This outperforms SOTA interactive frameworks including ClarifyGPT, TiCoder, and PInG.
• User Study: In a controlled study (both simulated and with real users), VLP achieved superior gains in user satisfaction, issue identification, and overall correctness, with a lower cognitive and time burden relative to line-by-line code review or test-driven interfaces.

  Figure 4: Pass@1 on BigCodeBench and QuantCodeEval with LLM-based user simulation, showing substantial improvements achieved by VLP-guided workflows.

  

  Figure 5: Real user study benchmarks: Left, pass@1 accuracy vs. user time; right, user-rated satisfaction, confidence, and effort—demonstrating VLP's superior correctness-effort tradeoff.

• Validation Efficiency: VLP typically triggers 0.1–0.22 questions per line of code (vs. exhaustive review or sparse clarification), localizing user validation effort where it is most productive.

  Figure 6: Average tokens expended per task on BCB and QCE, quantifying cost tradeoffs against correctness.

Ablation Analysis

• Removal of the API knowledge base or TLR reduces pass@1 by 6–19 absolute points, verifying that both technical components are necessary for peak performance.

Limitations

• VLP does not address requirements or misalignments that never appear in any prompt/documentation artifact.
• Effectiveness is contingent on underlying LLM's repair competence and domain knowledge, especially for tasks requiring deep finance or scientific reasoning.

Implications and Future Directions

VLP substantially increases the reliability, transparency, and human-controllability of LLM-generated code in NL-driven coding workflows, particularly lowering the technical barrier for non-programmer users. Practically, VLP's structured documentation and feedback loop represent an advance over both purely automated testing and coarse-grained human clarifications. It enables pinpoint repair of intent-level misalignments, while automated verifiers support downstream validation of language/library-specific concerns.

Theoretically, VLP brings large-scale generation closer to a specification-driven paradigm. This aligns with emerging visions for explainable and certifiably correct AI agents in software construction. It also highlights the importance of separating intent-level and implementation-level validation, a bifurcation likely to be central in future AI-assisted software engineering methodologies.

Immediate areas for further research include refined integration with richer domain knowledge bases, enhancements for other programming languages and code genres, and automated prompts for self-refinement in domains with complex or latent requirements.

Conclusion

Verifiable Literate Programming demonstrates that coupling deterministic NL documentation with trace-link-guided, human-in-the-loop validation yields measurable improvements in LLM-generated code correctness and user trust. This work establishes a robust foundation for further integration of formal verification and fine-grained, user-driven review, advancing the practical deployment of LLMs in end-user-oriented software engineering.