Problem Creation

Problem Creation Guide

Assistant Workflow

When user requests a problem by number or name/slug, the assistant will:

1. Scrape problem data using uv run lcpy scrape
2. Transform data into proper JSON template format
3. CRITICAL: Include images - Extract image URLs from scraped data and add to readme_examples with format: ![Example N](image_url)\n\n before code blocks
   • Check scraped data for image URLs in the raw_content field
   • Look for patterns: https://assets.leetcode.com/uploads/... or <img alt="" src="..." />
   • Common patterns: kthtree1.jpg, kthtree2.jpg, clone_graph.png, container.jpg
   • Images provide crucial visual context, especially for tree and graph problems
   • Always verify images are included in readme_examples and accessible
4. Create JSON file in src/leetcode_py/cli/resources/leetcode/json/problems/{problem_name}.json (note the src/ prefix — the non-src path silently fails bake p-gen with Warning: JSON file not found)
5. Update tags.json5 - If user specifies tags, manually add problem name to corresponding tag arrays in src/leetcode_py/cli/resources/leetcode/json/tags.json5
6. Generate problem structure using bake p-gen
7. Update @bakefile.py - Set problem = "{problem_name}" on the MyBakebook class to the newly created problem name for easier bake command usage
8. Verify with bake lint - fix template issues in JSON if possible, or manually fix generated files if template limitations
9. Iterate if JSON fixes: re-run bake p-gen -p {problem_name} -f and bake lint until passes to ensure reproducibility

If user does not specify a problem number or name/slug, run:

uv run python .claude/.dev/next_problem.py

This will suggest the next problem to work on from the available problem lists based on completion status.

Scraping Commands

# Fetch by number
uv run lcpy scrape -n 1

# Fetch by slug
uv run lcpy scrape -s "two-sum"

Premium Problems (scraper cannot fetch)

Premium problems fail with Error fetching problem: 'NoneType' object is not iterable. Fetch the statement from the web instead:

• Primary source: doocs/leetcode raw markdown mirror — covers ALL LeetCode problems (premium included), no search engine needed. URL is deterministic from the problem number + title: https://raw.githubusercontent.com/doocs/leetcode/main/solution/0100-0199/0156.Binary%20Tree%20Upside%20Down/README_EN.md (century folder 0100-0199, zero-padded number, URL-encoded Title Case)
• Fetch with curl: curl -s '<url>' | head -c 4000 — raw.githubusercontent serves static text, no browser needed. Title-guess 404? List the exact folder via GitHub API: curl -s https://api.github.com/repos/doocs/leetcode/contents/solution/0200-0299 | grep '"name"'
• Fallback: https://leetcode.ca/all/{N}.html (older wording, usually no constraints) — curl first; Playwright only if a source needs JS. Playwright GOTCHA: browser_evaluate HANGS on raw.githubusercontent pages (plain-text doc; eval stalls past 120s) — navigate, then read the auto-saved .playwright-mcp/page-*.yml snapshot
• Model the JSON on the fetched text, never on memory — statements get revised (e.g. 163 Missing Ranges now returns list[list[int]] ranges, not the old ["2", "4->49"] strings, and is Easy)
• Premium problems ship only 2-3 official examples, so most test cases are hand-invented — machine-verify every expectation with a reference implementation before writing the JSON (tree problems: TreeNode[int].from_list round-trip)

JSON Template Format

Required fields for src/leetcode_py/cli/resources/leetcode/json/problems/{problem_name}.json:

CRITICAL: Use single quotes for Python strings in playground fields to avoid JSON escaping issues with Jupyter notebooks.

JSON Escaping Rules:

• playground_test_case: Use single quotes for string literals (e.g., s = 'hello' not s = "hello")
• playground_execution: Use single quotes for string literals
• playground_assertion: Use single quotes for string literals
• Double quotes in JSON + cookiecutter + Jupyter notebook = triple escaping issues

Test Cases Format:

• test_cases: Use structured format with {"list": ["..."]} instead of string arrays
• Each test case should be a string representation of the tuple/parameters
• Example: {"list": ["('input1', 'input2', expected)", "('input3', 'input4', expected)"]}

GOTCHA — long string cases hit E501 in generated tests. Ruff line-length is 100 and the generator emits each parametrize case on its own line (16-space indent + quotes + comma). A case whose full line passes col 100 breaks p-gen/lint — BUT only when the overflow contains whitespace: ruff/pycodestyle silently exempt no-whitespace overflow (why a 120-char single-word line elsewhere in the repo passes). Hit with 273 Integer to English Words: cases like (1234567891, 'One Billion Two Hundred Thirty Four Million ...') produced 121-char lines. Fix at the JSON level: keep each test_cases entry's string payload under ~80 chars. For long-output problems, pick short-output cases at the same scale instead ((1000000001, 'One Billion One') covers the Billion path; drop the 99-char mega cases). Ops-sequence (design) cases that still overflow after trimming the op list: drop ALL spaces after commas ([[[1,2]],[],[]] instead of [[[1, 2]], [], []]) — still valid Python and buys room. DO NOT rely on a no-whitespace E501 exemption: the exemption is inconsistent (batch 11, 3 of 20 agents independently re-tested it: a 102-char no-whitespace parametrize line FAILS ruff check --select E501; it holds only when the whole generated line is a single token, and agent reports across runs conflict on the boundary). Worse, p-gen runs ruff format, which reflows long list literals element-per-line, so compactness does not even survive generation. Default rule: hard-cap every generated parametrize line at <=100 chars with a write-time assert in the JSON-writing script (1272/1533 pattern) — if a case cannot fit, use shorter cases at the same coverage instead of compact tricks; 1258 dropped an official example from test_cases by trusting the exemption. Compact form is still useful to fit borderline cases, but treat it as unverified until the assert passes. CAUTION — build compact strings quote-aware: repr(x).replace(" ", "") also strips spaces INSIDE string literals, silently corrupting expectations (' ' becomes '', 'i love you' becomes 'iloveyou'; hit twice in one batch, 604 and 642, costing 3 QA cycles). Strip whitespace only OUTSIDE quoted segments (re.split on '...' spans, strip in non-string parts) or escape literal spaces as \x20 before stripping.

GOTCHA — every test_cases entry must be a COMPLETE Python tuple literal. The generator parses each entry with ast.literal_eval; a bare two-expression string like '(H)', 'H' (no enclosing parens) fails to eval and the generator splits it on commas into orphan parametrize values, producing a confusing collection error: in "parametrize" the number of names (2) must be equal to the number of values (3). Parens INSIDE a quoted value are fine — ('Mg(OH)2', 'H2MgO2') parses correctly; the entry just needs its own enclosing ('...', '...'). Hit with 726 Number of Atoms: five hand-written paren-formula cases broke collection and cost a full regen cycle. Sanity-check before generating: python3 -c "import ast; [ast.literal_eval(c) for c in cases]".

