docs: add llm-assisted-problem-creation.md

wislertt · wislertt · commit ef1a42933084 · 2025-09-17T00:18:24.000+07:00
diff --git a/Makefile b/Makefile
@@ -1,5 +1,5 @@
 PYTHON_VERSION = 3.13
-PROBLEM ?= daily_temperatures
+PROBLEM ?= house_robber
 FORCE ?= 0
 COMMA := ,
 
diff --git a/README.md b/README.md
@@ -187,7 +187,11 @@ make gen-all-problems
 
 ### LLM-Assisted Problem Creation
 
-To extend the problem collection beyond the current catalog, leverage an LLM assistant within your IDE (Cursor, GitHub Copilot Chat, Amazon Q, etc.):
+To extend the problem collection beyond the current catalog, leverage an LLM assistant within your IDE (Cursor, GitHub Copilot Chat, Amazon Q, etc.).
+
+📖 **[Complete LLM-Assisted Problem Creation Guide](docs/llm-assisted-problem-creation.md)** - Comprehensive guide with screenshots and detailed workflow.
+
+**Quick Start:**
 
 ```bash
 # Problem generation commands:
@@ -240,6 +244,8 @@ poetry run python -m leetcode_py.tools.check_test_cases --threshold=10
 
 ### CLI Commands (Global)
 
+📖 **[Complete CLI Usage Guide](docs/cli-usage.md)** - Detailed documentation with all options and examples.
+
 ```bash
 # Generate problems
 lcpy gen -n 1                       # Single problem by number
