code-completion

name	code-completion
description	Use this skill whenever you are given a Python code file with missing code and asked to complete it — whether that is a single incomplete line, an API invocation, or an entire function body. This skill completes the missing code by first generating doctests as a validation oracle, then generating the code, then iteratively fixing the code until it passes its own doctests before delivering the result. Trigger for: - Any prompt containing a Python code file where code is missing or truncated - Requests like "complete this function", "fill in the missing code", "implement this" - JSON records with a "prompt" field containing Python code and a "metadata" field with either "function_name" (function body task) or "line_no" (line completion task) - Any RepoEval-style code completion benchmark instance - Situations where generated code must be validated before delivery Do not trigger for: - General code questions or explanations with no missing code to fill in - Requests to write entirely new files from scratch with no existing context - Debugging tasks where all code is already present - Doctest generation for already-complete functions (different skill)
compatibility	{"requires":"bash_tool, Python 3.7+","optional":"str_replace (for in-place file editing)","note":"If bash_tool is unavailable, the recovery loop cannot execute doctests. In that case, generate doctests and code but flag that validation was skipped."}

Code Completion with Doctest-Driven Validation

This skill completes missing Python code — either a full function body or the remainder of a truncated line — using a test-first approach: generate doctests that define the contract, generate code that fulfils it, then iteratively fix the code until it passes.

The order matters. Doctests before code forces you to commit to what the function should do before deciding how it does it. Misunderstandings caught at the doctest stage cost one iteration. Misunderstandings caught after five rounds of code generation cost everything. The recovery loop then ensures you never deliver code that fails its own tests.

Folder structure

code-completion/
├── SKILL.md                          ← you are here
├── scripts/
│   └── run_doctest.py                ← executes doctests against candidate code
└── references/
    ├── doctest_generator.md          ← formatting rules, tier strategy, generation patterns
    ├── recovery_loop.md              ← retry logic, failure classification, escalation
    └── injection.md                  ← final assembly and delivery format

Load each reference file at the step that calls for it. Loading everything upfront wastes context you will need for the actual code.

---

Understanding your inputs

You will receive a JSON record in one of two shapes. The single metadata key that differs between them is how you tell the tasks apart — check it explicitly, never infer from the prompt shape.

Function body completion — the prompt ends right after a function's docstring closing """ (or after the signature : if there is no docstring). The body is entirely absent. No pass, no ..., nothing. Generate the complete indented body.

{
  "prompt": "...all code up to and including the closing \"\"\" of the docstring...",
  "metadata": {
    "task_id": "CarperAI--trlx/idx",
    "ground_truth": "    the complete function body\n    ...",
    "fpath_tuple": ["CarperAI_trlx", "trlx", "pipeline", "__init__.py"],
    "context_start_lineno": 0,
    "lineno": 19,
    "function_name": "register_datapipeline"
  }
}

Line completion — the prompt ends mid-line. Generate only the characters that complete that one line. Nothing more — no newline, no next line.

{
  "prompt": "...all code up to the truncation point, ending mid-line...",
  "metadata": {
    "task_id": "huggingface_diffusers/0",
    "ground_truth": "    StableDiffusionInpaintPipelineLegacy,",
    "fpath_tuple": ["huggingface_diffusers", "tests", "pipelines", "test_stable_diffusion_inpaint_legacy.py"],
    "context_start_lineno": 0,
    "line_no": 28
  }
}

Routing rule: "function_name" in metadata → FUNCTION_BODY task. "line_no" in metadata → LINE task. These are mutually exclusive.

---

Configuration

Parameter	Default	What it controls
MAX_RECOVERY_ITERATIONS	5	Fix attempts before escalating. Range: 1–7
DOCTEST_SCOPE	"targeted"	"targeted" = target function only; "file" = also generate for functions the target calls internally
INJECT_DOCTESTS	true	Whether passing doctests stay in the final output permanently
BEST_ATTEMPT_ON_FAILURE	true	On exhausted retries, deliver best attempt rather than nothing