GOTCHA — the generator does NOT warn when test_cases has fewer than 12 entries (the repo's stated minimum, enforced only at the QA/review level). Count the case list BEFORE running p-gen — the JSON-writing script should assert len(tc) >= 12 alongside its other write-time checks. Hit twice in one batch (723 with 11 cases, 1086 with 6); each needed a post-QA JSON edit + p-gen -f regen + solution restore, ~2 extra cycles. When hand-invented cases fall short, top up programmatically: generate random small inputs, run the same reference implementation over them, and assert the outputs into the case list (see 1086 High Five).

IMPORTANT: Create actual JSON files, not JSON5

The template below uses JSON5 format with comments for documentation purposes only. When creating the actual .json file, you must:

1. Remove all comments (lines starting with //)
2. Use proper JSON syntax with quoted property names
3. Save as .json file (not .json5)

Template with comments (JSON5 format for reference only):

{
    // ============================================================================
    // COMPREHENSIVE LEETCODE TEMPLATE EXAMPLE
    // ============================================================================
    // This example demonstrates ALL template patterns using valid_anagram as base
    // with comprehensive comments showing variations for different problem types.
    //
    // REFERENCE PROBLEMS (see .templates/leetcode/json/ for complete examples):
    // 1. valid_anagram        - Basic: string parameters, boolean return
    // 2. invert_binary_tree   - Tree: TreeNode imports/parameters
    // 3. merge_two_sorted_lists - LinkedList: ListNode imports/parameters
    // 4. lru_cache           - Design: custom class, multiple methods, operations
    // 5. implement_trie_prefix_tree - Trie: DictTree inheritance
    // ============================================================================

    // === PROBLEM IDENTIFICATION ===
    problem_name: "valid_anagram", // snake_case: used for directory/file names
    solution_class_name: "Solution", // "Solution" for basic problems
    // "LRUCache" for design problems
    // "Trie(DictTree[str])" for inheritance
    problem_number: "242", // LeetCode problem number as string
    problem_title: "Valid Anagram", // Exact title from LeetCode
    difficulty: "Easy", // Easy, Medium, Hard
    topics: "Hash Table, String, Sorting", // Comma-separated topics from LeetCode
    _tags: { list: ["grind-75"] }, // Optional: common problem set tags
    // Use _tags wrapper for cookiecutter lists

    // === README CONTENT ===
    // IMPORTANT: Preserve rich HTML content from LeetCode including:
    // - Code snippets with backticks: `code`
    // - Bold text: **bold** or <strong>bold</strong>
    // - Italic text: *italic* or <em>italic</em>
    // - Images: ![Example](https://assets.leetcode.com/uploads/...)
    // - HTML formatting: <p>, <br>, <ul>, <li>, etc.
    // - Mathematical expressions and special characters
    readme_description: "Given two strings `s` and `t`, return `true` if `t` is an anagram of `s`, and `false` otherwise.",

    _readme_examples: {
        // Use _readme_examples wrapper for cookiecutter lists
        list: [
            { content: '```\nInput: s = "anagram", t = "nagaram"\nOutput: true\n```' },
            { content: '```\nInput: s = "rat", t = "car"\nOutput: false\n```' },
            // For tree problems: Include images
            // { "content": "![Example 1](https://assets.leetcode.com/uploads/2021/02/19/tree1.jpg)\n\n```\nInput: root = [4,2,7,1,3,6,9]\nOutput: [4,7,2,9,6,3,1]\n```" }
        ],
    },

    readme_constraints: "- 1 <= s.length, t.length <= 5 * 10^4\n- s and t consist of lowercase English letters.",
    readme_additional: "**Follow up:** What if the inputs contain Unicode characters? How would you adapt your solution to such a case?",

    // === HELPER FUNCTIONS ===
    // New template system uses helper functions for cleaner test organization
    helpers_imports: "", // Empty for basic problems
    // "from leetcode_py import TreeNode" for tree problems
    // "from leetcode_py import ListNode" for linked list problems
    helpers_content: "", // Additional helper content if needed
    helpers_run_name: "is_anagram", // Function name matching main method
    helpers_run_signature: "(solution_class: type, s: str, t: str)",
    // For tree: "(solution_class: type, root_list: list[int | None])"
    // For linked list: "(solution_class: type, list1_vals: list[int], list2_vals: list[int])"
    // For design: "(solution_class: type, operations: list[str], inputs: list[list[int]])"
    helpers_run_body: "    implementation = solution_class()\n    return implementation.is_anagram(s, t)",
    // For tree: "    root = TreeNode[int].from_list(root_list)\n    implementation = solution_class()\n    return implementation.invert_tree(root)"
    // For design: "    cache = None\n    results: list[int | None] = []\n    # ... operation loop ...\n    return results, cache"
    helpers_assert_name: "is_anagram", // Function name matching main method
    helpers_assert_signature: "(result: bool, expected: bool) -> bool",
    // For tree: "(result: TreeNode[int] | None, expected_list: list[int | None]) -> bool"
    // For design: "(result: list[int | None], expected: list[int | None]) -> bool"
    helpers_assert_body: "    assert result == expected\n    return True",
    // For tree: "    expected = TreeNode[int].from_list(expected_list)\n    assert result == expected\n    return True"

    // === SOLUTION TEMPLATE ===
    solution_imports: "", // Empty for basic problems
    // "from leetcode_py import TreeNode" for tree problems
    // "from leetcode_py import ListNode" for linked list problems
    // "from leetcode_py.data_structures import DictTree, RecursiveDict" for trie problems
    solution_contents: "", // Additional content before class definition
    solution_class_content: "", // Content inside class definition (usually empty)

    // === TEST CONFIGURATION ===
    test_imports: "import pytest\nfrom leetcode_py import logged_test\nfrom .helpers import assert_is_anagram, run_is_anagram\nfrom .solution import Solution",
    // For design: "from .solution import LRUCache" instead of Solution
    test_content: "", // Additional test content
    test_class_name: "ValidAnagram", // PascalCase: TestClassName for pytest class
    test_class_content: "    def setup_method(self):\n        self.solution = Solution()",
    // Empty for design problems: ""

    // === SOLUTION METHODS ===
    _solution_methods: {
        // Use _solution_methods wrapper for cookiecutter lists
        list: [
            {
                name: "is_anagram", // snake_case method name
                signature: "(self, s: str, t: str) -> bool", // Full method signature with type hints
                // For tree: "(self, root: TreeNode[int] | None) -> TreeNode[int] | None"
                // For linked list: "(self, list1: ListNode[int] | None, list2: ListNode[int] | None) -> ListNode[int] | None"
                body: "        # TODO: Implement is_anagram\n        return False",
                // For design problems with __init__:
                // { "name": "__init__", "signature": "(self, capacity: int) -> None", "body": "        # TODO: Initialize\n        pass" }
            },
        ],
    },

    // === TEST HELPER METHODS ===
    _test_helper_methods: {
        // Use _test_helper_methods wrapper for cookiecutter lists
        list: [
            { name: "setup_method", parameters: "", body: "self.solution = Solution()" },
            // Empty list for design problems: []
        ],
    },

    // === TEST METHODS ===
    _test_methods: {
        // Use _test_methods wrapper for cookiecutter lists
        list: [
            {
                name: "test_is_anagram", // test_{method_name}
                signature: "(self, s: str, t: str, expected: bool)", // Method signature with type hints
                parametrize: "s, t, expected", // pytest parametrize parameters
                // For tree: "root_list, expected_list"
                // For design: "operations, inputs, expected"
                test_cases: {
                    list: [
                        "('anagram', 'nagaram', True)",
                        "('rat', 'car', False)",
                        "('listen', 'silent', True)",
                        "('hello', 'bello', False)",
                        "('', '', True)",
                        "('a', 'a', True)",
                        "('a', 'b', False)",
                        "('ab', 'ba', True)",
                        "('abc', 'bca', True)",
                        "('abc', 'def', False)",
                        "('aab', 'abb', False)",
                        "('aabbcc', 'abcabc', True)",
                        "('abcd', 'abcde', False)",
                        "('race', 'care', True)",
                        "('elbow', 'below', True)",
                        "('study', 'dusty', True)",
                        "('night', 'thing', True)",
                        "('stressed', 'desserts', True)",
                    ],
                },
                // For tree: {"list": ["([4, 2, 7, 1, 3, 6, 9], [4, 7, 2, 9, 6, 3, 1])", "([2, 1, 3], [2, 3, 1])", "([], [])"]}
                // For design: {"list": ["(['LRUCache', 'put', 'get'], [[2], [1, 1], [1]], [None, None, 1])"]}
                body: "        result = run_is_anagram(Solution, s, t)\n        assert_is_anagram(result, expected)",
                // For tree: "        result = run_invert_tree(Solution, root_list)\n        assert_invert_tree(result, expected_list)"
                // For design: "        result, _ = run_lru_cache(LRUCache, operations, inputs)\n        assert_lru_cache(result, expected)"
            },
        ],
    },

    // === PLAYGROUND NOTEBOOK ===
    // CRITICAL: Use single quotes for Python strings to avoid JSON escaping issues with Jupyter notebooks
    // Double quotes in JSON + cookiecutter + Jupyter notebook = triple escaping issues
    // ALWAYS use single quotes: s = 'hello', not s = "hello"
    playground_imports: "from helpers import run_is_anagram, assert_is_anagram\nfrom solution import Solution",
    // For tree: "from helpers import run_invert_tree, assert_invert_tree\nfrom solution import Solution\nfrom leetcode_py import TreeNode"
    // For design: "from helpers import run_lru_cache, assert_lru_cache\nfrom solution import LRUCache"
    playground_setup: "# Example test case\ns = 'anagram'\nt = 'nagaram'\nexpected = True",
    // For tree: "# Example test case\nroot_list: list[int | None] = [4, 2, 7, 1, 3, 6, 9]\nexpected_list: list[int | None] = [4, 7, 2, 9, 6, 3, 1]"
    // For design: "# Example test case\noperations = ['LRUCache', 'put', 'get']\ninputs = [[2], [1, 1], [1]]\nexpected = [None, None, 1]"
    playground_run: "result = run_is_anagram(Solution, s, t)\nresult",
    // For tree: "result = run_invert_tree(Solution, root_list)\nresult"
    // For design: "result, cache = run_lru_cache(LRUCache, operations, inputs)\nprint(result)\ncache"
    playground_assert: "assert_is_anagram(result, expected)",
    // For tree: "assert_invert_tree(result, expected_list)"
    // For design: "assert_lru_cache(result, expected)"

    // ============================================================================
    // PROBLEM TYPE VARIATIONS SUMMARY:
    // ============================================================================
    //
    // BASIC PROBLEMS (valid_anagram):
    // - solution_class_name: "Solution"
    // - solution_imports: ""
    // - Simple method signatures: "(self, s: str, t: str) -> bool"
    // - Basic test cases: structured format with {"list": ["..."]}
    // - Playground: single quotes for strings
    //
    // TREE PROBLEMS (invert_binary_tree):
    // - solution_class_name: "Solution"
    // - solution_imports: "from leetcode_py import TreeNode"
    // - Tree method signatures: "(self, root: TreeNode[int] | None) -> TreeNode[int] | None"
    // - Helper functions use TreeNode.from_list()
    // - Test cases: structured format with list representations of trees
    // - Playground: TreeNode imports and list conversions
    //
    // LINKED LIST PROBLEMS (merge_two_sorted_lists):
    // - solution_class_name: "Solution"
    // - solution_imports: "from leetcode_py import ListNode"
    // - List method signatures: "(self, list1: ListNode[int] | None, list2: ListNode[int] | None) -> ListNode[int] | None"
    // - Helper functions use ListNode.from_list()
    // - Test cases: structured format with list representations of linked lists
    // - Playground: ListNode imports and list conversions
    //
    // DESIGN PROBLEMS (lru_cache):
    // - solution_class_name: "LRUCache" (custom class name)
    // - Multiple methods including __init__
    // - Operations-based testing: structured format with operations, inputs, expected arrays
    // - Complex test body with operation loops
    // - Helper functions return (results, instance) for debugging
    // - Playground: print results, return instance
    // - test_class_content: "" (no setup_method)
    //
    // INHERITANCE PROBLEMS (implement_trie_prefix_tree):
    // - solution_class_name: "Trie(DictTree[str])" (with inheritance)
    // - solution_imports: "from leetcode_py.data_structures import DictTree, RecursiveDict"
    // - Custom class with inheritance from DictTree
    // - Operations-based testing with structured format like design problems
    // - Helper functions return (results, instance) for debugging
    //
    // MULTIPLE SOLUTIONS (invert_binary_tree, lru_cache):
    // - Add parametrize for solution classes in test files:
    //   @pytest.mark.parametrize("solution_class", [Solution, SolutionDFS, SolutionBFS])
    //   @pytest.mark.parametrize("solution_class", [LRUCache, LRUCacheWithDoublyList])
    // - Update test method signature to include solution_class parameter
    // - Import all solution classes in test file
    // ============================================================================
}

IMPORTANT: When creating the actual .json file, convert the above JSON5 to valid JSON by:

1. Remove all comments (lines starting with //)
2. Keep all quoted property names (already done above)
3. Save as .json file (not .json5)

Naming Conventions

• problem_name: snake_case (e.g., "two_sum", "valid_palindrome")
  • GOTCHA — digit-leading names break pytest collection. A slug like 3sum-smaller yields problem_name 3sum_smaller, whose package pytest cannot import (ImportError: attempted relative import with no known parent package). Fix by spelling it out per repo precedent (three_sum_smaller, like two_sum/three_sum) or, when there is no natural spelling (pure-numeric prefix like 132-pattern), shifting digits out of leading position: pattern_132 (precedent dota2_senate, number_of_1_bits)
• solution_class_name: Usually "Solution", except for design problems (e.g., "LRUCache")
• test_class_name: PascalCase (e.g., "TwoSum", "ValidPalindrome")
• method_name: snake_case (e.g., "two_sum", "is_palindrome", "character_replacement")
• parameters: Use snake_case for all parameter names

CRITICAL: Method Naming Convention

• Always convert LeetCode method names from camelCase to snake_case
• Example: characterReplacement → character_replacement
• Example: isSubtree → is_subtree
• Example: countSubstrings → count_substrings
• This ensures Python convention compliance and consistency across the codebase

PascalCase Rules for Properties

When creating JSON properties that use PascalCase (solution_class_name, test_class_name):

• Acronyms: Keep all caps (e.g., "LRUCache" not "LruCache")
• Roman numerals: Keep all caps (e.g., "ReverseLinkedListII" not "ReverseLinkedListIi")
• Common patterns: "BST", "DFS", "BFS", "API", "URL", "HTML", "JSON", "XML"

Special Problem Types

Tree Problems

• Add "solution_imports": "from leetcode_py import TreeNode"
• Use TreeNode | None for nullable tree parameters
• Test imports: Include TreeNode in test_imports
• Test setup: root = TreeNode.from_list(root_list)

GOTCHA — from_list uses COMPACT level-order semantics. None entries are skipped in the build queue: they occupy no children slots and do NOT enqueue. Padding under a null parent (e.g. trailing entries after [3, None, 2, None, 1]) is silently DROPPED — those nodes never appear in the built tree. Rules:

• Write test-case arrays in compact LeetCode form: never include children-of-null padding
• Derive each expected_list from the tree from_list actually builds, not from the array you typed — when in doubt, run TreeNode[int].from_list(...) and print the structure before finalizing the JSON
• Hand-derived inorder/postorder/expectations for construction problems (#105, #106 style) are the top source of bad test cases — verify by running the generated tests before QA; a failure there means the test data is wrong, not the solution

GOTCHA — computed expectations must be machine-verified. For any non-trivial expected output (any-order result lists, arithmetic results, big-number cases), derive expectations by RUNNING a quick reference implementation, not by hand:

python3 -c "
def ref(expr):  # reference implementation of the expected output
    ...
print(sorted(ref('1+2*3-4')))
"

Bound the verifier itself. A verification script that doesn't terminate burns a full 120s tool cycle before the kill: memoize exponential recursion (@lru_cache, 576 grid-path recursion hit 4^50), and never iterate over input magnitude (range(1, W) on a wall of total width 10^9, 554) — iterate candidate positions of interest (edges, indices) or use set/dict membership instead.

GOTCHA — never hand-transcribe verified values into the JSON. Running a separate verification script and then copying its output columns into the JSON-writing script is itself the failure point: the guess column gets copied instead of the ref column (hit twice in one batch — 974 and 983 — each costing a full regen + QA cycle). Fix: put the reference implementation INSIDE the JSON-writing script and assert every expectation before json.dump:

for tc, (inputs, expected) in zip(test_cases, cases):
    assert ref(*inputs) == expected, ("BAD", inputs, expected)

The assert fires at write time, before any p-gen/QA cycle is spent. It also catches bad hand-invented inputs the reference crashes on (988).

GOTCHA — construction-problem input pairs: generate, don't hand-invent, and make the verifier self-check. For "reconstruct from two traversals" problems (889 pre+post), hand-writing traversal PAIRS is error-prone (2 of 12 invented pairs were not valid traversals of any tree, and the failures surfaced as verifier crashes, not clean rejections). Generate pairs programmatically from random trees (build tree → emit both traversals → assert reference reconstruction round-trips), and have every verifier FIRST assert its own reference output matches the inputs (preorder_traverse(ref_result) == preorder_input) — a reference with an internal bug (local/global index mix-up) silently "verifies" garbage or crashes confusingly. Same discipline for any verifier computing expectations via index arithmetic.

GOTCHA — any-of-them TREE output needs traversal validation, not equality. When a problem returns a tree with multiple valid answers (889 Construct from Pre+Post: single-child nodes can lean left or right), exact-equality against one serialized tree fails valid solutions. Pattern: expected = [preorder_list, postorder_list]; the assert helper re-traverses the returned tree and asserts both traversals match. For exponential LISTS of trees (894 All Possible Full Binary Trees), combine with the dual-method pattern: multiset compare of to_list() serializations for small n (sort with a None-safe key like (len, str) — plain sorted crashes on None), count-only for large n.

Hand-derived values are the top source of QA test failures; each bad one costs a full regen + QA cycle to discover and fix. Also validate hand-invented INPUTS against the constraints — value ranges AND structural invariants: an input the constraints forbid (e.g. [2] where nums[i] <= n = 1) crashes the solution and reads as a solution bug, not a test-data bug, and shape guarantees bite too (827 Making A Large Island requires a square n x n grid; [[1], [1]] is 2x1 and passes all value checks — see test-quality-assurance.md). For problems whose statement guarantees a unique answer (e.g. 272 "guaranteed to have only one unique set of k values"), hand-invented inputs can violate the guarantee itself — ties at the k-boundary make the expected answer ill-posed even when it matches one valid answer. Guard in the verification script: assert the k-th and (k+1)-th candidates differ (values sorted by distance, abs(srt[k - 1] - target) != abs(srt[k] - target)).

For "return any of them" problems, the assert helper must check validity + result length, never exact equality (see largest_divisible_subset.json, course_schedule_ii.json).

GOTCHA — self-referential node classes need from __future__ import annotations. A custom Node class in solution_contents (N-ary tree, parent-pointer problems) whose own __init__ annotations reference the class (children: list[Node] | None = None) is evaluated at class-body time and fails p-gen lint with F821 Undefined name 'Node'. Set solution_imports: "from __future__ import annotations" (hit with 428; the remaining unscrapable queue has more parent-pointer/N-ary problems, so this recurs).

GOTCHA — ops-sequence (design) cases must honor the statement's BEHAVIORAL guarantees, not just the value constraints. Hand-crafted operation sequences routinely break rules plain-input cases can't: continuing after a win (348 Tic-Tac-Toe: "once a winning condition is reached, no more moves are allowed"), breaking turn alternation, or misaligning len(operations) vs len(inputs). Build the reference to ASSERT those guarantees while computing outputs (alternation, bounds, cell occupancy, no-post-win moves, length match) and construct sequences programmatically (small game(n, moves) helper) rather than hand-listing — each bad sequence costs a verification iteration and can slip through as a "valid-looking" test that the real solution would never face.