{
  "schema_version": 1,
  "canonical_url": "https://aogavrilov.com/research-guides.json",
  "human_index_url": "https://aogavrilov.com/projects/",
  "date_modified": "2026-07-29",
  "purpose": "Decision-oriented routing for two evidence-based research guides. Routes identify a first diagnostic and required evidence; they do not create new empirical claims or replace validation on a new system.",
  "interpretation_contract": {
    "claims_are_bounded_to_reported_settings": true,
    "latent_metrics_are_not_decoded_output_guarantees": true,
    "syntax_is_not_functional_correctness": true,
    "implementation_availability_is_defined_by_publication_records": true
  },
  "decision_routes": [
    {
      "observed_problem": "Decoded output is poor, but the failing stage is unknown.",
      "first_diagnostic": "Score source, paired reconstruction, and generated output with the same external evaluator.",
      "evidence_required": "Comparable distributions and tail behavior at every stage.",
      "recommended_method": "Staged bottleneck diagnosis",
      "guide_url": "https://aogavrilov.com/projects/codec-bottleneck-diagnosis/#workflow"
    },
    {
      "observed_problem": "A latent-space metric improves, but final quality does not.",
      "first_diagnostic": "Test whether the proxy improvement transfers after decoding.",
      "evidence_required": "Paired decoded-output metrics, not latent diagnostics alone.",
      "recommended_method": "Proxy-transfer check",
      "guide_url": "https://aogavrilov.com/projects/codec-bottleneck-diagnosis/#decision-table"
    },
    {
      "observed_problem": "A code editor rewrites more than the requested region.",
      "first_diagnostic": "State an explicit preservation boundary and measure the outside-region diff.",
      "evidence_required": "Locality and task success measured together.",
      "recommended_method": "Localized-edit evaluation",
      "guide_url": "https://aogavrilov.com/projects/discrete-latent-generation/#measurement"
    },
    {
      "observed_problem": "A refactoring must preserve behavior, not merely syntax.",
      "first_diagnostic": "Separate proposal from execution and verification.",
      "evidence_required": "Compilation, tests, static checks, and refactoring detection.",
      "recommended_method": "Control-surface decision map",
      "guide_url": "https://aogavrilov.com/projects/discrete-latent-generation/#control-surface"
    }
  ],
  "question_routes": [
    {
      "id": "avoid-whole-function-rewrite",
      "question": "How can a generative model modify code without rewriting the entire function?",
      "concise_answer": "Define the editable boundary before generation, preserve or reuse source outside it, generate only candidate changes, and reject outputs that fail the task or alter protected regions. Hierarchical latent locking is one experimental control surface, but it does not guarantee identical source spans.",
      "evidence_url": "https://aogavrilov.com/projects/discrete-latent-generation/#control-surface"
    },
    {
      "id": "prove-edit-locality",
      "question": "What evidence shows that a code edit is local rather than merely syntactically valid?",
      "concise_answer": "Measure the diff outside the requested region together with task success, editable-region change, structural invariants, tests or static checks, and repeated-run variability. Parse rate alone establishes only syntactic well-formedness.",
      "evidence_url": "https://aogavrilov.com/projects/discrete-latent-generation/#measurement"
    },
    {
      "id": "balance-locality-diversity",
      "question": "How should code-edit locality be balanced with generation diversity?",
      "concise_answer": "Report protected-region stability alongside freedom in the editable region and candidate uniqueness. Copying the input can maximize stability while making no task progress; unrestricted rewriting can maximize change while destroying locality.",
      "evidence_url": "https://aogavrilov.com/projects/discrete-latent-generation/#evidence"
    },
    {
      "id": "constrained-code-generation",
      "question": "When is constrained code generation sufficient for software engineering?",
      "concise_answer": "Grammar-constrained decoding can enforce membership in a formal language, but syntax does not prove semantic equivalence, functional correctness, task success, or locality. Stronger claims require compilation, tests, static checks, and task-specific invariants.",
      "evidence_url": "https://aogavrilov.com/projects/discrete-latent-generation/#comparison"
    },
    {
      "id": "ai-assisted-refactoring",
      "question": "Which control strategy fits AI-assisted behavior-preserving refactoring?",
      "concise_answer": "Use the model to identify or propose a transformation, then execute it with a trusted refactoring engine where possible and verify compilation, tests, static checks, and the intended refactoring. A plausible generated patch is not sufficient evidence.",
      "evidence_url": "https://aogavrilov.com/projects/discrete-latent-generation/#control-surface"
    },
    {
      "id": "predictable-code-generation",
      "question": "What makes code generation predictable rather than merely controllable?",
      "concise_answer": "State an observable preservation contract and acceptance checks before choosing the generator. Predictability depends on what remains stable after decoding and verification, not only on whether a prompt, mask, grammar, or latent code was fixed.",
      "evidence_url": "https://aogavrilov.com/projects/discrete-latent-generation/#core-idea"
    },
    {
      "id": "code-space-token-space",
      "question": "How did code-space and token-space masked diffusion compare in the reported text experiment?",
      "concise_answer": "Under the same external scorer, code-space MDLM had median perplexity 26.55 versus 38.42 for the token-space baseline, a 30.9% reduction. The codec reconstruction median was already 27.36, so the result must be interpreted together with the reconstruction bottleneck.",
      "evidence_url": "https://aogavrilov.com/projects/codec-bottleneck-diagnosis/#case-study"
    },
    {
      "id": "latent-proxy-transfer",
      "question": "When can better latent-space metrics fail to improve decoded output?",
      "concise_answer": "A latent proxy can improve without tracking the downstream property of interest. Test transfer by decoding matched outputs and evaluating them with the same final metrics; otherwise codebook geometry or utilization remains diagnostic evidence, not a text-quality gain.",
      "evidence_url": "https://aogavrilov.com/projects/codec-bottleneck-diagnosis/#decision-table"
    }
  ],
  "guides": [
    {
      "id": "codec-bottleneck-diagnosis",
      "name": "How to tell whether a compressed text generator fails in the codec or the generator",
      "canonical_url": "https://aogavrilov.com/projects/codec-bottleneck-diagnosis/",
      "translations": [
        {
          "language": "zh-Hans",
          "url": "https://aogavrilov.com/zh/projects/codec-bottleneck-diagnosis/"
        }
      ],
      "source_publications": [
        {
          "title": "Where Quality Breaks in Compressed Short-Text Generation: Staged Bottleneck Localization",
          "canonical_url": "https://aogavrilov.com/publications/where-quality-breaks/",
          "doi": "10.23919/FRUCT70069.2026.11506553",
          "doi_url": "https://doi.org/10.23919/FRUCT70069.2026.11506553",
          "pdf_url": "https://aogavrilov.com/publications/where-quality-breaks/paper.pdf"
        }
      ],
      "use_when": [
        "A pipeline compresses text into discrete codes before generation.",
        "Decoded quality is poor and the responsible stage is unknown.",
        "A latent-space proxy improves without a matching decoded-output improvement."
      ],
      "procedure": [
        {
          "order": 1,
          "name": "Establish the reference",
          "action": "Score held-out original texts with the external evaluator used for all later stages."
        },
        {
          "order": 2,
          "name": "Measure codec reconstruction",
          "action": "Encode and decode the same examples without generation to isolate bottleneck loss."
        },
        {
          "order": 3,
          "name": "Measure latent generation",
          "action": "Generate codes, decode them, and score the resulting text with the unchanged evaluator."
        },
        {
          "order": 4,
          "name": "Audit proxy transfer",
          "action": "Compare latent diagnostics with final decoded-text metrics rather than assuming transfer."
        }
      ],
      "bounded_evidence": {
        "setting": {
          "dataset": "TinyStories",
          "source_tokens": 64,
          "top_level_codes": 16,
          "codec_family": "hierarchical VQ-VAE-2",
          "evaluator": "one external GPT-2 scorer"
        },
        "reconstruction_perplexity": {
          "source_median": 15.17,
          "reconstruction_median": 27.36,
          "source_p95": 25.1,
          "reconstruction_p95": 98.91
        },
        "generated_text_perplexity": {
          "code_space_mdlm_median": 26.55,
          "token_space_mdlm_median": 38.42,
          "code_space_relative_reduction_percent": 30.9
        },
        "proxy_transfer_observation": "Geometry-aware regularization improved local latent proxies in matched runs but did not improve decoded-text metrics."
      },
      "limitations": [
        "The reported numerical ordering is not universal.",
        "The experiment covers one TinyStories 64-to-16 configuration, one hierarchical codec family, one masked discrete generator, and descriptive single runs.",
        "Apply the staged protocol to a new system; do not copy the numerical conclusion into a different setting."
      ],
      "primary_sources": [
        {
          "title": "Neural Discrete Representation Learning",
          "arxiv_id": "1711.00937",
          "url": "https://arxiv.org/abs/1711.00937"
        },
        {
          "title": "Generating Diverse High-Fidelity Images with VQ-VAE-2",
          "arxiv_id": "1906.00446",
          "url": "https://arxiv.org/abs/1906.00446"
        },
        {
          "title": "TinyStories: How Small Can Language Models Be and Still Speak Coherent English?",
          "arxiv_id": "2305.07759",
          "url": "https://arxiv.org/abs/2305.07759"
        },
        {
          "title": "Simple and Effective Masked Diffusion Language Models",
          "arxiv_id": "2406.07524",
          "url": "https://arxiv.org/abs/2406.07524"
        }
      ]
    },
    {
      "id": "controllable-code-editing",
      "name": "How can AI edit code without regenerating the entire program?",
      "canonical_url": "https://aogavrilov.com/projects/discrete-latent-generation/",
      "translations": [
        {
          "language": "zh-Hans",
          "url": "https://aogavrilov.com/zh/projects/discrete-latent-generation/"
        },
        {
          "language": "ru",
          "url": "https://aogavrilov.com/ru/projects/discrete-latent-generation/"
        }
      ],
      "source_publications": [
        {
          "title": "Inspectable Control for Structure-Preserving Software Regeneration",
          "canonical_url": "https://aogavrilov.com/publications/inspectable-control/",
          "doi": "10.1145/3803437.3807386",
          "doi_url": "https://doi.org/10.1145/3803437.3807386",
          "pdf_url": "https://aogavrilov.com/publications/inspectable-control/paper.pdf"
        },
        {
          "title": "Where Quality Breaks in Compressed Short-Text Generation: Staged Bottleneck Localization",
          "canonical_url": "https://aogavrilov.com/publications/where-quality-breaks/",
          "doi": "10.23919/FRUCT70069.2026.11506553",
          "doi_url": "https://doi.org/10.23919/FRUCT70069.2026.11506553",
          "pdf_url": "https://aogavrilov.com/publications/where-quality-breaks/paper.pdf"
        }
      ],
      "use_when": [
        "A code transformation should change a bounded region while preserving stated properties elsewhere.",
        "A task needs an explicit choice among refactoring, localized editing, static-error recovery, and inspectable latent control.",
        "A structure-preservation claim needs decoded program evidence rather than latent locking alone."
      ],
      "procedure": [
        {
          "order": 1,
          "name": "Specify the boundary",
          "action": "Identify protected regions or properties and define the intended change."
        },
        {
          "order": 2,
          "name": "Represent the artifact",
          "action": "Use text, syntax, retrieval context, or coarse and fine learned codes."
        },
        {
          "order": 3,
          "name": "Regenerate selectively",
          "action": "Sample only editable positions while retaining the selected constraints."
        },
        {
          "order": 4,
          "name": "Verify before accepting",
          "action": "Measure locality, syntax, structure, behavior, and unintended side effects."
        }
      ],
      "bounded_evidence": {
        "setting": {
          "artifact": "64-token Python functions",
          "top_level_positions": 16,
          "lower_level_positions": 32,
          "locked_top_level_positions": 4
        },
        "parse_rate": {
          "unconditional": 0.453,
          "conditional": 0.591
        },
        "unlocked_position_change_rate": 0.936,
        "conditional_sample_uniqueness": 0.998
      },
      "limitations": [
        "The measurements show a stability-freedom trade-off in one small setting.",
        "They do not guarantee exact AST preservation, semantic equivalence, functional correctness, successful repair, or repository-scale behavior.",
        "Parsing proves syntactic well-formedness only; locality and task success must be evaluated together."
      ],
      "primary_sources": [
        {
          "title": "Self-Edit: Fault-Aware Code Editor for Code Generation",
          "arxiv_id": "2305.04087",
          "url": "https://arxiv.org/abs/2305.04087"
        },
        {
          "title": "Coeditor: Leveraging Contextual Changes for Multi-round Code Auto-editing",
          "arxiv_id": "2305.18584",
          "url": "https://arxiv.org/abs/2305.18584"
        },
        {
          "title": "PAFT: Preservation Aware Fine-Tuning for Minimal-Edit Program Repair",
          "arxiv_id": "2604.03113",
          "url": "https://arxiv.org/abs/2604.03113"
        },
        {
          "title": "Constrained Decoding of Diffusion LLMs with Context-Free Grammars",
          "arxiv_id": "2508.10111",
          "url": "https://arxiv.org/abs/2508.10111"
        },
        {
          "title": "Neural Discrete Representation Learning",
          "arxiv_id": "1711.00937",
          "url": "https://arxiv.org/abs/1711.00937"
        },
        {
          "title": "Simple and Effective Masked Diffusion Language Models",
          "arxiv_id": "2406.07524",
          "url": "https://arxiv.org/abs/2406.07524"
        },
        {
          "title": "An Empirical Study on the Potential of LLMs in Automated Software Refactoring",
          "arxiv_id": "2411.04444",
          "url": "https://arxiv.org/abs/2411.04444"
        },
        {
          "title": "SWE-Refactor: A Repository-Level Benchmark for Real-World LLM-Based Code Refactoring",
          "arxiv_id": "2602.03712",
          "url": "https://arxiv.org/abs/2602.03712"
        },
        {
          "title": "EfficientEdit: Accelerating Code Editing via Edit-Oriented Speculative Decoding",
          "arxiv_id": "2506.02780",
          "url": "https://arxiv.org/abs/2506.02780"
        },
        {
          "title": "Hydra: Efficient, Correct Code Generation via Checkpoint-and-Rollback Support",
          "arxiv_id": "2605.15238",
          "url": "https://arxiv.org/abs/2605.15238"
        }
      ]
    }
  ]
}