diff --git a/docs/images/generated-solution.png b/docs/images/generated-solution.png
diff --git a/docs/images/generated-test.png b/docs/images/generated-test.png
diff --git a/docs/images/problems-are-generated.png b/docs/images/problems-are-generated.png
diff --git a/docs/images/prompt-with-context.png b/docs/images/prompt-with-context.png
diff --git a/docs/llm-assisted-problem-creation.md b/docs/llm-assisted-problem-creation.md
@@ -0,0 +1,144 @@
+# LLM-Assisted Problem Creation Guide
+
+This guide demonstrates how to leverage Large Language Models (LLMs) like Amazon Q, GitHub Copilot Chat, or Cursor to automatically generate new LeetCode problems for your practice environment.
+
+## Overview
+
+The LLM-assisted workflow enables you to add new problems to your collection with a simple natural language command. The AI assistant handles the entire process from scraping problem data to generating the complete problem structure with comprehensive test cases.
+
+## Prerequisites
+
+### Required LLM Context
+
+For optimal results, include these rule files in your LLM context:
+
+- [`.amazonq/rules/problem-creation.md`](../.amazonq/rules/problem-creation.md) - Complete problem generation workflow
+- [`.amazonq/rules/test-quality-assurance.md`](../.amazonq/rules/test-quality-assurance.md) - Test enhancement and reproducibility verification
+- [`.amazonq/rules/development-rules.md`](../.amazonq/rules/development-rules.md) - Code standards and testing patterns
+
+### Setup Your IDE
+
+Configure your IDE with an LLM assistant:
+
+- **Amazon Q**: Install the Amazon Q plugin
+- **GitHub Copilot**: Enable Copilot Chat
+- **Cursor**: Built-in AI assistant
+- **Other**: Any IDE with LLM integration
+
+## Quick Start
+
+### Basic Problem Addition
+
+Simply ask your LLM assistant to add a problem:
+
+![Prompt with Context](images/prompt-with-context.png)
+
+_Example prompt showing how to request a new problem with the LLM assistant_
+
+```bash
+# Simple commands that work:
+"Add problem 198. House Robber"
+"Add problem 198. House Robber. tag: grind"
+"Create problem 70. Climbing Stairs with grind-75 tag"
+```
+
+### What Happens Automatically
+
+The LLM assistant will execute the complete workflow:
+
+1. **Scrape** problem data from LeetCode
+2. **Transform** data into proper JSON template format (including images)
+3. **Create** JSON file in `leetcode_py/cli/resources/leetcode/json/problems/{problem_name}.json`
+4. **Update** `leetcode_py/cli/resources/leetcode/json/tags.json5` with specified tags
+5. **Generate** complete problem structure in `leetcode/{problem_name}/`
+6. **Verify** with linting checks (iterates from step 3 until all pass)
+
+![Problems Are Generated](images/problems-are-generated.png)
+
+_Source control view showing all files created and modified during the problem generation process_
+
+## Generated Problem Structure
+
+### Solution Template
+
+The assistant generates a clean solution template with proper type hints:
+
+![Generated Solution](images/generated-solution.png)
+
+_Generated solution.py file with TODO placeholder and proper method signature_
+
+### Comprehensive Test Suite
+
+Each problem includes 10+ test cases covering edge cases (note: generated test cases may need verification for correctness):
+
+![Generated Test](images/generated-test.png)
+
+_Generated test_solution.py with parametrized tests and comprehensive test cases_
+
+## Test Enhancement Workflow
+
+### Enhancing Existing Problems
+
+Improve test coverage for existing problems:
+
+```bash
+"Enhance test cases for two_sum problem"
+"Add more edge cases to binary_tree_inorder_traversal"
+"Fix test reproducibility for valid_palindrome"
+```
+
+### Quality Assurance
+
+The assistant can identify problems needing more test cases and verify test case correctness and reproducibility:
+
+```bash
+"Check which problems need more test cases"
+"Find problems with less than 12 test cases"
+"Verify test case correctness for house_robber"
+"Fix test reproducibility for binary_tree_inorder_traversal"
+```
+
+## Best Practices
+
+### Effective Prompts
+
+**Good prompts:**
+
+- "Add problem 198. House Robber with grind tag"
+- "Create problem 70. Climbing Stairs for grind-75"
+- "Enhance test cases for two_sum problem"
+
+**Avoid:**
+
+- Vague requests without problem numbers
+- Requests for non-existent problems
+
+## Troubleshooting
+
+### Common Issues
+
+**Template errors:**
+
+- Assistant will automatically fix JSON template issues
+- Re-runs generation until linting passes
+- If JSON template fails after many iterations, ask agent to review the example template carefully as mentioned in the rules
+
+**Test failures:**
+
+- Assistant verifies test cases against expected outputs
+- Fixes incorrect expected values
+- Use test QA workflow for comprehensive test enhancement and reproducibility verification
+
+## Integration with Development Workflow
+
+### CI/CD Compatibility
+
+Generated problems integrate seamlessly with:
+
+- **Test Reproducibility** - CI automatically verifies problems can be regenerated consistently; just implement your solution and CI handles the rest
+
+## Conclusion
+
+LLM-assisted problem creation transforms the tedious process of adding new problems into a simple natural language interaction. The assistant handles all the complexity while ensuring professional code quality and comprehensive test coverage.
+
+Start practicing with your new problems immediately - the assistant takes care of everything else!
diff --git a/leetcode/house_robber/README.md b/leetcode/house_robber/README.md
@@ -0,0 +1,38 @@
+# House Robber
+
+**Difficulty:** Medium
+**Topics:** Array, Dynamic Programming
+**Tags:** grind
+
+**LeetCode:** [Problem 198](https://leetcode.com/problems/house-robber/description/)
+
+## Problem Description
+
+You are a professional robber planning to rob houses along a street. Each house has a certain amount of money stashed, the only constraint stopping you from robbing each of them is that adjacent houses have security systems connected and **it will automatically contact the police if two adjacent houses were broken into on the same night**.
+
+Given an integer array `nums` representing the amount of money of each house, return \*the maximum amount of money you can rob tonight **without alerting the police\***.
+
+## Examples
+
+### Example 1:
+
+```
+Input: nums = [1,2,3,1]
+Output: 4
+Explanation: Rob house 1 (money = 1) and then rob house 3 (money = 3).
+Total amount you can rob = 1 + 3 = 4.
+```
+
+### Example 2:
+
+```
+Input: nums = [2,7,9,3,1]
+Output: 12
+Explanation: Rob house 1 (money = 2), rob house 3 (money = 9) and rob house 5 (money = 1).
+Total amount you can rob = 2 + 9 + 1 = 12.
+```
+
+## Constraints
+
+- `1 <= nums.length <= 100`
+- `0 <= nums[i] <= 400`
diff --git a/leetcode/house_robber/__init__.py b/leetcode/house_robber/__init__.py
diff --git a/leetcode/house_robber/helpers.py b/leetcode/house_robber/helpers.py
@@ -0,0 +1,8 @@
+def run_rob(solution_class: type, nums: list[int]):
+    implementation = solution_class()
+    return implementation.rob(nums)
+
+
+def assert_rob(result: int, expected: int) -> bool:
+    assert result == expected
+    return True
diff --git a/leetcode/house_robber/playground.py b/leetcode/house_robber/playground.py
@@ -0,0 +1,29 @@
+# ---
+# jupyter:
+#   jupytext:
+#     text_representation:
+#       extension: .py
+#       format_name: percent
+#       format_version: '1.3'
+#       jupytext_version: 1.17.3
+#   kernelspec:
+#     display_name: leetcode-py-py3.13
+#     language: python
+#     name: python3
+# ---
+
+# %%
+from helpers import assert_rob, run_rob
+from solution import Solution
+
+# %%
+# Example test case
+nums = [2, 7, 9, 3, 1]
+expected = 12
+
+# %%
+result = run_rob(Solution, nums)
+result
+
+# %%
+assert_rob(result, expected)
diff --git a/leetcode/house_robber/solution.py b/leetcode/house_robber/solution.py
@@ -0,0 +1,21 @@
+class Solution:
+    """
+    Houses: [2, 7, 9, 3, 1]
+    Can't rob adjacent houses!
+    For each house: max(skip, rob) = max(prev1, prev2 + current)
+
+    Step by step:
+    i=0: prev2=0, prev1=0, num=2 → max(0, 0+2) = 2
+    i=1: prev2=0, prev1=2, num=7 → max(2, 0+7) = 7
+    i=2: prev2=2, prev1=7, num=9 → max(7, 2+9) = 11
+    i=3: prev2=7, prev1=11, num=3 → max(11, 7+3) = 11
+    i=4: prev2=11, prev1=11, num=1 → max(11, 11+1) = 12
+    """
+
+    # Time: O(n)
+    # Space: O(1)
+    def rob(self, nums: list[int]) -> int:
+        prev2 = prev1 = 0  # prev2: max 2 ago, prev1: max 1 ago
+        for num in nums:
+            prev2, prev1 = prev1, max(prev1, prev2 + num)
+        return prev1
diff --git a/leetcode/house_robber/test_solution.py b/leetcode/house_robber/test_solution.py
@@ -0,0 +1,36 @@
+import pytest
+
+from leetcode_py import logged_test
+
+from .helpers import assert_rob, run_rob
+from .solution import Solution
+
+
+class TestHouseRobber:
+    def setup_method(self):
+        self.solution = Solution()
+
+    @logged_test
+    @pytest.mark.parametrize(
+        "nums, expected",
+        [
+            ([1, 2, 3, 1], 4),
+            ([2, 7, 9, 3, 1], 12),
+            ([1], 1),
+            ([2, 1], 2),
+            ([5, 1, 3, 9], 14),
+            ([2, 7, 9, 3, 1, 5, 8], 20),
+            ([0, 0, 0], 0),
+            ([5], 5),
+            ([1, 2], 2),
+            ([2, 1, 1, 2], 4),
+            ([5, 5, 10, 100, 10, 5], 110),
+            ([100, 1, 1, 100], 200),
+            ([1, 3, 1, 3, 100], 103),
+            ([400, 0, 400], 800),
+            ([1, 2, 3, 4, 5], 9),
+        ],
+    )
+    def test_rob(self, nums: list[int], expected: int):
+        result = run_rob(Solution, nums)
+        assert_rob(result, expected)
diff --git a/leetcode_py/cli/resources/leetcode/json/problems/house_robber.json b/leetcode_py/cli/resources/leetcode/json/problems/house_robber.json
@@ -0,0 +1,73 @@
+{
+    "problem_name": "house_robber",
+    "solution_class_name": "Solution",
+    "problem_number": "198",
+    "problem_title": "House Robber",
+    "difficulty": "Medium",
+    "topics": "Array, Dynamic Programming",
+    "_tags": { "list": ["grind"] },
+
+    "readme_description": "You are a professional robber planning to rob houses along a street. Each house has a certain amount of money stashed, the only constraint stopping you from robbing each of them is that adjacent houses have security systems connected and **it will automatically contact the police if two adjacent houses were broken into on the same night**.\n\nGiven an integer array `nums` representing the amount of money of each house, return *the maximum amount of money you can rob tonight **without alerting the police***.",
+
+    "_readme_examples": {
+        "list": [
+            {
+                "content": "```\nInput: nums = [1,2,3,1]\nOutput: 4\nExplanation: Rob house 1 (money = 1) and then rob house 3 (money = 3).\nTotal amount you can rob = 1 + 3 = 4.\n```"
+            },
+            {
+                "content": "```\nInput: nums = [2,7,9,3,1]\nOutput: 12\nExplanation: Rob house 1 (money = 2), rob house 3 (money = 9) and rob house 5 (money = 1).\nTotal amount you can rob = 2 + 9 + 1 = 12.\n```"
+            }
+        ]
+    },
+
+    "readme_constraints": "- `1 <= nums.length <= 100`\n- `0 <= nums[i] <= 400`",
+
+    "helpers_imports": "",
+    "helpers_content": "",
+    "helpers_run_name": "rob",
+    "helpers_run_signature": "(solution_class: type, nums: list[int])",
+    "helpers_run_body": "    implementation = solution_class()\n    return implementation.rob(nums)",
+    "helpers_assert_name": "rob",
+    "helpers_assert_signature": "(result: int, expected: int) -> bool",
+    "helpers_assert_body": "    assert result == expected\n    return True",
+
+    "solution_imports": "",
+    "solution_contents": "",
+    "solution_class_content": "",
+
+    "test_imports": "import pytest\nfrom leetcode_py import logged_test\nfrom .helpers import assert_rob, run_rob\nfrom .solution import Solution",
+    "test_content": "",
+    "test_class_name": "HouseRobber",
+    "test_class_content": "    def setup_method(self):\n        self.solution = Solution()",
+
+    "_solution_methods": {
+        "list": [
+            {
+                "name": "rob",
+                "signature": "(self, nums: list[int]) -> int",
+                "body": "        # TODO: Implement rob\n        return 0"
+            }
+        ]
+    },
+
+    "_test_helper_methods": {
+        "list": [{ "name": "setup_method", "parameters": "", "body": "self.solution = Solution()" }]
+    },
+
+    "_test_methods": {
+        "list": [
+            {
+                "name": "test_rob",
+                "signature": "(self, nums: list[int], expected: int)",
+                "parametrize": "nums, expected",
+                "test_cases": "[([1, 2, 3, 1], 4), ([2, 7, 9, 3, 1], 12), ([1], 1), ([2, 1], 2), ([5, 1, 3, 9], 14), ([2, 7, 9, 3, 1, 5, 8], 20), ([0, 0, 0], 0), ([5], 5), ([1, 2], 2), ([2, 1, 1, 2], 4), ([5, 5, 10, 100, 10, 5], 110), ([100, 1, 1, 100], 200), ([1, 3, 1, 3, 100], 103), ([400, 0, 400], 800), ([1, 2, 3, 4, 5], 9)]",
+                "body": "        result = run_rob(Solution, nums)\n        assert_rob(result, expected)"
+            }
+        ]
+    },
+
+    "playground_imports": "from helpers import run_rob, assert_rob\nfrom solution import Solution",
+    "playground_setup": "# Example test case\nnums = [2, 7, 9, 3, 1]\nexpected = 12",
+    "playground_run": "result = run_rob(Solution, nums)\nresult",
+    "playground_assert": "assert_rob(result, expected)"
+}
diff --git a/leetcode_py/cli/resources/leetcode/json/tags.json5 b/leetcode_py/cli/resources/leetcode/json/tags.json5
@@ -78,7 +78,7 @@
         "zero_one_matrix",
     ],
 
-    grind: [{ tag: "grind-75" }, "daily_temperatures"],
+    grind: [{ tag: "grind-75" }, "daily_temperatures", "house_robber"],
 
     // Test tag for development and testing
     test: ["binary_search", "two_sum", "valid_palindrome"],