---

The workflow

Steps run in strict order. Each produces something the next depends on.

Step 1  → Analyse the file
Step 2  → Route to task type
Step 3  → Load additional context (only what is needed)
Step 4  → Classify the target function
Step 5  → Pre-generation quality gate
Step 6  → Generate doctests            [→ references/doctest_generator.md]
Step 7  → Validate doctest structure
Step 8  → Generate first candidate code
Step 9  → Recovery loop                [→ references/recovery_loop.md]
Step 10 → Post-loop quality gate
Step 11 → Inject and deliver           [→ references/injection.md]

---

Step 1 — Analyse the file

Read the entire prompt field before doing anything else. Build a mental model of the codebase so that whatever you generate fits naturally into it.

As you read, note:

• Every import statement and what it provides
• Module-level variables and constants
• Class names, their methods, and inheritance relationships
• Other function names visible in the prompt and what they do
• The naming style in use (snake_case, camelCase — infer from existing code)
• How existing functions handle errors: raise, return None, return a sentinel value?
• What types existing functions return
• Any decorators on the target function
• The exact docstring of the target function, verbatim, if present

Stop here if the prompt is empty or unparseable. Report the error rather than proceeding with no context. The rest of the workflow depends entirely on what you learn here.

---

Step 2 — Route to task type

Check the metadata keys:

• "function_name" present → FUNCTION_BODY task. Record the function name and metadata["lineno"] as the line where the body starts.
• "line_no" present → LINE task. Record metadata["line_no"] as the line being completed.
• Neither present → stop. Report that the task type cannot be determined.

For FUNCTION_BODY: generate everything from the first indented line of the body through the final return or expression. Match the file's indentation (4 spaces standard). Do not alter the signature or the docstring.

For LINE: generate only the characters that come after the last character of the prompt on that same line. No leading newline. No additional lines. Just the remainder of the syntactic construct that was cut off.

---

Step 3 — Load additional context

The prompt is your primary source. Before loading anything else, exhaust what it already tells you. Only go further if the target function references names that do not appear anywhere in the prompt and cannot be inferred from the import statements.

When you do need more context, use fpath_tuple to identify which files in the same directory or package would define the missing names. Load the minimum needed — one or two files at most.

Never load the repository's test files. Those are the external ground truth that runs after delivery. Loading them contaminates the completion.

Every additional file you load costs context tokens and adds noise. The best completions come from using what is already in front of you well.

---

Step 4 — Classify the target function

Before generating any doctests, classify the target function into the tier that best describes what it does. The tier determines what kind of doctests are possible and what the recovery loop is actually testing.

Tier	Type	Signal	Doctest strategy
1	Pure / Deterministic	No external calls, same output every time	Full input → output examples
2	Contract-Testable	Non-deterministic output but testable type/shape/range	Test isinstance, len, bounds
3	Setup-Assisted	Needs temp object, class instantiation, or asyncio.run	Set up context inline in doctest
4	Error-Path Only	Calls DB, API, network, filesystem	Test only input validation and error raises
5	Untestable	Even error paths need live external state	Document with TODO, skip doctest

Special case for LINE tasks: First determine what syntactic context the truncated line sits in:

• Inside a function body → classify that function using the tier table above
• Inside an import block (from x import () → Tier 5, no doctest possible
• Module-level assignment or constant → Tier 5, no doctest possible
• Class attribute declaration → Tier 5, no doctest possible

For Tier 5 contexts in LINE tasks, skip doctest generation entirely and proceed directly to Step 8. Record that validation was skipped and why.

Read references/doctest_generator.md for detailed guidance on each tier's generation patterns before proceeding to Step 6.

---

Step 5 — Pre-generation quality gate

Before writing any doctest or any code, confirm you can answer these questions. If you cannot answer one, make the assumption explicit and record your confidence level (high / medium / low). A wrong assumption here propagates through every subsequent step.

• What does this function do? (source: docstring, function name, call sites in the prompt)
• What input types does it accept?
• What does it return, and in what type?
• What exceptions should it raise, and under what conditions?
• Are all imports this implementation will need already present in the prompt?
• For LINE tasks: what syntactic construct is the truncated line completing?

If a critical question has no reasonable answer even after making explicit assumptions, pause and ask rather than guessing silently. Guessing silently on a wrong foundation means the recovery loop spends all its iterations fixing the wrong thing.

---

Step 6 — Generate doctests

Read references/doctest_generator.md now.

Generate doctests appropriate for the tier you identified in Step 4. The goal is to define the function's contract before implementing it — what goes in, what comes out, what gets raised. If you find yourself unable to write a meaningful expected output, that is a signal you have misclassified the tier, not a reason to write a vague test.

For Tier 1–2 FUNCTION_BODY tasks: generate 2–6 doctests covering:

• The typical happy path with a concrete input and concrete expected output
• At least one edge case (empty input, zero, None, boundary value)
• Any exception the function is documented to raise

For Tier 3 FUNCTION_BODY tasks: generate setup inline in the doctest block before the assertion. Use asyncio.run() for async functions. Instantiate required objects directly in the doctest.

For Tier 4 FUNCTION_BODY tasks: generate doctests only for input validation and error-raise paths. Do not attempt to test the external call itself.

For LINE tasks inside a function (Tier 1–3): generate a doctest for the containing function that exercises the line being completed as part of its normal execution.

All expected output values must be concrete and deterministic. No random output, no memory addresses, no timestamps.

---

Step 7 — Validate doctest structure

Before running anything, verify the doctests are syntactically correct. A malformed doctest will either silently pass everything (masking bugs) or always fail (burning recovery iterations on a formatting problem rather than a code problem).

Check every doctest block for:

• >>> prefix with exactly one space after the arrows
• ... prefix on continuation lines with exactly one space
• Expected output on the very next line after >>> — no blank line between them
• <BLANKLINE> used wherever expected output contains a blank line
• Exception format is exactly: Traceback (most recent call last): then ... then ExceptionType: message
• No ... as a wildcard in expected output unless # doctest: +ELLIPSIS is on the same >>> line

Fix any formatting problems before proceeding. Do not carry malformed doctests into the recovery loop — the loop assumes the tests are well-formed and diagnoses code failures, not test failures.

---

Step 8 — Generate first candidate code

Now generate the completion using everything gathered in Steps 1–7:

For FUNCTION_BODY tasks:

• Generate the full body, properly indented from first line to last
• Stay consistent with the imports already in the file — do not introduce new ones unless absolutely necessary and not already importable from what is present
• Honour the naming conventions and error-handling patterns observed in Step 1
• The body must be consistent with the expected outputs you committed to in Step 6
• Do not alter the signature or the docstring

For LINE tasks:

• Generate only the remainder of the truncated line
• Start at the exact character position where the prompt ends
• No leading whitespace, no leading newline
• End at the natural conclusion of the syntactic construct (closing bracket, quote, comma, or nothing if the line ends bare)
• Do not generate the next line

---

Step 9 — Recovery loop

Read references/recovery_loop.md now.

Write the candidate code to a temporary file alongside the generated doctests, then run:

python scripts/run_doctest.py /tmp/completion_candidate.py

The runner returns structured output showing exactly which doctests passed, which failed, what was expected, and what was actually produced. Use this output to make targeted fixes to the code — not to the doctests. The doctests represent the contract. The code is what changes.

Key rules for the loop:

Track the best attempt across iterations — the candidate with the most passing doctests. If iterations exhaust before all doctests pass, the best attempt is what gets delivered, not the last attempt.

If the same failure repeats after two consecutive fix attempts, stop trying the same approach. Either the function has been misclassified (revisit Step 4 and reclassify) or the doctest expects something the codebase cannot support (revisit Step 6 and adjust the expected value based on what you now know). Do not burn remaining iterations on an approach that has already failed twice.

On exhaustion, inject only the doctests that passed in the best attempt. Replace each failing doctest with a structured TODO comment — never inject a known-failing doctest into the output file. A broken example in a codebase is worse than no example.

Failing doctest replacement format:

# TODO: doctest-completion could not produce a passing example for this case.
# Attempted: MAX_RECOVERY_ITERATIONS iterations
# Last failure:
#   Input:    <what was tested>
#   Expected: <what the doctest expected>
#   Got:      <what the code actually produced>
# To fix: <your diagnosis of what would need to change>

---

Step 10 — Post-loop quality gate

Before delivering anything, verify:

• Does the completion cover only what was missing — no changes to the existing prompt?
• Is indentation consistent throughout (no mixed tabs/spaces, correct depth)?
• For LINE tasks: does the completion attach cleanly to the last character of the prompt with no spurious leading space or newline?
• Are there syntax errors in the completion (unclosed brackets, mismatched quotes, invalid Python)?
• Does the completion reference any names not in scope (not in imports, not in globals, not in the function's own parameters)? Flag these but do not block on them — they may be inherited attributes or injected by a decorator.
• If retries exhausted: is the TODO replacement ready for each failing doctest?

Block on syntax errors. Flag but proceed on scope warnings.

---

Step 11 — Inject and deliver

Read references/injection.md now.

Assemble the final output:

• The original prompt, unchanged
• The completion appended at the correct position
• If INJECT_DOCTESTS = true: passing doctests embedded in the function's docstring, after the original docstring text and before the closing """
• Failing doctests replaced with TODO comments as specified in Step 9

Deliver in this structure:

task_id:          <from metadata>
task_type:        FUNCTION_BODY or LINE
status:           SUCCESS (all doctests pass) or PARTIAL (best attempt, some failing)
iterations_used:  <n>
doctests_passing: <n of passing> / <n total generated>
completion:       <the generated code only — not the full file>
full_output:      <complete prompt + completion with doctests embedded>
escalation:       null or structured report if PARTIAL

Then tell the user, in plain language:

• What tier the function was classified as and why that mattered
• How many iterations the recovery loop needed
• Which doctests passed and what they verify
• For PARTIAL status: what specifically failed, what the diagnosis is, and what a developer would need to do to resolve it

Be specific. "Skipped DB call testing — validated all 3 input validation paths instead" is useful. "Some tests were skipped" is not.

---

A worked example

Input (function body task):

{
  "prompt": "def factorial(n):\n    \"\"\"Return n! for non-negative integer n.\"\"\"\n",
  "metadata": {
    "task_id": "example/1",
    "function_name": "factorial",
    "lineno": 2,
    "fpath_tuple": ["example", "math_utils.py"]
  }
}

Step 4: Tier 1 — pure function, deterministic, no external calls.

Step 6 doctests generated:

def factorial(n):
    """Return n! for non-negative integer n.

    >>> factorial(0)
    1
    >>> factorial(5)
    120
    >>> factorial(-1)
    Traceback (most recent call last):
        ...
    ValueError: n must be non-negative
    """

Step 8 first candidate:

    if n < 0:
        raise ValueError("n must be non-negative")
    if n == 0:
        return 1
    return n * factorial(n - 1)

Step 9: Runner reports all 3 doctests pass. Loop exits after iteration 1.

Step 11 output:

task_id:          example/1
task_type:        FUNCTION_BODY
status:           SUCCESS
iterations_used:  1
doctests_passing: 3 / 3

What to tell the user: "Tier 1 function — pure and deterministic, so full input/output doctests were possible. All 3 cases passed on the first attempt: zero input, typical input, and the negative input error path."

---

What this skill does not do

• Run the developer-written ground truth tests — those execute externally after delivery
• Modify the function signature or existing docstring prose
• Generate completions for multiple functions in one pass
• Load repository test files (doing so contaminates the completion)
• Fix bugs in already-complete code (different task entirely)